<!-- mdpo-disable-next-line -->
# mkdocs-include-markdown-plugin
<!-- mdpo-disable -->
[![PyPI][pypi-version-badge-link]][pypi-link]
[![License][license-image]][license-link]
[![Tests][tests-image]][tests-link]
[![Coverage status][coverage-image]][coverage-link]
<!-- mdpo-enable -->
Mkdocs Markdown includer plugin.
<!-- mdpo-disable -->
<!-- mdpo-enable-next-line -->
> Read this document in other languages:
>
> - [Español][es-readme-link]
> - [Français][fr-readme-link]
<!-- mdpo-enable -->
## Installation
```bash
pip install mkdocs-include-markdown-plugin
```
## Documentation
### Setup
Enable the plugin in your `mkdocs.yml`:
```yaml
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](#reference).
```yaml
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`
Default opening and closing tags. When not specified they are `{%` and `%}`.
```yaml
plugins:
- include-markdown:
opening_tag: "{!"
closing_tag: "!}"
```
<!-- mdpo-disable-next-line -->
#### `exclude`
Global exclusion wildcard patterns. Relative paths defined here will be
relative to the [`docs_dir`] directory.
```yaml
plugins:
- include-markdown:
exclude:
- LICENSE.md
- api/**
```
<!-- mdpo-disable-next-line -->
#### `cache`
Expiration time in seconds for cached HTTP requests when including from URLs.
```yaml
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:
```txt
# 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:
- 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.
<!-- mdpo-disable-next-line -->
#### **`include-markdown`**
Includes Markdown files content, optionally using two delimiters to filter the
content to include.
- <a name="include-markdown_start" href="#include-markdown_start">#</a>
**start**: Delimiter that marks the beginning of the content to include.
- <a name="include-markdown_end" href="#include-markdown_end">#</a>
**end**: Delimiter that marks the end of the content to include.
- <a name="include-markdown_preserve-includer-indent" href="#include-markdown_preserve-includer-indent">#</a>
**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`.
- <a name="include-markdown_dedent" href="#include-markdown_dedent">#</a>
**dedent** (_false_): If enabled, the included content will be dedented.
- <a name="include-markdown_exclude" href="#include-markdown_exclude">#</a>
**exclude**: Specify with a glob which files should be ignored. Only useful
when passing globs to include multiple files.
- <a name="include-markdown_trailing-newlines" href="#include-markdown_trailing-newlines">#</a>
**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`.
- <a name="include-markdown_encoding" href="#include-markdown_encoding">#</a>
**encoding** (_utf-8_): Specify the encoding of the included file.
If not defined `utf-8` will be used.
- <a name="include-markdown_rewrite-relative-urls" href="#include-markdown_rewrite-relative-urls">#</a>
**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`.
- <a name="include-markdown_comments" href="#include-markdown_comments">#</a>
**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`.
- <a name="include-markdown_heading-offset" href="#include-markdown_heading-offset">#</a>
**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
```jinja
{%
include-markdown "../README.md"
start="<!--intro-start-->"
end="<!--intro-end-->"
%}
```
```jinja
{%
include-markdown 'includes/header.md'
start='<!--\n\ttable-start\n-->'
end='<!--\n\ttable-end\n-->'
rewrite-relative-urls=false
comments=false
%}
```
```jinja
{%
include-markdown "includes/header.md"
heading-offset=1
%}
```
```jinja
{%
include-markdown "../LICENSE*"
start="<!--license \"start\" -->"
end='<!--license "end" -->'
exclude="../*.rst"
%}
```
```jinja
{%
include-markdown "**"
exclude="./{index,LICENSE}.md"
%}
```
```jinja
{% include-markdown '/escap\'ed/single-quotes/in/file\'/name.md' %}
```
<!-- mdpo-disable-next-line -->
#### **`include`**
Includes the content of a file or a group of files.
- <a name="include_start" href="#include_start">#</a>
**start**: Delimiter that marks the beginning of the content to include.
- <a name="include_end" href="#include_end">#</a>
**end**: Delimiter that marks the end of the content to include.
- <a name="include_preserve-includer-indent" href="#include_preserve-includer-indent">#</a>
**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`.
- <a name="include_dedent" href="#include_dedent">#</a>
**dedent** (_false_): If enabled, the included content will be dedented.
- <a name="include_exclude" href="#include_exclude">#</a>
**exclude**: Specify with a glob which files should be ignored. Only useful
when passing globs to include multiple files.
- <a name="include_trailing-newlines" href="#include_trailing-newlines">#</a>
**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`.
- <a name="include_encoding" href="#include_encoding">#</a>
**encoding** (_utf-8_): Specify the encoding of the included file.
If not defined `utf-8` will be used.
##### Examples
```jinja
~~~yaml
{% include "../examples/github-minimal.yml" %}
~~~
```
```jinja
{%
include "../examples.md"
start="~~~yaml"
end="~~~\n"
%}
```
```jinja
{%
include '**'
exclude='./*.md'
%}
```
## Acknowledgment
- Joe Rickerby and contributors for
[giving me the permissions][cibuildwheel-470] to separate this plugin from the
documentation of [cibuildwheel][cibuildwheel-repo-link].
[Bash wildcard globs]: https://facelessuser.github.io/wcmatch/glob/#syntax
<!-- mdpo-disable -->
[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin
[pypi-version-badge-link]: https://img.shields.io/pypi/v/mkdocs-include-markdown-plugin?logo=pypi&logoColor=white
[tests-image]: https://img.shields.io/github/actions/workflow/status/mondeja/mkdocs-include-markdown-plugin/ci.yml?logo=github&label=tests&branch=master
[tests-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/actions?query=workflow%3ACI
[coverage-image]: https://img.shields.io/codecov/c/github/mondeja/mkdocs-include-markdown-plugin?logo=codecov&logoColor=white
[coverage-link]: https://app.codecov.io/gh/mondeja/mkdocs-include-markdown-plugin
[license-image]: https://img.shields.io/pypi/l/mkdocs-include-markdown-plugin?color=light-green&logo=apache&logoColor=white
[license-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/LICENSE
[platformdirs]: https://pypi.org/project/platformdirs/
[cibuildwheel-470]: https://github.com/pypa/cibuildwheel/issues/470
[cibuildwheel-repo-link]: https://github.com/pypa/cibuildwheel
[es-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/es/README.md
[fr-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/fr/README.md
[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-include-markdown-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "\u00c1lvaro Mond\u00e9jar Rubio <mondejar1994@gmail.com>",
"keywords": "includer, markdown, mkdocs, plugin",
"author": "Joe Rickerby",
"author_email": "\u00c1lvaro Mond\u00e9jar Rubio <mondejar1994@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/17/ca/1a5c0fb22557e806b6d54672aab5a256af49e305705bb10354da4f0fcd85/mkdocs_include_markdown_plugin-6.0.6.tar.gz",
"platform": null,
"description": "<!-- mdpo-disable-next-line -->\n\n# mkdocs-include-markdown-plugin\n\n<!-- mdpo-disable -->\n\n[![PyPI][pypi-version-badge-link]][pypi-link]\n[![License][license-image]][license-link]\n[![Tests][tests-image]][tests-link]\n[![Coverage status][coverage-image]][coverage-link]\n\n<!-- mdpo-enable -->\n\nMkdocs Markdown includer plugin.\n\n<!-- mdpo-disable -->\n<!-- mdpo-enable-next-line -->\n\n> Read this document in other languages:\n>\n> - [Espa\u00f1ol][es-readme-link]\n> - [Fran\u00e7ais][fr-readme-link]\n\n<!-- mdpo-enable -->\n\n## Installation\n\n```bash\npip install mkdocs-include-markdown-plugin\n```\n\n## Documentation\n\n### Setup\n\nEnable the plugin in your `mkdocs.yml`:\n\n```yaml\nplugins:\n - include-markdown\n```\n\n### Configuration\n\nThe global behaviour of the plugin can be customized in the configuration.\n\nMost of the settings will define the default values passed to arguments\nof directives and are documented in the [reference](#reference).\n\n```yaml\nplugins:\n - include-markdown:\n encoding: ascii\n preserve_includer_indent: false\n dedent: false\n trailing_newlines: true\n comments: true\n rewrite_relative_urls: true\n heading_offset: 0\n start: <!--start-->\n end: <!--end-->\n```\n\n#### `opening_tag` and `closing_tag`\n\nDefault opening and closing tags. When not specified they are `{%` and `%}`.\n\n```yaml\nplugins:\n - include-markdown:\n opening_tag: \"{!\"\n closing_tag: \"!}\"\n```\n\n<!-- mdpo-disable-next-line -->\n\n#### `exclude`\n\nGlobal exclusion wildcard patterns. Relative paths defined here will be\nrelative to the [`docs_dir`] directory.\n\n```yaml\nplugins:\n - include-markdown:\n exclude:\n - LICENSE.md\n - api/**\n```\n\n<!-- mdpo-disable-next-line -->\n\n#### `cache`\n\nExpiration time in seconds for cached HTTP requests when including from URLs.\n\n```yaml\nplugins:\n - include-markdown:\n cache: 600\n```\n\nIn order to use this feature, the dependency [platformdirs] must be installed.\nYou can include it in the installation of the plugin adding the `cache` extra:\n\n```txt\n# requirements.txt\nmkdocs-include-markdown-plugin[cache]\n```\n\n### Reference\n\nThis plugin provides two directives, one to include Markdown files and another\nto include files of any type.\n\nPaths of included files can be either:\n\n- URLs to include remote content.\n- Local files:\n - Absolute paths (starting with a path separator).\n - Relative from the file that includes them (starting with `./` or `../`).\n - Relative to the [`docs_dir`] directory. For instance if your `docs_dir` is\n _./docs/_, then `includes/header.md` will match the file\n _./docs/includes/header.md_.\n- [Bash wildcard globs] matching multiple local files.\n\nFile paths to include and string arguments can be wrapped by double `\"` or\nsingle `'` quotes, which can be escaped prepending them a `\\` character as\n`\\\"` and `\\'`.\n\nThe arguments **start** and **end** may contain usual (Python-style) escape\nsequences like `\\n` to match against newlines.\n\n<!-- mdpo-disable-next-line -->\n\n#### **`include-markdown`**\n\nIncludes Markdown files content, optionally using two delimiters to filter the\ncontent to include.\n\n- <a name=\"include-markdown_start\" href=\"#include-markdown_start\">#</a>\n **start**: Delimiter that marks the beginning of the content to include.\n- <a name=\"include-markdown_end\" href=\"#include-markdown_end\">#</a>\n **end**: Delimiter that marks the end of the content to include.\n- <a name=\"include-markdown_preserve-includer-indent\" href=\"#include-markdown_preserve-includer-indent\">#</a>\n **preserve-includer-indent** (_true_): When this option is enabled (default),\n every line of the content to include is indented with the same number of\n spaces used to indent the includer `{% %}` template. Possible values are\n `true` and `false`.\n- <a name=\"include-markdown_dedent\" href=\"#include-markdown_dedent\">#</a>\n **dedent** (_false_): If enabled, the included content will be dedented.\n- <a name=\"include-markdown_exclude\" href=\"#include-markdown_exclude\">#</a>\n **exclude**: Specify with a glob which files should be ignored. Only useful\n when passing globs to include multiple files.\n- <a name=\"include-markdown_trailing-newlines\" href=\"#include-markdown_trailing-newlines\">#</a>\n **trailing-newlines** (_true_): When this option is disabled, the trailing newlines\n found in the content to include are stripped. Possible values are `true` and `false`.\n- <a name=\"include-markdown_encoding\" href=\"#include-markdown_encoding\">#</a>\n **encoding** (_utf-8_): Specify the encoding of the included file.\n If not defined `utf-8` will be used.\n- <a name=\"include-markdown_rewrite-relative-urls\" href=\"#include-markdown_rewrite-relative-urls\">#</a>\n **rewrite-relative-urls** (_true_): When this option is enabled (default),\n Markdown links and images in the content that are specified by a relative URL\n are rewritten to work correctly in their new location. Possible values are\n `true` and `false`.\n- <a name=\"include-markdown_comments\" href=\"#include-markdown_comments\">#</a>\n **comments** (_true_): When this option is enabled (default), the content to\n include is wrapped by `<!-- BEGIN INCLUDE -->` and `<!-- END INCLUDE -->`\n comments which help to identify that the content has been included. Possible\n values are `true` and `false`.\n- <a name=\"include-markdown_heading-offset\" href=\"#include-markdown_heading-offset\">#</a>\n **heading-offset** (0): Increases or decreases the Markdown headings depth\n by this number. Only supports number sign (`#`) heading syntax. Accepts\n negative values to drop leading `#` characters.\n\n##### Examples\n\n```jinja\n{%\n include-markdown \"../README.md\"\n start=\"<!--intro-start-->\"\n end=\"<!--intro-end-->\"\n%}\n```\n\n```jinja\n{%\n include-markdown 'includes/header.md'\n start='<!--\\n\\ttable-start\\n-->'\n end='<!--\\n\\ttable-end\\n-->'\n rewrite-relative-urls=false\n comments=false\n%}\n```\n\n```jinja\n{%\n include-markdown \"includes/header.md\"\n heading-offset=1\n%}\n```\n\n```jinja\n{%\n include-markdown \"../LICENSE*\"\n start=\"<!--license \\\"start\\\" -->\"\n end='<!--license \"end\" -->'\n exclude=\"../*.rst\"\n%}\n```\n\n```jinja\n{%\n include-markdown \"**\"\n exclude=\"./{index,LICENSE}.md\"\n%}\n```\n\n```jinja\n{% include-markdown '/escap\\'ed/single-quotes/in/file\\'/name.md' %}\n```\n\n<!-- mdpo-disable-next-line -->\n\n#### **`include`**\n\nIncludes the content of a file or a group of files.\n\n- <a name=\"include_start\" href=\"#include_start\">#</a>\n **start**: Delimiter that marks the beginning of the content to include.\n- <a name=\"include_end\" href=\"#include_end\">#</a>\n **end**: Delimiter that marks the end of the content to include.\n- <a name=\"include_preserve-includer-indent\" href=\"#include_preserve-includer-indent\">#</a>\n **preserve-includer-indent** (_true_): When this option is enabled (default),\n every line of the content to include is indented with the same number of\n spaces used to indent the includer `{% %}` template. Possible values are\n `true` and `false`.\n- <a name=\"include_dedent\" href=\"#include_dedent\">#</a>\n **dedent** (_false_): If enabled, the included content will be dedented.\n- <a name=\"include_exclude\" href=\"#include_exclude\">#</a>\n **exclude**: Specify with a glob which files should be ignored. Only useful\n when passing globs to include multiple files.\n- <a name=\"include_trailing-newlines\" href=\"#include_trailing-newlines\">#</a>\n **trailing-newlines** (_true_): When this option is disabled, the trailing newlines\n found in the content to include are stripped. Possible values are `true` and `false`.\n- <a name=\"include_encoding\" href=\"#include_encoding\">#</a>\n **encoding** (_utf-8_): Specify the encoding of the included file.\n If not defined `utf-8` will be used.\n\n##### Examples\n\n```jinja\n~~~yaml\n{% include \"../examples/github-minimal.yml\" %}\n~~~\n```\n\n```jinja\n {%\n include \"../examples.md\"\n start=\"~~~yaml\"\n end=\"~~~\\n\"\n %}\n```\n\n```jinja\n{%\n include '**'\n exclude='./*.md'\n%}\n```\n\n## Acknowledgment\n\n- Joe Rickerby and contributors for\n [giving me the permissions][cibuildwheel-470] to separate this plugin from the\n documentation of [cibuildwheel][cibuildwheel-repo-link].\n\n[Bash wildcard globs]: https://facelessuser.github.io/wcmatch/glob/#syntax\n\n<!-- mdpo-disable -->\n\n[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin\n[pypi-version-badge-link]: https://img.shields.io/pypi/v/mkdocs-include-markdown-plugin?logo=pypi&logoColor=white\n[tests-image]: https://img.shields.io/github/actions/workflow/status/mondeja/mkdocs-include-markdown-plugin/ci.yml?logo=github&label=tests&branch=master\n[tests-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/actions?query=workflow%3ACI\n[coverage-image]: https://img.shields.io/codecov/c/github/mondeja/mkdocs-include-markdown-plugin?logo=codecov&logoColor=white\n[coverage-link]: https://app.codecov.io/gh/mondeja/mkdocs-include-markdown-plugin\n[license-image]: https://img.shields.io/pypi/l/mkdocs-include-markdown-plugin?color=light-green&logo=apache&logoColor=white\n[license-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/LICENSE\n[platformdirs]: https://pypi.org/project/platformdirs/\n[cibuildwheel-470]: https://github.com/pypa/cibuildwheel/issues/470\n[cibuildwheel-repo-link]: https://github.com/pypa/cibuildwheel\n[es-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/es/README.md\n[fr-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/fr/README.md\n[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir\n",
"bugtrack_url": null,
"license": null,
"summary": "Mkdocs Markdown includer plugin.",
"version": "6.0.6",
"project_urls": {
"Bug tracker": "https://github.com/mondeja/mkdocs-include-markdown-plugin/issues",
"Changelog": "https://github.com/mondeja/mkdocs-include-markdown-plugin/releases",
"Documentation": "https://github.com/mondeja/mkdocs-include-markdown-plugin#documentation",
"Source": "https://github.com/mondeja/mkdocs-include-markdown-plugin"
},
"split_keywords": [
"includer",
" markdown",
" mkdocs",
" plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b636e191c1a7e4408f280adbfb986550f2f56ba1b2859111d5229f33bb4a578e",
"md5": "f0007b348ada0c5da9787b645645091f",
"sha256": "7ccafbaa412c1e5d3510c4aff46d1fe64c7a810c01dace4c636253d1aa5bc193"
},
"downloads": -1,
"filename": "mkdocs_include_markdown_plugin-6.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f0007b348ada0c5da9787b645645091f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23184,
"upload_time": "2024-05-02T00:46:20",
"upload_time_iso_8601": "2024-05-02T00:46:20.021942Z",
"url": "https://files.pythonhosted.org/packages/b6/36/e191c1a7e4408f280adbfb986550f2f56ba1b2859111d5229f33bb4a578e/mkdocs_include_markdown_plugin-6.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "17ca1a5c0fb22557e806b6d54672aab5a256af49e305705bb10354da4f0fcd85",
"md5": "7994fb777384268624afb621588fd55c",
"sha256": "7c80258b2928563c75cc057a7b9a0014701c40804b1b6aa290f3b4032518b43c"
},
"downloads": -1,
"filename": "mkdocs_include_markdown_plugin-6.0.6.tar.gz",
"has_sig": false,
"md5_digest": "7994fb777384268624afb621588fd55c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19978,
"upload_time": "2024-05-02T00:46:22",
"upload_time_iso_8601": "2024-05-02T00:46:22.769915Z",
"url": "https://files.pythonhosted.org/packages/17/ca/1a5c0fb22557e806b6d54672aab5a256af49e305705bb10354da4f0fcd85/mkdocs_include_markdown_plugin-6.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-02 00:46:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mondeja",
"github_project": "mkdocs-include-markdown-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-include-markdown-plugin"
}
JSON
