You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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
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.
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.
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.
The text was updated successfully, but these errors were encountered:
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
: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 thedocs
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 likepostman/collection1.json
otherwise it will end up in having the file relative for example toTutorials/Examples/Example1
and will point toTutorials/Examples/Example1/postman/collection1.json
which is not right.But the side effects of that are:
/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 convenienthttps://github.com/me/myproject/blob/master/postman/collection1.json
instead ofhttps://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.
The text was updated successfully, but these errors were encountered: