An extension of the mkdocs-simple-plugin that adds syntax for including content from other files
Go to file
Glen Whitney 4a4241a4e4
continuous-integration/drone/push Build is passing Details
continuous-integration/drone/tag Build is passing Details
continuous-integration/drone Build is passing Details
chore: Update to mkdocs-simple v2.1.2 (#23)
Note the upstream refactor from mkdocs-simple v1 -> v2 was fairly large, so
  this is a rather larger update than most. And in fact one feature of
  mkdocs-semiliterate (universal markdown extraction) was incorporated into
  mkdocs-simple, so the initialization of this plugin is noticeably simplified
  as a result.

  Also updates mkdocs to 1.4.

Co-authored-by: Glen Whitney <>
Reviewed-on: #23
2022-11-09 20:52:47 +00:00
assets feat: Add `extract_on_copy` option 2022-07-12 12:14:41 -07:00
mkdocs_semiliterate chore: Update to mkdocs-simple v2.1.2 (#23) 2022-11-09 20:52:47 +00:00
tests chore: Update to mkdocs-simple v2.1.2 (#23) 2022-11-09 20:52:47 +00:00
.drone.yml chore: Update to mkdocs-simple v2.1.2 (#23) 2022-11-09 20:52:47 +00:00
.gitignore feat: Implement double-quoted filename features. (#13) 2021-02-12 17:11:07 +00:00
LICENSE Initial commit 2021-01-08 04:10:06 +00:00 chore: Update to mkdocs-simple v2.1.2 (#23) 2022-11-09 20:52:47 +00:00
mkdocs.yml chore: Update to mkdocs-simple v2.1.2 (#23) 2022-11-09 20:52:47 +00:00
pyproject.toml chore: initialize setuptools project 2021-01-07 22:39:40 -08:00
setup.cfg chore: Update to mkdocs-simple v2.1.2 (#23) 2022-11-09 20:52:47 +00:00

Dreaming of integrated documentation MkDocs semiliterate Plugin

This plugin for MkDocs is an extension of Allison Thackston's excellent mkdocs-simple-plugin. It allows you to include content from one file into another (via {! ... !} syntax), using exactly the same extraction specification that the simple plugin already uses for identifying documentation in source files.


Time and trends have not validated Knuth's original vision of "literate programming" as a mainstream practice. Nevertheless, there remain significant advantages to incorporating all documentation, including user-guide-style narrative, into the source code for a project. These advantages include ease of maintenance and synchronization of code and documentation, and opportunities to make the ensemble of your code and documentation more DRY. Thus, it's worth using a "semiliterate" programming style, in which

  • code is arranged as dictated by best software engineering practices
  • documentation is co-located in the same files next to the implementing code
  • and tools are provided for extracting and assembling that documentation into readable form.

*[DRY]: Don't Repeat Yourself -- a coding philosophy of creating a single authoritative location for each piece of information.

The simple plugin goes a long way toward creating a semiliterate programming environment. However, in creating narrative documentation, it's very useful to be able to quote or incorporate content --- whether that be documentation blocks or code examples or code that itself serves as documentation to avoid repeating information --- from one file into another. To satisfy that need, this semiliterate plugin extends (i.e, literally inherits from) the simple plugin and adds a syntax for such inclusion.

With a few other small ease-of-use tweaks (documented in the Usage section), this extended plugin aims to produce a lightweight but comprehensive semiliterate programming environment. The documentation site is, of course, produced by MkDocs using the semiliterate plugin.


The mkdocs-semiliterate package which provides the semiliterate plugin for MkDocs is available via PyPI:

python3 -m pip install mkdocs-semiliterate

or of course if your pip is already set up to use a Python 3.5 (or later) installation, just

pip install mkdocs-semiliterate

License and Acknowledgments

This software is licensed under Apache 2.0. Icons8 provided the icon.