mkdocs-include-markdown-plugin 5.1.0

Mkdocs Markdown includer plugin.

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

Configuration

The global behaviour of the plugin can be customized in the configuration.

• # opening_tag and closing_tag: The default opening and closing tags. By default are {% and %}.

Most of the settings will define the default values passed to arguments of directives and are documented in the reference.

plugins:
  - include-markdown:
      opening_tag: "{!"
      closing_tag: "!}"
      encoding: ascii
      preserve_includer_indent: false
      dedent: false
      trailing_newlines: true
      comments: true
      rewrite_relative_urls: true
      heading_offset: 0
      start: <!--start-->
      end: <!--end-->
      exclude: LICENSE.md

The cache setting defines a expiration time in seconds for HTTP requests when including from URLs.

plugins:
  - include-markdown:
      cache: 600

In order to use this feature, the dependency platformdirs must be installed. You can include it in the installation of the plugin adding the cache extra:

# requirements.txt
mkdocs-include-markdown-plugin[cache]

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 either:

• Local files with absolute or relative paths to the file that includes them.
• Globs matching multiples files, in which case certain paths can be ignored using the exclude argument.
• URLs to include remote content.

File paths to include and string arguments can be wrapped by double " or single ' quotes, which can be escaped prepending them a \ character as \" and \'.

The arguments start and end may contain usual (Python-style) escape sequences like \n to match against newlines.

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.
• # exclude: Specify with a glob which files should be ignored. Only useful when passing globs to include multiple files.
• # trailing-newlines (true): When this option is disabled, the trailing newlines found in the content to include are stripped. Possible values are true and false.
• # encoding (utf-8): Specify the encoding of the included file. If not defined utf-8 will be used.
• # 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 or decreases the Markdown headings depth by this number. Only supports number sign (#) heading syntax. Accepts negative values to drop leading # characters.

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*"
   start="<!--license \"start\" -->"
   end='<!--license "end" -->'
   exclude="../LICENSE*.rst"
%}

{% include-markdown '/escap\'ed/single-quotes/in/file\'/name.md' %}

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.
• # trailing-newlines (true): When this option is disabled, the trailing newlines found in the content to include are stripped. Possible values are true and false.
• # encoding (utf-8): Specify the encoding of the included file. If not defined utf-8 will be used.

Examples

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

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

{%
   include '../LICENSE*'
   exclude='../LICENSE*.rst'
%}

Acknowledgment

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