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.8, 3.9, 3.10, 3.11 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: null
folders:
- '*'
ignore_folders: null
ignore:
- venv
- .cache/**
- .devcontainer/**
- .github/**
- .vscode/**
- '**/__pycache__/**'
- .git/**
- '*.egg-info'
ignore_hidden: null
merge_docs_dir: true
build_docs_dir: null
build_dir: ''
copy: false
include_extensions: null
include:
- '*.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 (renamed)
Renamed folders
folders
Directories whose name matches a glob pattern in this list will be searched for documentation
ignore_folders (renamed)
Renamed ignore
ignore
Directories whose name matches a glob pattern in this list will NOT be searched for documentation.
ignore_hidden (deprecated)
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 (renamed)
Renamed build_dir
build_dir
If set, the directory where docs will be collated to be build. Otherwise, the build docs directory will be a temporary directory.
copy
If set, docs will be copied to the build_docs_dir. Otherwise, files will be used in place.
include_extensions (renamed)
Renamed include
include
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