Skip to content

Latest commit

 

History

History
228 lines (186 loc) · 7.96 KB

README.md

File metadata and controls

228 lines (186 loc) · 7.96 KB
Raw

mkdocs-include-markdown-plugin

Mkdocs Markdown includer plugin.

PyPI Tests Coverage status

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

Make sure that you define include-markdown before other plugins that could conflict, like mkdocs-macros-plugin.

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 %}.

The rest of the options 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: true
      trailing_newlines: false
      comments: false

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 absolute or relative to the path of the file that includes them. This argument also accept globs, in which case certain paths can be ignored using the exclude argument.

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