mondeja / mkdocs-include-markdown-plugin

Mkdocs Markdown includer plugin

mkdocs-include-markdown-plugin

Mkdocs Markdown includer plugin.

Read this document in other languages:

• Español
• Français

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-->

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. 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:

• 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.

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 'includes/header.md'
   start='<!--\n\ttable-start\n-->'
   end='<!--\n\ttable-end\n-->'
   rewrite-relative-urls=false
   comments=false
%}

{%
   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"
%}

{% 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 '**'
   exclude='./*.md'
%}

Acknowledgment

• Joe Rickerby and contributors for giving me the permissions to separate this plugin from the documentation of cibuildwheel.

mkdocs-include-markdown-plugin's Issues

Move development environment to Hatch

[Feature-Request] Including of other files in .yml

User-Story
As a user, i'd like to separate the navigation sections into separate .yml files. This would help me when updating or extending the navigation with navigation items. In bigger applications it'd be confusing to maintain hundreds of lines of indent-dependent code.

Example
Currently, everything has to be defined in one file (mkdocs.yml).

nav:
    - Project 1
        - 1. Introduction: 'ref-to-markdown-file.md'
        - 2. Quickstart: 'ref-to-markdown-file.md'
        - 3. Components:
            - 3.1 Example component
            - 3.2 Another example component
            - //...
    - Project 2
        - 1. Introduction: 'ref-to-markdown-file.md'
        - 2. Quickstart: 'ref-to-markdown-file.md'
        - 3. Components:
            - 3.1 Example component
            - 3.2 Another example component
            - //...
    - Project 3
        - 1. Introduction: 'ref-to-markdown-file.md'
        - 2. Quickstart: 'ref-to-markdown-file.md'
        - 3. Components:
            - 3.1 Example component
            - 3.2 Another example component
            - //...

It would be great if i'm able to do this:

nav:
    - Project 1: !include 'project-1/structure.yml'
    - Project 2: !include 'project-2/structure.yml'
    - Project 3: !include 'project-3/structure.yml'

Is something like this possible?

Dependency Dashboard

This issue provides visibility into Renovate updates and their statuses. Learn more

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

• Update dependency isort to v5.9.3
• Update dependency mdpo to v0.3.67
• Update dependency yamllint to v1.26.3
• Update peter-evans/create-pull-request action to v3.10.1
• Update pre-commit hook PyCQA/isort to v5.9.3
• Update pre-commit hook adrienverge/yamllint to v1.26.3
• Update dependency pre-commit to v2.14.1
• Update dependency pyupgrade to v2.25.0

---

• Check this box to trigger a request for Renovate to run again on this repository

Allow custom ordering of arguments in directives

Currently, this snippet doesn't works:

{%
  include-markdown "{filepath}"
  comments=false
  start="<!-- start -->"
  end="<!-- end -->"
%}

Must be written as:

{%
  include-markdown "{filepath}"
  start="<!-- start -->"
  end="<!-- end -->"
  comments=false
%}

NameError: name 'LiveReloadServer' is not defined while mkdocs serve.

Hello,

When development server mkdocs serve is invoked the NameError: name 'LiveReloadServer' raised.

mkdocs-include-markdown-plugin Version: 4.0.1

...
mkdocs_include_markdown_plugin/plugin.py", line 42, in _watch_included_files
    SERVER = cast(LiveReloadServer, SERVER)
                  ^^^^^^^^^^^^^^^^
NameError: name 'LiveReloadServer' is not defined

My guess is that it is caused by TYPE_CHECKING condition at plugin.py:19

best regards

Include from URL

hello

i am trying to do something like this

# included from gtihub url

{%
    include-markdown "https://raw.githubusercontent.com/timescale/timescaledb/main/README.md"
%}

is it possible? i mean its not (this way), because i've tested it and its not working, but if it is possible how can i do this?

if not, i would like to request a feature for this to be implemented.

thanks in advance.

upper bound python requirements is making the plugin impossible to install with poetry

Hi, I hope you are doing great, thanks for this amazing plugin.

I'm trying to install this plugin using poetry but because of the requires-python = ">=3.7,<3.12" line in your pyproject.tomlfile it is impossible to install the package without updating my project to have the same constraints. I'm using poetry here but I'm sure the issue will occur with other package managers as well.
The easiest solution would be to remove the <3.12 upper bound, is there a reason why it is needed?

Having several start-end tags in included page

Having several start-end tags in included page, results in including only the first appearance.

Is it possible to have more than one section included?

<!--start-tag-->
## Important Content1
<!--end-tag-->

[unimportant content]

<!--start-tag-->
## Important Content2
<!--end-tag-->

Email address is replaced when using in snippet

[contact us](mailto:[email protected]) gets replaced as [contact us](mailto:../../_whateverfolder/[email protected]) based on where the snippet is located.

Enabling this kills the search text input in the readthedocs theme

I was wondering why the cibuildwheel site has no search input. So I created a minimal reproducer mkdocs.yml

site_name: My Docs
theme:
  name: readthedocs

plugins:
  - include-markdown

With the last two lines: no search box. Without them, search box appears. Any ideas?

Normalize arguments formatting

The directive include-markdown is not consistent with the name of most of the arguments, which are defined with _ as separators (eg. preserve_includer_indent). I think that we should use - for consistency, but this is a breaking change for v3.

Code formatting question

I have a file called "test.md"

1.  This is the first number line

1.  {%
       include-markdown "./includes/content_chunk_with_code.md"
    %}

1.  If everything works as expected this should be number 3

The contents of "./includes/content_chunk_with_code.md" is this

This content chunk contains code

\```
This is my example
It is a code block
\```

With some text after it

The code block renders all the way to the left margin, and it shows on one line, not two. (Ignore/remove the "\" in the example content chunk, I had to add it to this issue allowing the back ticks to show up).

Paths relative to docs folder

The following example in the README isn't working as expected.

{%
include-markdown "docs/includes/header.md"
heading-offset=1
%}

A custom setting for the plugin (or an already existing global one?) should be set to specify docs root path, e.g.:

mkdocs.yml

plugins:
  - include-markdown:
      docs_root: 'docs'

so that each relative path is interpreted as relative to docs_root.

rewrite_relative_urls seems to be broken

rewrite_relative_urls doesn't work for me. Please find attached a simple project to reproduce the issue.

Output

$ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
WARNING  -  Documentation file 'index.md' contains a link to '../src/images/hello.png' which is not found in the documentation files.
INFO     -  Documentation built in 0.05 seconds
INFO     -  [19:41:47] Serving on http://127.0.0.1:8000/
WARNING  -  [19:41:48] "GET /pounce_teleop/ HTTP/1.1" code 404

mkdocs_test.zip

Blank code line in between included files

I am including multiple files from a main file, but there's an odd behavior that adds a blank code-block line between each of the different imported md file contents. Those md files have no extra spaces prior or after the boundary blocks, thus it's weird that it's happening; however, the issue went away by setting multiple include-markdown statements together on a same line. Weirdly enough, the issue did not return after splitting that long single line into multiple lines again, as if there had been bogus characters somewhere in between.

I'm creating this issue to let everyone know I got to get rid of them by setting the includes in a single line and then splitting them into two again.

initial main-file.md:

{% include-markdown "1-introduction.md" start="<!--begin-block-->" end="<!--end-block-->" %}
{% include-markdown "1-introduction.md" start="<!--begin-block-->" end="<!--end-block-->" %}

Modified main-file.md:

{% include-markdown "1-introduction.md" start="<!--begin-block-->" end="<!--end-block-->" %}{% include-markdown "1-introduction.md" start="<!--begin-block-->" end="<!--end-block-->" %}

Final main-file.md:

{% include-markdown "1-introduction.md" start="<!--begin-block-->" end="<!--end-block-->" %}
{% include-markdown "1-introduction.md" start="<!--begin-block-->" end="<!--end-block-->" %}

1-introduction.md:

<!--begin-block-->
#Introduction

sample text.
<!--end-block-->

mkdocs.yml:

plugins:
  - search
  - include-markdown

Remove Python 3.6 support

trailing-newlines parameter question

I tested this new feature.

This does not work:

1.  This is the first number line
1.  {%
       include-markdown "./includes/content_chunk2.md"
       trailing-newlines=true
    %}

1.  If everything works as expected this should be number 3

This does work

1.  This is the first number line
1.  {%
       include-markdown "./includes/content_chunk2.md"
       comments=false
       trailing-newlines=true
    %}

1.  If everything works as expected this should be number 3

The docs do not indicate the "trailing-newlines" parameter must only be used with "comments=false". Can the docs be updated or the combination be removed?

UTF8 encoding is lost upon including

Hello,

When I include MD file with language other than english, I lose UTF8 encoding, and text become corrupted.
Onlu english text is included correctly.

Wrap start and end comments by quotes

Using start=' ' or end=' ' will display a unreadable BEGIN INCLUDE ... END INCLUDE comment because start and end will not be well displayed.

Make heading-offset cumulative over nested inclusions

Use case is:

File A.md:
# A

File B.md:
# B

File C.md:

#C

{%
include-markdown "./A.md"
heading-offset=1
%}

{%
include-markdown "./B.md"
heading-offset=1
%}

which is already rendered as following:

C

A

B

But if you have
File D.md:

# D

{%
include-markdown "./C.md"
heading-offset=1
%}

it is currently rendered as:

D

C

# A

# B

While I expected it to be rendered as follows:

D

C

A

B

Therefore, I suggest making heading-offset parameter cumulative over nested inclusions in order to achieve that expected result. Thank you for your feedback.

Add parameter to exclude BEGIN and END INCLUDE comments

allow user to change default delimiter

It's better to allow user to change the default delimiter {% %}, which is conflict with mkdocs-macros-plugin.
Currently, when using this plugin, it must be configured before macros to let mkdocs work.

Add types

Drop Python3.7 support

Parts of included markdown file gets incorrectly rendered as code

I found a weird bug while writing documentation for my project:

I have an index.md exactly like this:

{%
    include-markdown "../README.md"
%}

And a README.md file that you can find from my repo: https://github.com/guillp/requests_oauth2client/blob/master/README.md

The index.html that is generated has the complete top half rendered as code: https://github.com/guillp/requests_oauth2client/blob/00e6ee7f790b158dfd48e4c2c6a750672859c753/index.html

To workaround it, I had to copy/paste the content of README.md into index.md. The generated documentation looks as expected (for reference: https://guillp.github.io/requests_oauth2client/ ).

I am not sure exactly what causes this bug. I tried removing some parts of README.md to see if that had any effect on the render, but did not find the exact location that causes this issue.

Regards,

[wish] Option to omit YAML frontmatter when including an .md

When I include a full Markdown file that has YAML frontmatter (metadata) in another Markdown file, the plugin copies the YAML which becomes invalid HTML

It would be wonderful if there was a simple option to skip the YAML frontmatter when including an .md file

Copy included Markdown referenced links targets definitions

If a [referenced-link][target] is found inside included snippet content using include-markdown directive and their target definition ([target]: link) is not found in includer file, must be copied into it.

Allow for indented "info" boxes

Using the extension "admonition" we are able to add "highlight boxes" to our site.

Is there a way to allow "indented info boxes"?

I have a test site here to show what I did: https://github.com/cncook001/mkdocs-test

https://github.com/cncook001/mkdocs-test/blob/main/mkdocs/docs/info-test.md

Markdown links inside code blocks are interpreted

I seem to have run into a problem when using {% markdown-include %} to include a markdown file that contains a code block, which in turn contains something that looks like a valid markdown link (but in fact it's a C++11 lambda definition).

Here's an example. I have a markdown file examples/lambda.md that contains a C++ code snippet, with C++11 lambdas:

examples/lambda.md

This is an example of a C++11 lambda:

```cpp
const auto lambda = []() { .... };
````

If I include this markdown file into another document using {% include-markdown %}, the []() string in the code block gets interpreted as an empty link

docs/main.md

Hello! Let's learn C++!

{% include-markdown "../examples/lambda.md" %}

The output then looks like this:

---

Hello! Let's learn C++!

This is an example of a C++11 lambda:

const auto lambda = [](../examples) { ... };

---

Notice the "../examples" string rendered in the lambda codeblock. I suspect the reason is that []() is a markdown syntax for links, which somehow gets interpreted during the include process, even though it is inside of a code-block. If I change the code example to contain space between [] and (), then it gets rendered correctly (i.e. no extra strings get injected)

const auto lambda = [] () { ... };

Feature request: Global config settings

It would be great to set a global flag to change some of the default settings.

e.g. Whenever I add "include-markdown", I want to automatically set these as defaults as well:

comments=false
trailing-newlines=true

Error while using relative urls

Hi, I'm getting following error

ERROR   -  Error reading page 'quickstart/index.md': relpath() argument must be str or bytes, not 'PosixPath'
Traceback (most recent call last):
  File "/usr/lib/python3.5/runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "/usr/lib/python3.5/runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/__main__.py", line 192, in <module>
    cli()
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/__main__.py", line 152, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/commands/build.py", line 271, in build
    _populate_page(file.page, config, files, dirty)
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/commands/build.py", line 168, in _populate_page
    'page_markdown', page.markdown, page=page, config=config, files=files
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/plugins.py", line 94, in run_event
    result = method(item, **kwargs)
  File "/usr/local/lib/python3.5/dist-packages/mkdocs_include_markdown_plugin/plugin.py", line 8, in on_page_markdown
    return _on_page_markdown(markdown, page, **kwargs)
  File "/usr/local/lib/python3.5/dist-packages/mkdocs_include_markdown_plugin/event.py", line 107, in _on_page_markdown
    markdown)
  File "/usr/lib/python3.5/re.py", line 182, in sub
    return _compile(pattern, flags).sub(repl, string, count)
  File "/usr/local/lib/python3.5/dist-packages/mkdocs_include_markdown_plugin/event.py", line 91, in found_include_markdown_tag
    destination_path=page_src_path,
  File "/usr/local/lib/python3.5/dist-packages/mkdocs_include_markdown_plugin/process.py", line 134, in rewrite_relative_urls
    markdown
  File "/usr/lib/python3.5/re.py", line 182, in sub
    return _compile(pattern, flags).sub(repl, string, count)
  File "/usr/local/lib/python3.5/dist-packages/mkdocs_include_markdown_plugin/process.py", line 124, in found_href
    rewritten_url = rewrite_url(href)
  File "/usr/local/lib/python3.5/dist-packages/mkdocs_include_markdown_plugin/process.py", line 108, in rewrite_url
    destination_path.parent)
  File "/usr/lib/python3.5/posixpath.py", line 460, in relpath
    genericpath._check_arg_types('relpath', path, start)
  File "/usr/lib/python3.5/genericpath.py", line 143, in _check_arg_types
    (funcname, s.__class__.__name__)) from None
TypeError: relpath() argument must be str or bytes, not 'PosixPath'

for this snippet

{% 
    include-markdown "../../_snippets/where-to-go-next.md"
    start="<!--intro-start-->"
    end="<!--intro-end-->"
%}

With rewrite_relative_urls=false it works.

Maybe it is related to the snippets not being part of the docs folder

.
├── README.md
├── dictionary.txt
├── mkdocs.yml
├── src
│   ├── _snippets
│   ├── docs
├── tsconfig.json
└── tslint.json

mkdocs.yml

site_dir: 'build'
docs_dir: 'src/docs'

This also brings me to feature request, yould it be possible in the plugin configuration to specify default source folder?

Thanks for looking into this.

Snippet does not honor the level in which it is used

I need to use one snippet file like this

snippet.md

- item
- item

# What can be done
{% include-markdown "snippet.md" %}

and

1. Is that all
    {% include-markdown "snippet-md" %}

While in the first the result is as expected, the second usage will create

<ol>
<li>
<p> Is that all </p>
<p>
- item
- item
</p>
</li>

instead of expected

<ol>
<li>
<p> Is that all </p>
<ul>
<li> item</li>
<li> item</li>
</ul>
</li>

Problem with several include-markdown statements (v2.6.1)

I've noticed a problem with included file

> **Sample content**: Lorem ipsum dolor sit amet, 
consectetuer adipiscing elit. Aliquam ante. In dapibus augue non sapien. 
Donec ipsum massa, ullamcorper in, auctor et, scelerisque sed, est. 

The file:

## Heading

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam ante. In dapibus augue non sapien. Donec ipsum massa, ullamcorper in, auctor et, scelerisque sed, est. Duis risus. Etiam ligula pede, sagittis quis, interdum ultricies, scelerisque eu.

{% include-markdown "snippet.md" %}

## Heading 2

{% include-markdown "another.md" %}

## Heading 3

{% include-markdown "another.md" %}

## Heading 4

{% include-markdown "another.md" %}

## Heading 5

The contents of the snippet will be inserted, but rest of the file until Heading 5 is missing from the generated file. The last include will turn on the output again. I suppose that maybe the RE is too greedy?

Accept globs as filenames and include from multiple files

Is it possible to include whole (sub)directories with this plugin?

I am looking for a way to include sections from multiple files for "consolidation" of various todos, warnings etc

Alow to include escaped `"` characters in strings values

Replace `pathlib.Path` with `os.path`

Allow to pass strings using `'` characters to quote them

Demonstrate code for including without actually including

Great plugin, this is helpful!

Our community documentation has a contributor guide. In that guide I want to show others how to use this plugin as it applies to our documentation. To do so I've included this:

  ```text
  {%
      include-markdown "../docs_include/<file>.md"
      heading-offset=<parent-section-header-level>
  %}
  ```

However, it (naturally) gets interpreted as an inclusion, which creates an error and an empty fenced code block in the rendered page.

Is there functionality to instruct mkdocs-include-markdown-plugin to ignore this particular inclusion so that I can render the contents of the fenced code block verbatim?

Add 'start' and 'end' arguments to 'include' directive

Weird behavior when using include-markdown on the same file

If I have a file example.md and I attempt to use include-markdown to fetch from example.md (same file), then some odd behavior occurs.

Seems like the include works for the most part, except for a trailing " end=" printout.

Here's the relevant snippets from the markdown doc

<!--orm-questions-start-->

??? question "Can I make ORM calls without hooks?"

    Due to Django's ORM design, database queries must be deferred using hooks. Otherwise, you will see a `SynchronousOnlyOperation` exception.

    This may be resolved in a future version of Django with a natively asynchronous ORM.

??? question "What is an "ORM"?"

    A Python **Object Relational Mapper** is an API for your code to access a database.

    See the [Django ORM documentation](https://docs.djangoproject.com/en/dev/topics/db/queries/) for more information.

<!--orm-questions-end-->


. . .


??? question "Can `use_mutation` trigger refetch of a `use_query`?"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed eiusmod tempor incididunt 

{% include-markdown "hooks.md" start="<!--orm-questions-start-->" end="<!--orm-questions-end-->" %}

Feature request: nested includes

For the current scenario I have nested includes - and there is no simple (or convenient) way around it.

Would it be possible to support it?

Thanks.

Add option to dedent included content

Now, it's not possible to include a fragment of a Python docstring due to the docstring indent. This could be solved with a dedent argument, by default false.

Add 'preserve_includer_indent' argument to 'include' directive

Drop Mkdocs < 1.4.0 support

• Remove README comment about plugin order in configuration.
• Drop mkdocs.plugins.event_priority shim.

Feature Request: Add option to offset headings

I would like to ability to offset the headings inside a markdown file I import. I have a Markdown file that can both standalone and be imported into another file.

This could be an option available for every import.

{%
include-markdown "docs/test.md"
heading-offset=1
%}

Watch included files in server mode

When running mkdocs with mkdocs serve.

Relative paths to images inside markdown are broken when doing an include

Hello @mondeja ! I haven't touched this module in over a year and as soon as you take it over, I have a feature request! :)

I'm including another section from our README into the docs. This section contains images, in the ![](path_to_image) format.

README.md

....
<!--examples-start-->
![](docs/assets/example.png)
<!--examples-end-->
...

docs/examples.md

{%
   include-markdown "../README.md"
   start="<!--examples-start-->"
   end="<!--examples-end-->"
%}

But the trouble is, when the snippet from README.md is included, the relative path breaks because it's relative to a different file. I guess the same problem would occur for relative hyperlinks, too.

I'm wondering about a flag that can be used on include-markdown, which would rewrite URLs to be relative to the inclusion location. So something like

{%
   include-markdown "../README.md"
   start="<!--examples-start-->"
   end="<!--examples-end-->"
   rewrite_relative_urls=true
%}

What do you think?

Nested inclusions not showing correct warnings

Nested inclusions with expected but not found start or end delimiters does not show proper file paths in warnings.

Reproducible example

Script

import os
import tempfile

from mkdocs_include_markdown_plugin.event import get_file_content


first_includer = os.path.join(
    tempfile.gettempdir(),
    'first.md',
)
second_includer = os.path.join(
    tempfile.gettempdir(),
    'second.md',
)
included = os.path.join(
    tempfile.gettempdir(),
    'included.md',
)

with open(second_includer, 'w') as f:
    f.write(f'''# 2

{{% include-markdown "{included}" start="start" end="end" %}}
''')

with open(included, 'w') as f:
    f.write(f'''# 3''')

result = get_file_content(
    f'''# 1

{{% include-markdown "{second_includer}" %}}
''',
    first_includer,
    tempfile.gettempdir(),
    first_includer,
)

Output

Delimiter start 'start' defined at first.md not detected in the file included.md
Delimiter end 'end' defined at first.md not detected in the file included.md

Expected output

Delimiter start 'start' defined at second.md not detected in the file included.md
Delimiter end 'end' defined at second.md not detected in the file included.md

Log warning when failing to find `start` or `end`

Currently, if a start or end delimiter is not detected, the include tag silently handles this. This really ought to be logged via warning.

Feature request: Allow for trailing newlines in include files

I have a file called "test.md"

1.  This is the first number line
1.  {%
       include-markdown "./includes/content_chunk2.md"
    %}

1.  If everything works as expected this should be number 3

The contents of "./includes/content_chunk2.md" is this

This is my second content chunk

The challenge is using prettier. It will automatically ensure there is a final "\n" at the end of the file. This breaks the number scheme rendering.

The rendered file will be like this:

Test

1.    This is the first number line
2.    This is my second content chunk

1.    If everything works as expected this should be number 3

The trailing newline can be stripped with this command:

for i in docs/includes/*.md; do printf "$( <$i )" > $i; done

Then it renders like this:

Test

1.    This is the first number line
2.    This is my second content chunk
3.    If everything works as expected this should be number 3

Is there a way to allow an include file to have a trailing newline and also render the numbering system?