A plugin for MkDocs that adds the ability to include snippets in your documentation.
MIT License
This plugin allows you to include snippets into your mkdocs documentation.
snippets_dir
.mike
!pip install mkdocs-snippets
pip install mkdocs-exclude
(recommended)
Consider adding the plugins to a requirements.txt
file alongside other Python dependencies for your project.
Add the plugin to your mkdocs.yml
file:
It is recommended to use the mkdocs-exclude
plugin to exclude the snippet directory from the documentation build.
This will save you from a lot of warnings about files that are not referenced in the nav
configuration.
plugins:
- search
- exclude:
glob:
- snippets/*
- snippets
The plugin will load snippets from the default directory snippets
which must be inside your documentation directory.
It is allowed to have any amount of files and subdirectories inside the snippet directory.
These files must be in the YAML format.
mySnippet: |-
This is a snippet.
It can contain multiple lines.
# |- is the YAML Multiline Indicator
myOtherSnippet: |-
This is another snippet.
All top level keys in the snippet file are treated as snippets. Every key is a snippet ID.
The default snippet syntax is @Snippet:snippetFile:snippetID@
.
Internal documentation links in snippets are automatically converted to relative links based on where the snippet is used. This allows you to use documentation links in your snippets without having to worry that the snippet might be used in a directory in which the link does not work. Therefore, links in the snippet must be written as if they were in the root of the documentation directory.
Consider the following documentation structure (docs/
is the documentation's root directory):
docs/API/Overview.md
docs/API/Client/Cookbook.md
A snippet would look like this:
mySnippet: |-
This is a snippet.
It contains a link to the [API Overview](API/Overview.md).
myOtherSnippet: |-
This is another snippet.
It contains a link to the [Client API Cookbook](API/Client/Cookbook.md).
No leading slashes or relative paths are allowed. The file type (.md
) must be specified.
The snippets can now be used in any file without the links breaking.
If you want to customize the snippet syntax or directory, you can do so by adding the following configuration:
plugins:
- search
- snippets:
directory: "mySnippetDirectory"
delimiter: "|"
identifier: "snip"
divider_char: ">"