snippets

Includes external files into Markdown using the --8<-- syntax, so you can share reusable fragments (files, scripts, notices) across pages.

Usage

Inline single-line include:

--8<-- "includes/notice.md"

Block include of multiple files:

--8<--
includes/header.md
includes/footer.md
--8<--

Paths are resolved against the configured base_path entries (and the project root). The conventional <project-root>/snippets directory is always searched as well, so a file placed at snippets/notice.md can be included as --8<-- "notice.md" with no configuration.

Parameterized includes

Includes can also take key="value" arguments. Any ${key} placeholder in the included file is replaced with the supplied value (HTML-escaped). Because this form is not line-anchored, it can be used mid-line — for example inside a table cell:

| --8<-- "ebay.html" text="Some Product" url="https://ebay.us/abc" | 1 | $40.61 |

With snippets/ebay.html containing:

<a href="${url}" class="ebay-affiliate-link">${text}</a>

The included content is trimmed to a single inline fragment so it won't break the surrounding Markdown (tables, prose, etc.).

Named sections

Include only a marked region of a file by appending :section to the path. In the source file, wrap the region in start/end markers:

<!-- in includes/sample.py -->
# --8<-- [start:setup]
import os
config = os.environ
# --8<-- [end:setup]

Then include just that section from any page:

--8<-- "includes/sample.py:setup"

Only the lines between the matching [start:setup] and [end:setup] markers are included; the marker lines themselves are stripped. This mirrors pymdownx.snippets sections.

Options

{
  "name": "snippets",
  "options": {
    "base_path": [ ".", "docs/_include/files", "docs/snippets" ]
  }
}

Attribution

Behavior is modeled on pymdownx.snippets by @facelessuser (MIT). See Attributions.