7

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!

Balduin
  • 415
  • 4
  • 11
  • Perhaps it could work if you just moved your README.md file to the docs directory? – Lilya Jan 05 '21 at 11:53
  • 1
    I guess that would work, but the whole point of having index.md link the README.md is that I don't want to duplicate the README.md in the root directory (which I need for Github, PYPI, etc.) - but yes... maybe I should just copy-paste the content of the README.md to the index.md – Balduin Jan 06 '21 at 12:03
  • hi! I've tried to reproduce your problem but I wasn't successful in finding any other solution, so in your place I would probably go for copy-paste. I def get that you don't want to have duplicates. Perhaps, this can be helpful: https://github.com/mkdocs/mkdocs/issues/608#issuecomment-109855759 – Lilya Jan 06 '21 at 13:20
  • Also, reaching README.md file directly may be considered to be "sensitive", so that's why there is no any out of the box solution yet – Lilya Jan 06 '21 at 13:23

0 Answers0