Links in included files have to be written like if they were in the parent including file

[NicolasMassart]

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.