Includes/Snippets¶

You can include the contents of other files directly within your current page using snippets. This comes in handy for admonitions and other content that you want to write once and then use repeatedly. Rather than copying and pasting, you only need to refer back to the original file.

You can see an example of this on the Meta section index page, which includes includes/section-placeholder.md (source link).

How to¶

Shared snippets live in the includes/ folder at the root of the repo, outside of docs/, so they never show up as pages of their own.

To include one in a page, put the following on its own line, using just the filename:

example.md

--8<-- "section-placeholder.md"

You don’t need any ../ to find the file, no matter how deep in docs/ your page is.

Tip

If the snippet file doesn’t exist (for example, because of a typo in the filename), the build fails with an error, so a broken include can’t sneak onto the live site.

Note

To show the snippet syntax on a page without it being replaced (like in the example above), add a ; in front of it: ;--8<--. See the Snippets documentation for more details.