Single Source using Snippets

Single source in documentation is taking all or part of another topic and inserting it into another topic. Why would you do this? To standardize or reuse a piece of content in many different topics. This could be a company statement that must be the same in any topic used. Maybe a reminder to create a backup. Even third party application version support. By single sourcing this content, you can change the source material and have it update all topics using the source file the next time you build your documentation.

The snippet feature in MkDocs allows you to single source content in a file. The following is a snippet from a file. The snippet is highlighted using a codeblock to make it easier to see.

This is a snippet.

Lorem ipsum dolor sit amet consectetur adipiscing elit.
Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam quis nostrud exercitation ullamco.
Laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit.
Esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident.
Sunt in culpa qui officia deserunt mollit anim id est laborum.

You can insert selected lines for a snippet. The following is the same snippet as above, just lines 4-6.

Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam quis nostrud exercitation ullamco.
Laboris nisi ut aliquip ex ea commodo consequat.

Using Snippets

The following is an example of adding an entire markdown file as a snippet.

--8← ./docs/features/example1.md --8←

The following is an example of adding specific lines from a markdown file as a snippet. This example shows including lines 4 through 6 from a file.

--8← ./docs/features/example1.md:4:6 --8←