myst-substitutions

A small MyST plugin that replaces Nunjucks-style {{ var }} tokens using values from project config and page frontmatter.

Define a value once and reuse it across your documentation.

Basic usage¶

Enable by adding the .mjs file for the latest release of this plugin in your myst.yml plugins configuration:

project:
  plugins:
    - https://github.com/choldgraf/myst-substitutions/releases/download/v0.1/index.mjs

Define key/value pairs in project or page metadata:

---
substitutions:
  myvar: "**Wow!**"
---

Then insert it with {{ var }} syntax in your MyST markdown:

Here's a styled variable: {{ myvar }}.

Here are a few examples of how to use it:

Welcome to {{ site_name }}.

Style variables in their definition: {{ brand_emphasis }}.

Or style them in your content: **{{ site_name }}**.

This even works in headers:

### Header variable: {{ site_name }}

Configuration¶

Define substitutions at either the project-level (in myst.yml), or in page frontmatter. Page-level configuration over-rides project-level configuration. Here are examples from these docs:

project:
  title: "MyST Substitutions"
  github: https://github.com/choldgraf/myst-substitutions
  plugins:
    - ../dist/index.mjs
    - https://raw.githubusercontent.com/jupyter-book/myst-plugins/main/plugins/demo/src/index.mjs
  substitutions:
    brand_emphasis: "**MyST Docs**"
    version: "v1.3"
    site_name: "MyST Docs"
    release_channel: "stable"
    items:
      - name: "Alice"
        role: "Chair"
      - name: "Bob"

---
substitutions:
  version: "v2.0"
  meeting_date: "2025-02-01"
  meeting_date_literal: "`2025-02-01`"
  release_channel: "preview"
---

Page-level over-rides¶

Override or add values per page with frontmatter. This page sets version, meeting_date, and overrides release_channel.

Latest release: {{ version }}.

Next meeting: {{ meeting_date }}.

Channel for this page: {{ release_channel }}.

Nunjucks filters¶

Nunjucks Filters work too:

Shout it: {{ site_name | upper }}!

Fancy filters: {{ site_name | replace("Docs", "is totally cool") | upper }}

Multi-line substitutions with the {substitution} directive¶

Use the {substitution} directive for multi-line content like lists and tables that can’t be expressed inline:

:::{substitution}
{% for item in items %}
- **{{ item.name }}** — {{ item.role }}
{% endfor %}
:::

This works with tables too:

:::{substitution}
| Name | Role |
| --- | --- |
{% for item in items %}| {{ item.name }} | {{ item.role }} |
{% endfor %}
:::

Known limitations¶

• You cannot insert content that isn’t part of the base mystmd package (e.g. roles defined in extra extensions, like {button} won’t work until MyST transforms have the ability to re-use the mystmd parser.)