DOCSEARCHbyAlgolia
Submit Docs

mkdocs-include-markdown-plugin

repository·master·Indexed 41 days ago

https://github.com/mondeja/mkdocs-include-markdown-plugin

A MkDocs plugin (version 7.3.0) that allows including content from local files or remote URLs into Markdown documentation using custom directives. It provides two primary tags: `{% include-markdown %}` for processing content as Markdown with support for heading offsets and dedenting, and `{% include %}` for including raw text. Both directives support start/end markers for selective inclusion, glob patterns for multiple files, and HTTP request caching for remote content.

Tokens
12.5K
Snippets
70
Records
73
Agent score
96%

What's inside mkdocs-include-markdown-plugin

  1. Difference between include-markdown and include tags

    master

    The plugin provides two primary ways to include content from other files:

    1. {% include-markdown 'path/to/file.md' ... %}: This tag includes the content and processes it as Markdown. This is necessary if the included file contains Markdown syntax (like headers, bold text, or lists) that you want to be rendered correctly in the final output.

    2. {% include 'path/to/file.md' ... %}: This tag includes the content as raw text without Markdown processing. Use this when you want to include content exactly as it is, without the plugin attempting to parse its syntax.

    Both tags support parameters like start, end, and dedent to control how the content is extracted and formatted.

    {# Process as Markdown}
{% include-markdown 'included.md' start='<!--start-->' end='<!--end-->' dedent=true heading-offset=2 %}

{# Include as raw text}
{% include 'included.md' start='<!--start-->' end='<!--end-->' trailing-newlines=false %}

  2. Difference between `include` and `include-markdown` tags

    master

    The plugin provides two primary ways to include content from other files:

    1. {% include 'filename' %}: This is a standard include. It treats the included content as raw text/content without necessarily re-processing it through the Markdown parser in the same way as the parent document. It is useful for simple text inclusions.
    2. {% include-markdown 'filename' %}: This tag is specifically designed to include Markdown content. It allows for advanced processing such as dedent (removing leading whitespace) and heading-offset (adjusting the level of headings within the included content). Use this when you want the included file to be treated as a proper Markdown fragment that integrates into your document structure.

    Commonly used options for include-markdown include:

    • start: A marker to define the beginning of the content to include.
    • end: A marker to define the end of the content to include.
    • dedent: Boolean to remove indentation from the included content.
    • heading-offset: An integer to shift the heading levels (e.g., if the included file has # headings, an offset of 2 will turn them into ### in the parent document).
    {# Standard include #}
{% include 'included.md' start='<!--start-->' end='<!--end-->' trailing-newlines=false %}

{# Markdown-specific include with processing #}
{% include-markdown 'included.md' start='<!--start-->' end='<!--end-->' dedent=true heading-offset=2 %}

  3. Install platformdirs to run HTTP cache examples

    master

    To run the HTTP cache examples provided in this repository, you must have the platformdirs package installed in your environment. This dependency is required for the cache functionality to work correctly.

    pip install platformdirs

  8. Configure global plugin settings

    master

    You can customize the global behavior of the plugin in mkdocs.yml. Common settings include encoding, indentation behavior, and URL rewriting.

    Note: To use the cache feature for remote URLs, you must either install the [cache] extra via pip (pip install mkdocs-include-markdown-plugin[cache]) to provide the platformdirs dependency, or manually define a cache_dir.

    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

  10. Exclude specific files from inclusion using include-markdown

    master

    When using the {% include-markdown %} or {% include %} tags, you can prevent specific files from being processed by using the exclude option. This is useful for skipping index files, license files, or other metadata files when performing a bulk inclusion (e.g., using a glob pattern like **).

    To exclude multiple files, use brace expansion syntax within the path string, such as ./{index,license}.md.

    {% include-markdown "**" exclude="./{index,license}.md" %}
{% include "**" exclude="./{index,license}.md" %}

  11. Include raw content with options

    master

    The {% include %} tag allows you to include content from another file. Unlike include-markdown, this is typically used for raw content or when you don't need the specific Markdown processing features of the other tag. You can control trailing whitespace using the trailing-newlines option.

    • start: The marker where the inclusion begins.
    • end: The marker where the inclusion ends.
    • trailing-newlines: If set to false, it prevents extra newlines at the end of the included content.

    Example usage:

    {% include 'included.md' start='<!--start-->' end='<!--end-->' trailing-newlines=false %}