Relative links (to headings) in mkdocs with markdown_include.include

Viewed 1516

I'm not sure it's even possible to solve this problem - but I'd ask anyways:

I'm working on a python project using mkdocs for the documentation.
The project structure (simplified) looks roughly like this:

./
|-- docs
    |-- index.md
    |-- page2.md
    ā””-- [other documentation stuff]
|-- [the actual program stuff]
|-- README.md
ā””-- mkdocs.yml

I'm using the markdown_extensions markdown_include.include (declared in the mkdocs.yml), and the index.md consists only of the line {!README.md!} to include the markdown file at this place.

This works nicely, displaying the README.md as the overview page of the docs.

The problem I ran into now is that in the README.md, I want to have a statement "For more detail, see XY", where XY should be a link to a heading in page2.md in the docs.

With mkdocs, I can simply write see [here](page2.md#heading2), and that works perfectly in the docs. But when I look at the README.md directly (e.g. on github), that gives me a 404.

When I put see [here](docs/page2.md/#heading2), it works from the README.md, but not in the docs created by mkdocs.

Is there any good way to work around this? Help would be much appreciated!

0 Answers
Related