Customization

Tip

At the moment, only certain aspects of MkDocs Mad Libs are easily configurable. If there are other components you feel should be customizable, please enter a feature request.

Overriding the default styling

MkDocs Mad Libs relies on CSS styling to style the contenteditable element used for user input. This CSS styling is added to your MkDocs site via an extra stylesheet (see: Add custom CSS dependency).

To override the default styling, modify the .madlibs-editable and/or .madlibs-editable-icon CSS classes, where .madlibs-editable applies to the editable text, and .madlibs-editable-icon applies to the pen SVG icon adjacent to the text.

Use the default styling as a reference for defining your own styling: extra.css.

Syncing variables

MkDocs Mad Libs adds a data-original-content data-* attribute that can be used in a JavaScript EventListener to sync inputs within a document that share a variable name.

Add custom Javascript dependency

Follow the general mkdocs-material instructions for adding custom JavaScript.

mkdocs.yml

extra_javascript:
    - javascripts/extra.js

Add an event listener

Using the data-original-content attribute that is added to all mad Libs content, you can add an event listener to sync variables that share the same original content:

extra.js

document.addEventListener("input", function (event) {
    // Check if the event target has the "madlibs-editable" class
    if (event.target.classList.contains("madlibs-editable")) {
        const updatedText = event.target.textContent.trim();
        const originalText = event.target.getAttribute("data-original-text");

        // Update all other elements with the same original text
        if (originalText) {
            const elements = document.querySelectorAll(
                `.madlibs-editable[data-original-text="${originalText}"]`
            );
            elements.forEach((el) => {
                if (el !== event.target) {
                    // Update only the text content while keeping the SVG intact
                    const svgElement = el.querySelector("svg");
                    const textNode = [...el.childNodes].find(node => node.nodeType === Node.TEXT_NODE);

                    if (textNode) {
                        textNode.textContent = updatedText;
                    } else {
                        el.insertBefore(document.createTextNode(updatedText), svgElement);
                    }
                }
            });
        }
    }
});

Note

This example EventListener is provided courtesy of Paweł Krupa .

Example usage

Using the EventListener above syncs inputs that share a name, such as in this example:

print("If you edit me HERE, you will also update me HERE!")

Controlling user inputs

MkDocs Mad Libs uses the contenteditable HTML attribute to make code snippets editable. By default, this enables users to create any valid content within the <span> tag.

To control what keyboard inputs are valid for a user to make use of, you can add a JavaScript EventListener.

Add custom Javascript dependency

Follow the general mkdocs-material instructions for adding custom JavaScript.

mkdocs.yml

extra_javascript:
    - javascripts/extra.js

Select all the Mad Libs HTML content

Using the madlibs-editable class that is added to all Mad Libs editable content, you can select all the elements that need to be modified.

extra.js

let madlibsEditableContent = document.querySelectorAll(".madlibs-editable");

Add an event listener

Using the editable content elements queried from the HTML document, add an event listener for the keydown event.

extra.js

let madlibsEditableContent = document.querySelectorAll(".madlibs-editable");

for (i = 0; i < madlibsEditableContent.length; i++) {
    madlibsEditableContent[i].addEventListener("keydown", event => {
        console.log(event)
    });
};

Add logic to restrict the user inputs

Use the KeyboardEvent objects to apply constraints of your choosing, for example:

extra.js

let madlibsEditableContent = document.querySelectorAll(".madlibs-editable");

for (i = 0; i < madlibsEditableContent.length; i++) {
    madlibsEditableContent[i].addEventListener("keydown", event => {
        // prevent the user from backspacing if the content is empty
        if (event.key == "Backspace" && event.target.textContent === "") {
            event.preventDefault()
        };
        // prevent the user from adding newlines
        if (event.key == "Enter") {
            event.preventDefault()
        };
    });
};