Mkdocs Markdown includer plugin.
Mkdocs Markdown includer plugin.
Read this document in other languages:
pip install mkdocs-include-markdown-plugin
Enable the plugin in your mkdocs.yml
:
plugins:
- include-markdown
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-->
# opening_tag and
closing_tag: The default opening and closing tags. By default are
{%
and %}
.
plugins:
- include-markdown:
opening_tag: "{!"
closing_tag: "!}"
# exclude: Define global exclusion wildcard patterns. Relative paths defined here will be relative to the docs/ directory.
plugins:
- include-markdown:
exclude:
- LICENSE.md
- api/**
# cache: Define a 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.
You can include it in the installation of the plugin adding the cache
extra:
# requirements.txt
mkdocs-include-markdown-plugin[cache]
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:
./
or ../
).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.
{% %}
template. Possible values are
true
and false
.true
and false
.utf-8
will be used.true
and false
.<!-- BEGIN INCLUDE -->
and <!-- END INCLUDE -->
comments which help to identify that the content has been included. Possible
values are true
and false
.#
) heading syntax. Accepts
negative values to drop leading #
characters.{%
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="../*.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.
{% %}
template. Possible values are
true
and false
.true
and false
.utf-8
will be used.~~~yaml
{% include "../examples/github-minimal.yml" %}
~~~
{%
include "../examples.md"
start="~~~yaml"
end="~~~\n"
%}
{%
include '**'
exclude='./*.md'
%}