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.

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

plugins:
  - include-markdown:
      encoding: ascii
      preserve_includer_indent: false
      dedent: false
      trailing_newlines: true
      comments: true
      rewrite_relative_urls: true
      heading_offset: 0
      start: <!--start-->
      end: <!--end-->
      recursive: true

`opening_tag` and `closing_tag`

Default opening and closing tags. When not specified they are {% and %}.

plugins:
  - include-markdown:
      opening_tag: "{!"
      closing_tag: "!}"

`exclude`

Global exclusion wildcard patterns. Relative paths defined here will be
relative to the docs_dir directory.

plugins:
  - include-markdown:
      exclude:
        - LICENSE.md
        - api/**

`cache`

Expiration time in seconds for cached HTTP requests when including from URLs.

plugins:
  - include-markdown:
      cache: 600

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

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

`cache_dir`

Directory where cached HTTP requests will be stored. If set, platformdirs is not
needed to be installed to use cache.

plugins:
  - include-markdown:
      cache: 600
      cache_dir: ./mkdocs-include-markdown-cache

A .gitignore file will be added to the cache directory if not exists to avoid
committing the cache files.

`directives`

Customize the names of the directives.

plugins:
  - include-markdown:
      directives:
        include-markdown: include-md
        include: replace

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:

URLs to include remote content.
Local files:
- Absolute paths (starting with a path separator).
- Relative from the file that includes them (starting with ./ or ../).
- Relative to the docs_dir directory. For instance if your docs_dir is
  ./docs/, then includes/header.md will match the file
  ./docs/includes/header.md.
Bash wildcard globs matching multiple local files.

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.
#
recursive (true): When this option is disabled, included files are not
processed for recursive includes. 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 (false): When this option is enabled, the content to include
is wrapped by  and  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 'includes/header.md'
    start='<!--\n\ttable-start\n-->'
    end='<!--\n\ttable-end\n-->'
    rewrite-relative-urls=false
    comments=true
%}

{%
    include-markdown "includes/header.md"
    heading-offset=1
%}

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

{%
    include-markdown "**"
    exclude="./{index,LICENSE}.md"
%}

{% 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.
#
recursive (true): When this option is disabled, included files are not
processed for recursive includes. 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 '**'
    exclude='./*.md'
%}

Acknowledgment

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

Dependencies of mkdocs-include-markdown-plugin (3).
Dependency	Optional
mkdocs	false
wcmatch	false
platformdirs	true

Package profile

mkdocs-include-markdown-plugin

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description