mkdocs-include-markdown-plugin

[![PyPI][pypi-version-badge-link]][pypi-link] [![License][license-image]][license-link] [![Tests][tests-image]][tests-link] [![Coverage status][coverage-image]][coverage-link] [![Downloads][downloads-image]][downloads-link]

Mkdocs Markdown includer plugin.

Read this document in other languages:

> - [Español][es-readme-link]

- [Français][fr-readme-link]

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
      order: alpha-path

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

include_from_url

Allow including content from URLs.

plugins:
  - include-markdown:
      include_from_url: true

Reference

This plugin provides two directives, one to include Markdown files and another to include files of any type.

Common arguments

Paths of included files can be either:

• URLs to include remote content.
• Local files:

• [Bash wildcard globs] matching multiple local files.

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.

• #

• #

• #

##### 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"
    order="name"
%}

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

{%
    include-markdown "**"
    order="-natural-extension"
%}

include

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

##### Examples

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

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

{%
    include '**'
    exclude='./*.md'
    order='random'
%}

Acknowledgment

• [Joe Rickerby] and [contributors] for

[Bash wildcard globs]: https://facelessuser.github.io/wcmatch/glob/#syntax

[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 [downloads-image]: https://img.shields.io/pypi/dm/mkdocs-include-markdown-plugin [downloads-link]: https://pepy.tech/project/mkdocs-include-markdown-plugin [platformdirs]: https://pypi.org/project/platformdirs/ [cibuildwheel-470]: https://github.com/pypa/cibuildwheel/issues/470 [cibuildwheel-475]: https://github.com/pypa/cibuildwheel/pull/475 [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 [Joe Rickerby]: https://github.com/joerick [contributors]: https://github.com/mondeja/mkdocs-include-markdown-plugin/graphs/contributors