Skip to content

Mkdocs Simple Plugin

A plugin for MkDocs that builds a documentation website from markdown content interspersed within your code, in markdown files or in block comments in your source files.

simple will search your project directory tree for documentation. By default, Markdown files and graphics files will be copied to your documentation site. Source files will also be searched for markdown embedded in minimally-structured comment blocks; these will be extracted into additional markdown files included in the documentation site.

Installation

Install the plugin with pip.

pip install mkdocs-simple-plugin

Python 3.x, 3.7, 3.8, 3.9, 3.10 supported.

Settings

Create a mkdocs.yml file in the root of your directory and add the simple plugin to its plugin list.

site_name: "My site"
plugins:
- search:
- simple:

Defaults

include_folders:
- '*'
ignore_folders: []
ignore_hidden: true
merge_docs_dir: true
build_docs_dir: ''
include_extensions:
- .bmp
- .tif
- .tiff
- .gif
- .svg
- .jpeg
- .jpg
- .jif
- .jfif
- .jp2
- .jpx
- .j2k
- .j2c
- .fpx
- .pcd
- .png
- .pdf
- CNAME
- .snippet
- .pages
semiliterate:
- pattern: \.py$
  extract:
  - start: ^\s*"""\W?md\b
    stop: ^\s*"""\s*$
  - start: ^\s*#+\W?md\b
    stop: ^\s*#\s?\/md\s*$
    replace:
    - ^\s*# ?(.*\n?)$
    - ^.*$
- pattern: \.(cpp|cc?|hh?|hpp|js|css)$
  extract:
  - start: ^\s*/\*+\W?md\b
    stop: ^\s*\*\*/\s*$
  - start: ^\s*\/\/+\W?md\b
    stop: ^\s*\/\/\send\smd\s*$
    replace:
    - ^\s*\/\/\s?(.*\n?)$
    - ^.*$
- pattern: Dockerfile$|\.(dockerfile|ya?ml|sh)$
  extract:
  - start: ^\s*#+\W?md\b
    stop: '#\s\/md\s*$'
    replace:
    - ^\s*#?\s?(.*\n?)$
- pattern: \.(html?|xml)$
  extract:
  - start: <!--\W?md\b
    stop: -->\s*$

Note

If you add your own settings but want to also use any of these, you must reiterate the settings you want in your mkdocs.yml file.

Example usage (defaults)

Python

block comments starting with: """md

"""md
This is a documentation comment.
"""

line comments starting with: # md and ending with # /md, stripping leading spaces and `#``, and only capturing comment lines.

# md
# This is a documentation comment.
# /md

C, C++, and Javascript

block comments starting with: /** md

/** md
This is a documentation comment.
**/

in line comments starting with // md, ending with // end md, stripping leading spaces and //, and only capturing comment lines.

// md
// This is a documentation comment.
// end md

YAML, Dockerfiles, and shell scripts

line-comment blocks starting with # md and ending with # /md, stripping leading spaces and #

# md
# This is a documentation comment.
# /md

HTML and xml

line-comment blocks starting with <!-- md and ending with -->

<!-- md
This is a documentation comment.
-->

Configuration scheme

include_folders

Directories whose name matches a glob pattern in this list will be searched for documentation

ignore_folders

Directories whose name matches a glob pattern in this list will NOT be searched for documentation.

ignore_hidden

Hidden directories will not be searched if this is true.

merge_docs_dir

If true, the contents of the docs directory (if any) will be merged at the same level as all other documentation. Otherwise, the docs directory will be retained as a subdirectory in the result.

build_docs_dir

If set, the directory where docs will be coallated to be build. Otherwise, the build docs directory will be a temporary directory.

include_extensions

Any file in the searched directories whose name contains a string in this list will simply be copied to the generated documentation.

semiliterate

The semiliterate settings allows the extraction of markdown from inside source files. It is defined as a list of blocks of settings for different filename patterns (typically matching filename extensions). All regular expression parameters use ordinary Python re syntax.

pattern

Any file in the searched directories whose name contains this required regular expression parameter will be scanned.

destination

By default, the extracted documentation will be copied to a file whose name is generated by removing the (last) extension from the original filename, if any, and appending .md. However, if this parameter is specified, it will be expanded as a template using the match object from matching "pattern" against the filename, to produce the name of the destination file.

terminate

If specified, all extraction from the file is terminated when a line containing this regexp is encountered (whether or not any extraction is currently active per the parameters below). The last matching group in the terminate expression, if any, is written to the destination file; note that "start" and "stop" below share that same behavior.

extract

This parameter determines what will be extracted from a scanned file that matches the pattern above. Its value should be a block or list of blocks of settings.

start

(optional) The regex pattern to indicate the start of extraction.

Only the first mode whose start expression matches is activated, so at most one mode of extraction can be active at any time. When an extraction is active, lines from the scanned file are copied to the destination file (possibly modified by the "replace" parameter below).

Additionally, start can specify an output path for the extracted content. Simply add file=output_path.md to the start token line.

Example:

# md file=ouput_path.md

Note

The (last) extraction mode (if any) with no start parameter is active beginning with the first line of the scanned file; there is no way such a mode can be reactivated if it stops. This convention allows for convenient "front-matter" extraction.

stop

(optional) The regex pattern to indicate the stop of extraction.

The simple plugin will begin searching for further occurrences of start expressions on the next line of the scanned file.

replace

The replace parameter allows extracted lines from a file to be transformed in simple ways by regular expressions, for example to strip leading comment symbols if necessary.

The replace parameter is a list of substitutions to attempt. Each substitution is specified either by a two-element list of a regular expression and a template, or by just a regular expression.

Once one of the replace patterns matches, processing stops; no further expressions are checked.

Build

Then, you can build the mkdocs from the command line.

mkdocs build

Run a local server

One of the best parts of mkdocs is the ability to serve (and update!) your documentation site locally.

mkdocs serve