Glen Whitney
2235af160c
Also includes installation and development documentation, and updates to the latest development version of mkdocs-simple-plugin. Resolves #3.
18 lines
2.0 KiB
Markdown
18 lines
2.0 KiB
Markdown
# MkDocs semiliterate Plugin
|
|
|
|
This plugin for MkDocs is an extension of Allison Thackston's excellent [mkdocs-simple-plugin](https://athackst.github.io/mkdocs-simple-plugin). It adds `{! ... !}` syntax for including content from one file into another (and a couple of other small ease-of-use tweaks).
|
|
|
|
## Rationale
|
|
|
|
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 mkdocs-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 -- 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. <!-- repo: -->The<!-- site:This --> documentation site is, of course, produced by MkDocs using the semiliterate plugin.
|
|
|
|
## License
|
|
|
|
This software is licensed under [Apache 2.0](LICENSE).
|