Skip to main content

Mkdocs Markdown includer plugin.

Project description

mkdocs-include-markdown-plugin

PyPI License Tests Coverage status

Mkdocs Markdown includer plugin.

Read this document in other languages:

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_include_markdown_plugin-5.1.0.tar.gz (19.2 kB view hashes)

Uploaded Source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page