Mkdocs: Support for multifile documents

[banj]

Mkdocs already supports up to 2 levels of pages, but a further usecase for me is the need to build documentation from existing sections that recur throughout my project- for example, a project description section that appears in several different places, or a list of standards that appear all over the place.

Marked 2 supports multifile documents using a special syntax, e.g.:

<<[path/to/file.md]

Is this something that might be supported in mkdocs in some way (or is there a way to achieve this result using existing features / templates?)

[d0ugal]

You could achieve something like this with a python-markdown plugin. I've not tried it, but it sounds like this might do roughly what you want: https://github.com/cmacmackin/markdown-include/

After installing it you would need to enable it in your mkdocs.yml. http://www.mkdocs.org/user-guide/configuration/#markdown_extensions

Otherwise you might find another plugin that does what you need. Something like this is probably out of the scope of MkDocs (but potentially could be a candidate for a MkDocs plugin when that is possible. See #206)

[banj]

This is a great suggestion, thanks!

I've had some trouble getting markdown-include to work with mkdocs, this is the first time I've tried to add a third party extension. Are there any modifications I need to make beyond installing the extension through pip to make it available to my mkdocs project?

[waylan]

What does your config file look like? Note that the markdown-include's docs state:

By default, all file-names are evaluated relative to the location from which Markdown is being called. If you would like to change the directory relative to which paths are evaluated, then this can be done by specifying the extension setting base_path.

Remember, MkDocs commands are generally called from the directory of the config file. The documents are actually in a child dir (defined in Mkdocs docs_dir setting). You probably need to set base_path to the same dir as the docs_dir (even if you are using the default value for docs_dir: docs):

markdown_extensions:
    - markdown_include.include:
        base_path: docs

[banj]

That worked!

Thanks, I really appreciate your help!

[saun4app]

banj,

After you installed markdown-include and configured the yml file, what syntax did you use in the markdown file to include another file? Thanks.

[Fuzzyma]

I searched for this way to long!
The syntax is {!filename!}