Many extensions need to know the base path of the currently rendered Markdown file, as they are supposed to include assets relative to the markdown file. Two of them are:

• markdown-include
• pymdownx.snippets

Both make use of the config variable base_path for including other files, so in order to configure it, you would specify:

markdown_extensions:
  - pymdownx.snippets:
      base_path: docs
  - markdown_include.include:
      base_path: docs

Currently

Please take a look at this example repository.

|-- README.md
|-- docs
|   |-- big_topic
|   |   |-- index.md
|   |   `-- more_important_code.c
|   |-- index.md
|   `-- smaller_topic
|       |-- hello_world.c
|       `-- index.md
`-- mkdocs.yml

Currently you would have to include the *.c files with their full path, so in both files you would have to write:

    --8<-- "smaller_topic/hello_world.c"

    --8<-- "big_topic/more_important_code.c"

Why is this bad?

This is fine for Markdown files that are created and maintained for just one website, but we are currently including generic sub topics into our site that are shared among many repositories via git submodule. For e.g. some introduction topic on how to set up Docker. It's obvious that include paths must be relative to the Markdown file in this case, like:

    --8<-- "hello_world.c"

    --8<-- "more_important_code.c"

Desirable solution

If we want to be able to specify relative paths in every Markdown file, the base_path variable need to change with every Markdown file to be rendered, so it can't simply be included in mkdocs.yml.
This makes my feature request different from #998 #777 #761, because I'm not able to alter the .md files as they are shared over multiple projects.

It would be nice if we could specify something like

markdown_extensions:
  - pymdownx.snippets:
      base_path: $relative
  - markdown_include.include:
      base_path: $relative
  - one of many other extensions that use exacly 'base_path' as variable:
      base_path: $relative

that would then make MkDocs add the currently valid path as base_path variable for each rendered Markdown file.

This is an issue for the one who calls the plugin, and not the plugin itself, as an additional (dynamic) base_path must be exchanged at this point in code:

md = markdown.Markdown(
    extensions=extensions,
    extension_configs=config['mdx_configs'] or {}
)

Currently (with the upper config from my example), extension_configs would contain something in the structure of this:

extension_configs = {
    'pymdownx.snippets': {
        'base_path': '$relative'
    },
    'markdown_include.include': {
        'base_path': '$relative'
    }
}

We need to replace $relative here with the proper path depending on the current navigation.