smk4664 / mkdocs-include-markdown-plugin

Mkdocs Markdown includer plugin

mkdocs-include-markdown-plugin

Mkdocs Markdown includer plugin.

Status

Installation

pip install mkdocs-include-markdown-plugin

Documentation

Setup

Enable the plugin in your mkdocs.yml:

plugins:
  - include-markdown

Reference

This plugin provides two directives, one to include markdown files and another to include files of any type. Paths of included files can be absolute or relative to the path of the file that includes them:

include-markdown

Includes markdown file content, optionally using two delimiters to filter the content to include.

• start: Delimiter that marks the beginning of the content to include.
• end: Delimiter that marks the end of the content to include.
• preserve_includer_indent (true): When this option is enabled (default), every line of the content to include is indented with the same number of spaces used to indent the includer {% %} template. Possible values are true and false.
• dedent (false): If enabled, the included content will be dedented.
• rewrite_relative_urls (true): When this option is enabled (default), Markdown links and images in the content that are specified by a relative URL are rewritten to work correctly in their new location. Possible values are true and false.
• comments (true): When this option is enabled (default), the content to include is wrapped by <!-- BEGIN INCLUDE --> and <!-- END INCLUDE --> comments which help to identify that the content has been included. Possible values are true and false.

Note that the start and end strings may contain usual (Python-style) escape sequences like \n, which is handy if you need to match on a multi-line start or end trigger.

Examples

{%
   include-markdown "../README.md"
   start="<!--intro-start-->"
   end="<!--intro-end-->"
%}

{%
   include-markdown "docs/includes/header.md"
   start="<!--\n\ttable-start\n-->"
   end="<!--\n\ttable-end\n-->"
   rewrite_relative_urls=false
   comments=false
%}

include

Includes the content of a file.

• start: Delimiter that marks the beginning of the content to include.
• end: Delimiter that marks the end of the content to include.
• preserve_includer_indent (true): When this option is enabled (default), every line of the content to include is indented with the same number of spaces used to indent the includer {% %} template. Possible values are true and false.
• dedent (false): If enabled, the included content will be dedented.

Note that the start and end strings may contain usual (Python-style) escape sequences like \n, which is handy if you need to match on a multi-line start or end trigger.

Examples

~~~yaml
{% include "../examples/github-minimal.yml" %}
~~~

    {%
      include "../examples/__main__.py"
      start="~~~yaml"
      end="~~~\n"
    %}

Acknowledgment

• Joe Rickerby and contributors for giving me the permissions to separate this plugin from the documentation of cibuildwheel.