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.

Usage

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:

Example usage (defaults)

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

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

block comments starting with <!-- md and ending with -->

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

Inline parameters

Inline parameters configure a block's extraction.

These parameters should be on the same line as the start block.

For example:

 /**md file="new_name.md" trim=2 content="^\s*\/\/\s?(.*)$"

Set output file name

Filename is relative to the folder of the file being processed.

file=<name>

Trim the front of a line

Useful for removing leading spaces.

trim=#

Capture content

Regex expression to capture content, otherwise all lines are captured.

content=<regex>

Stop capture

Regex expression to indicate capture should stop.

stop=<regex>

Ignoring files

You can add a .mkdocsignore file to ignore a directory or files by glob pattern.

See example mkdocsignore usage

Default settings

Below are the default settings of the plugin.

include_folders:
- '*'
ignore_folders: []
ignore_hidden: true
merge_docs_dir: true
build_docs_dir: ''
include_extensions:
- .bmp
- .tif
- .tiff
- .gif
- .svg
- .jpeg
- .jpg
- .jif
- .jiff
- .jp2
- .jpx
- .j2k
- .j2c
- .fpx
- .pcd
- .png
- .pdf
- CNAME
- .snippet
- .pages
semiliterate:
- pattern: ^LICENSE$
- pattern: .*
  terminate: ^\W*md-ignore
  extract:
  - start: ^\s*"""\W?md\b
    stop: ^\s*"""\s*$
  - start: ^\s*#+\W?md\b
    stop: ^\s*#\s?\/md\s*$
    replace:
    - ^\s*# ?(.*\n?)$
    - ^.*$
  - start: ^\s*/\*+\W?md\b
    stop: ^\s*\*\*/\s*$
  - start: ^\s*\/\/+\W?md\b
    stop: ^\s*\/\/\send\smd\s*$
    replace:
    - ^\s*\/\/\s?(.*\n?)$
    - ^.*$
  - 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.

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 collated 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 processed into the destination file.

Note

The (last) extraction mode (if any) with no start parameter is active starting at the first line of the scanned file; there is no way this 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.

After the extraction has stopped, the file will continue to be searched for matching patterns starting with the next line of the scanned file. In this way the entire file will be processed looking for start-stop pairs.

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

You can build mkdocs from the command line using the standard command

mkdocs build

or you can generate and build at the same time see generator.

Run a local server

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

mkdocs serve