Currently there is only a wheel on PyPI for version 0.7.0, but no sdist. For packaging this project on conda-forge it would be nice to have an sdist as well

cc @hadim

Not sure this is actually a bug, I can see how this is "works as designed" but might be problematic.

The intended use of the include string is "place the string somewhere and there it will include the referenced file". The problem is that if you place the string inside a code block (inline, fenced doesn't matter) to demonstrate how it is used it will process the string regardless. For an existing file you will simply get the file included at the location of the string, for a non-existing file there will be a warning.

So it's impossible to use the include string inside a code block. You can encode the braces with HTML characters outside of a code block to make an example but everything else won't work. I'm trying to teach my users how to use the extension and it breaks consistency with the rest of my examples.

markdown-include==0.5.1 seems to always strip the last character from files it includes. That's great when the last is a new line character \n, but less great when it's something else like the end of an html tag.

See this example. Note how the trailing > has been stripped off the included file and the markdown is therefore messed up.

import markdown
from markdown_include.include import MarkdownInclude
from devtools import debug

included_file_content = """
<b>this is a test</b>"""

with open('docs/examples/error.html', 'w') as f:
    f.write(included_file_content)

# Markdown Extensions
markdown_include = MarkdownInclude(
    configs={'base_path': 'docs/examples/'}
)

src = """
This is a test

{!error.html!}

and more afterwards.
"""
html = markdown.markdown(src, extensions=[markdown_include])
debug(html)
"""
test.py:24 <module>
    html: (
        '<p>This is a test</p>\n'
        '<p><b>this is a test&lt;/b</p>\n'
        '<p>and more afterwards.</p>'
    ) (str) len=80
"""

markdown has removed this argument: https://github.com/Python-Markdown/markdown/blob/77fb7f1b51076becff488a9b42ef2883153262a0/docs/change_log/release-3.4.md#previously-deprecated-objects-have-been-removed

I use this plugin on my site after upgrading

- markdown_include.include:
      base_path: .

The error I get is:

mkdocs serve
INFO     -  Building documentation...
ERROR    -  Config value: 'markdown_extensions'. Error: MarkdownInclude.extendMarkdown() missing 1 required positional argument: 'md_globals'
Aborted with 1 Configuration Errors!

Output from requirements.txt file:

click==8.1.3
fontawesome-markdown @ https://github.com/bmcorser/fontawesome-markdown/archive/master.zip
ghp-import==2.1.0
gitdb==4.0.9
GitPython==3.1.27
importlib-metadata==4.12.0
Jinja2==3.1.2
livereload==2.6.3
lunr==0.6.2
Markdown==3.4.1
markdown-include==0.6.0
MarkupSafe==2.1.1
mercurial==6.1.4
mergedeep==1.3.4
mkdocs==1.3.0
mkdocs-autolinks-plugin==0.6.0
mkdocs-git-revision-date-localized-plugin==1.1.0
mkdocs-material==8.3.9
mkdocs-material-extensions==1.0.3
packaging==21.3
pycurl==7.45.1
Pygments==2.12.0
pymdown-extensions==9.5
pyparsing==3.0.9
python-dateutil==2.8.2
pytz==2022.1
PyYAML==6.0
pyyaml_env_tag==0.1
six==1.16.0
smmap==5.0.0
tabulate==0.8.10
tornado==6.2
watchdog==2.1.9
zipp==3.8.1```

The recent release has broken my documentation build

Here is the relevant error message.

/home/travis/build/D3DEnergetic/FIDASIM/docs/fidasim.md
Traceback (most recent call last):
  File "/home/travis/virtualenv/python2.7.14/bin/ford", line 11, in <module>
    sys.exit(run())
  File "/home/travis/virtualenv/python2.7.14/lib/python2.7/site-packages/ford/__init__.py", line 385, in run
    proj_data, proj_docs, md = initialize()
  File "/home/travis/virtualenv/python2.7.14/lib/python2.7/site-packages/ford/__init__.py", line 141, in initialize
    extension_configs={'markdown_include.include': {'base_path': md_base}})
  File "/home/travis/virtualenv/python2.7.14/lib/python2.7/site-packages/markdown/__init__.py", line 159, in __init__
    configs=kwargs.get('extension_configs', {}))
  File "/home/travis/virtualenv/python2.7.14/lib/python2.7/site-packages/markdown/__init__.py", line 187, in registerExtensions
    ext.extendMarkdown(self, globals())
  File "/home/travis/virtualenv/python2.7.14/lib/python2.7/site-packages/markdown_include/include.py", line 58, in extendMarkdown
    md.preprocessors.register(IncludePreprocessor(md,self.getConfigs()), 'include', 101)
AttributeError: 'OrderedDict' object has no attribute 'register'
make: *** [docs] Error 1

The last character of each line is being chipped off, so as to remove the newline character. But when working with files without any newlines, this chips off a significant character.

This commit fixes this problem.

I've got a potential use-case that populates a requirements table using includes, like this:

Product | Operating System | Cloud Environments | Datacenter Environments --- | --- | --- | --- Product X | {! ./prod-x-os.md !} | {! ./prod-x-cloud.md !} | {! ./prod-x-dc.md !} Product Y | {! ./prod-y-os.md !} | {! ./prod-y-cloud.md !} | {! ./prod-y-dc.md !}

markdown-include only matches first include on each line, so the above scenario doesn't work. In fact, in this example scenario, everything from the second include onward is actually lost.

How do you feel about supporting multiple matches per line?

I have the markdown-include extension working with MkDocs, but when I try to add the inheritHeadingDepth: True config value, I get an error. I'm guessing I just don't have the config syntax right. Can anyone advise? Thanks :)

From my mkdocs.yml

markdown_extensions:
    - markdown_include.include:
        base_path: docs
        inheritHeadingDepth: True

Config instructions: https://github.com/cmacmackin/markdown-include#configuration I have tried formatting the YML several different ways with no luck.

Debug says:

DEBUG   -  Config value: 'markdown_extensions' = [{}, u'extra', u'admonition', {}, u'sane_lists']

And the error:

ERROR   -  Config value: 'markdown_extensions'. Error: inheritHeadingDepth
[E 190516 17:55:31 ioloop:801] Exception in callback <bound method type.poll_tasks of <class 'livereload.handlers.LiveReloadHandler'>>
    Traceback (most recent call last):
      File "c:\python27\lib\site-packages\tornado\ioloop.py", line 1229, in _run
        return self.callback()
      File "c:\python27\lib\site-packages\livereload\handlers.py", line 67, in poll_tasks
        filepath, delay = cls.watcher.examine()
      File "c:\python27\lib\site-packages\livereload\watcher.py", line 73, in examine
        func and func()
      File "c:\python27\lib\site-packages\mkdocs\commands\serve.py", line 107, in builder
        site_dir=site_dir
      File "c:\python27\lib\site-packages\mkdocs\config\base.py", line 210, in load_config
        "Aborted with {0} Configuration Errors!".format(len(errors))
    ConfigurationError: Aborted with 1 Configuration Errors!

https://github.com/cmacmackin/markdown-include/blob/6bdd38511403bd77cfad83580ed21eeb3eed44c5/markdown_include/include.py#L70

Changing the for loop around the whole list of lines to:

for loc, line in enumerate(lines):

and removing the loc = lines.index(line) call would improve performance.

Unfortunately, list.index() is just a for loop in C that starts at the beginning each time it's called, on every line, over and over again getting worse on each call.

Hello! I'm confused with the instructions in the README, I'm able to include this extension in MkDocs: markdown_extensions: [markdown_include.include] Now, I don't have an idea how to use this extension, Here what I want to achieve is to create a file name file.md with a content of:

[URL1]: mydocs/file1.md
[URL2]: mydocs/file2.md
[URL3]: mydocs/file3.md

then calling these relative paths from other markdown files like this:

Here is the [link][URL1] 
Here is the [link][URL2] 
Here is the [link][URL3] 

Is it possible? thanks in advance!

Consider the following situation:

=== "source"
    ` ` `python
    {!my_source.py!}
    ` ` `

and

print('Hello, world!')

Here we'd expect

=== "source"
    ` ` `python
    print('Hello, world!')
    ` ` `

That is, every line of my_source.py gets as many tabs and spaces as many is leading the inclusion tag.

This pull request enables this inclusion mode.

In my mkdocs project, I am using markdown-include and mkdocs-material.

Let a top-level file be:

# Some heading

{!tables/Some_Table.md!}

And let table/Some_Table.md be:

The following table shows some data about whatever.

| Some first column | Some second column | 
| ----------------- | ------------------ |
| Some text.        | Some more text.    |

• With inheritHeadingDepth being false, the generated output will be some nice looking HTML-table.
• With inheritHeadingDepth being true, the generated output will be the actual text, wrapped in <p> elements.

Used versions:

• mkdocs: 1.1.1
• mkdocs-material: 6.2.8
• markdown-include: 0.6.0
• python: 3.8

With inheritHeadingDepth being true.

Let a top-level file be:

# Some first level heading

{!sub/Subsection_1.md!}

{!task/Subsection_2.md!}

{!task/Subsection_3.md!}

And let each task/Subection_X.md be:

# Some heading <X>

Some text.

Then, I would expect the result to be:

# Some first level heading

## Some heading 1

Some text.

## Some heading 2

Some text.

## Some heading 3

Some text.

But, the actual result is:

# Some first level heading

## Some heading 1

Some text.

### Some heading 2

Some text.

#### Some heading 3

Some text.

With the current implementation of inheritHeadingDepth, it is impossible to include several sections on the same level.

Current workaround probably is to move the heading from the sections into the parent file.

This patch allows to automatically format source files (declared in the 'extensions' config option, where one can set a source file extension and a syntax highlighter synonym for that extension). I use it in mkdocs, where i set the following extensions:

    - markdown_include.include:
        base_path: docs
        extensions: 
            java: java
            py: python
            js: javascript

Is there any chence for this to get merged? Or do you plan to support this independently from my work?

Hi,

I'm having an issue with my includes because included files contains links.

For instance I have the following structure and parameter base_path: docs:

.
├── docs
│   ├── Tutorials
│   │   └── Examples
│   │   │   ├── Example1.md
│   │   │   ├── Example2.md
│   │   │   └── Example3.md
│   ├── global
│   │   └── Postman.md
│   ├── postman
│   │   └── collection1.json
└── mkdocs.yml

NOTE: this is a simplified directory structure for the ticket, the real one is visible at https://github.com/hyperledger/besu-docs/

Examples files all include the Postman.md file with the include syntax {!global/Postman.md!} relative to the docs base_path directory.

The Postman.md includes some explanation and a link to the JSON file in the form [download the collection](/postman/collection1.json) for it to be valid when the HTML is compiles with MkDocs and put on the website. I'm forced to use / as I can't know where the include is going to be made and so I can't have a relative path like postman/collection1.json otherwise it will end up in having the file relative for example to Tutorials/Examples/Example1 and will point to Tutorials/Examples/Example1/postman/collection1.json which is not right.

But the side effects of that are:

1. I have to make sure the /postman/collection1.json is a valid link because for instance with ReadTheDocs, path includes /lang/version/ so I have to add a redirect from /postman/collection1.json to /lang/version/postman/collection1.json which is not convenient
2. Link checker (is use the Node markdown-link-check but I guess all checkers will have the same issue) is failing on the link in the Postman.md file as it's valid only when included and compiles with MkDocs.
3. I'm unable to navigate to the link in my markdown source using my IDE as the link is invalid before being compiled in HTML.
4. Google indexed the Github repos and when people look at the Github rendered Postman.md file, the link is invalid as it tries to point to the root of my repos like https://github.com/me/myproject/blob/master/postman/collection1.json instead of https://github.com/me/myproject/blob/master/docs/postman/collection1.json

My wish:

Having the links in included files able to be written relatively to the included file then translated to the correct path once included would fix all this.

For instance, when I include the link in my docs/global/Postman.md I would simply write [download the collection](../postman/collection1.json), which would be valid when not included and once included in docs/Tutorials/Examples/Example1.md it would be translated to [download the collection](../../postman/collection1.json) which would correctly go up by two levels as expected.

The rendered HTML will have a valid relative path and the source markdown would be valid too whatever the context.

I think it requires the rewriting of URL just after including and before rendering the HTML or whatever, but I don't see any drawbacks for the moment. Please tell me if you do.

Thanks.