mkdocs-include-markdown-plugin

Mkdocs Markdown includer plugin.

Read this document in other languages:

• Español
• Français

Installation

pip install mkdocs-include-markdown-plugin

Documentation

Setup

Enable the plugin in your mkdocs.yml:

plugins:
  - include-markdown

Make sure that you define include-markdown before other plugins that could conflict, like mkdocs-macros-plugin.

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. This argument also accept globs, in which case certain paths can be ignored using the exclude argument:

include-markdown

Includes Markdown files 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.
• heading-offset (0): Increases the Markdown heading depth by this number. Only supports number sign (#) heading syntax. Max offset of 5.
• exclude: Specify with a glob which files should be ignored. Only useful when passing globs to include multiple files.

Note that 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-markdown "docs/includes/header.md"
   heading-offset=1
%}

{%
   include-markdown "../LICENSE*.md"
   start="<!--license-start-->"
   end="<!--license-end-->"
   exclude="../LICENSE*.rst"
%}

include

Includes the content of a file or a group of files.

• 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.
• exclude: Specify with a glob which files should be ignored. Only useful when passing globs to include multiple files.

Note that 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"
    %}

{%
   include "../LICENSE*.md"
   exclude="../LICENSE*.rst"
%}

Acknowledgment

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