Usage

Installation

You can install latest release with pip:

python3 -m pip install mkdocs-placeholder-plugin

If you want to use the (sometimes very unstable) bleeding edge version, see the README on GitHub.

Configuration

Register plugin

Add the plugin to your mkdocs.yml:

plugins:
  - search
  - placeholder

If you have no plugins entry in your config file yet, you will likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set.

More information about plugins in the MkDocs documentation.

Defining placeholders

Add a placeholder-plugin.yaml in the root of your MkDocs project and define the placeholder names and initial values here. For example:

placeholders:
  NAME: John Doe
  PLUGIN: MkDocs Placeholder Plugin
  RATING: great
  YEAR: 2023
  RANDOM: 5

Ideally you only use capital letters and underscores in your placeholders. Other characters may be interpreted as markdown syntax or lead to syntax highlighting splitting the placeholder. If that happens, the placeholder replacement will fail. Leading and trailing underscores should not be used, since they are reserved for future features.

Using placeholders

Now you can use the placeholders you defined using the following xPLACEHOLDER_NAMEx format. Example text:

Hi, I am xNAMEx and I think that xPLUGINx is xRATINGx!

Changing placeholder values

By default an table with input fields for all editable placeholders used on the page is added to the top of each page. If the page has no placeholders, this table is hidden. You can disable the automatic insertion of tables by disabling the auto_placeholder_tables option (see configuration).

Inline editors

Starting with version 0.5.0 you can also edit placeholders inline with the editable replacement method. For checkbox or dropdown placeholders, clicking on where the placeholder is embedded in the page will switch it to the next possible value. For textbox placeholders, the value will become editable like a text field.

If you do not like this behavior by default, there are two ways to disable it:

• If you set inline_editors to false in your placeholder config file, inline editors will be disabled by default, but can be turned in by the page's visitors in the placeholder settings.
• If you set normal_is_alias_for to dynamic, only placeholders embedded by the editable syntax (default ePLACEHOLDERe) will be editable.

Below you can see inline editors for different placeholder types. Hovering over them will show information about the placeholder and how to use the inline editor via a tooltip.

Input table

You can manually insert placeholder tables like the ones generated by default with the following syntax:

<div class="auto-input-table" data-hide-empty data-columns="description-or-name,input"></div>

Using a <div> and the auto-input-table class is mandatory. If you include the data-hide-empty attribute, the table will be hidden if it would be empty.

The data-columns attribute specifies a list of columns to include in the table. Valid column names for data-columns are:

• description: Shows the placeholder's description (if available)
• description-or-name: Shows the placeholders description. If none exists, the placeholders name is shown instead.
• input: Shows an input element, that can be used to change the placeholder's value
• name: Shows the placeholder's name
• value: Shows the placeholder's expanded value

Input field

You can create an input field (that will change a placeholder's value) with the following syntax:

<input data-input-for="PLACEHOLDER_NAME">

For example:

<label>Your name: <input data-input-for="NAME"></label>

All inputs tagged this way will get assigned the class input-for-variable, so that you can more easily style them with CSS. This works for the normal textbox fields and special types (checkbox, dropdown).

Textbox field

Unless otherwise specified, the input field will be a regular textbox that allows the user to specify arbitrary values. So for example if you have the following in your placeholder-plugin.yaml, the input field will be a textbox:

placeholders:
  LINK:
    default: https://www.example.com/test/page

The default field's value will be used as the default for the placeholder. You can apply the new value by changing the text in the text box and pressing Enter (if reload_on_change is enabled, which it is by default).

Live demo

Checkbox field

You can also define placeholders that have only two different values. They can be represented by a check box.

You can define them in your placeholder-plugin.yaml like this:

placeholders:
  QUOTE_CHECKBOX:
    description: Use double quotes?
    default: checked
    values:
      checked: "\""
      unchecked: "'"

You can use the placeholder's value as you can use any other placeholder. If the checkbox is checked, the value defined under values.checked is used. Otherwise values.unchecked is used. To determine, whether it is checked by default, you set default to checked or unchecked. If default is not specified or empty, unchecked is used.

Live demo

Dropdown field

Dropdown fields allow the user to select one of a list of predefined options. They are defined like this:

placeholders:
  DROPDOWN:
    description: An test dropdown for selecting your favourite DNS lookup tool
    default: "DNS lookup with host"
    values:
      "DNS lookup with dig": "dig"
      "DNS lookup with nmap": "nmap -n --resolve-all"
      "DNS lookup with host": "host"
      "DNS lookup with nslookup": "nslookup"

The possible values are defined in values: Each key specifies the displayed option's text, while the value will be assigned to the placeholder. You can specify the option to select by default, by passing the corresponding display name to default. If this is not done, the first option will be selected by default.

Live demo

Placeholder settings

Any placeholder input table (div with class auto-input-table) will have a gear icon in the top right corner. Clicking it will toggle displaying the user specific placeholder settings.

You can also include the settings by injecting an element like the following in your page:

<div class="placeholder-settings-panel"></div>

My recommendation is putting in in a (collapsible) admonition like the following to easily show where is begins and ends and set it apart from the rest og the page:

???+ note "Placeholder settings"

    <div class="placeholder-settings-panel"></div>

Live demo