search

fralau / mkdocs-macros-plugin

Create richer and more beautiful pages in MkDocs, by using variables and calls to macros in the markdown code.
https://mkdocs-macros-plugin.readthedocs.io
Other
336 stars 51 forks source link

Bug in linking within the ReadTheDocs docs #71

Closed honzajavorek closed 3 years ago

honzajavorek commented 3 years ago

Hi, just came to learn about the plugin and noticed a bug. The following link is broken:

Screenshot_2021-04-01 mkdocs-macros

I'm visualising the problem below by the diff syntax. The green is what should be in place, the red is what is there now:

+ https://mkdocs-macros-plugin.readthedocs.io/en/latest/pluglets/
- https://mkdocs-macros-plugin.readthedocs.io/en/pluglets

The markup in the source looks correct, so I don't know how to fix this. It's probably something in the settings of either MkDocs or ReadTheDocs.

github-actions[bot] commented 3 years ago

Welcome to this project and thank you!' first issue

honzajavorek commented 3 years ago

Meanwhile I found more of these, but I suppose it's the same problem. Perhaps the docs could be checked for broken links like this. I'm happy to contribute if we're able to identify the root cause together.

fralau commented 3 years ago

Fixed the "pluglet" link, as requested.

It's an idiosyncrasy of a mkdocs with index pages (the rules for relative links are different for index.md and the other pages).

For the moment, let me know if you find others?

honzajavorek commented 3 years ago

Great! I'm pretty sure I've spotted at least one more somewhere. I'll see your change and go through all the links during next week. If I find something, I'll send a PR with a fix, mimicking whatever you did to fix this one 🙂

fralau commented 3 years ago

Thanks a lot! You are welcome to propose a PR!

As a caution, there is something funny: on mkdocs serve the link may work, but the link may still be broken on the target static website (as produced by mkdocs build)

fralau commented 3 years ago

@honzajavorek What do we do with this issue? Do we keep it open, or do we close it?

(I you propose a PR, you could still refer to it?)

honzajavorek commented 3 years ago

Hi, I have this as my TODO No. 1 item when I get to programming, but this week's difficult in that regard. Please, let's leave this open for a few more days, I definitely plan to get back to it when I get pass other tasks that distract me now.

honzajavorek commented 3 years ago

Found time today! I went through other links and discovered a few more broken ones. I created https://github.com/fralau/mkdocs_macros_plugin/pull/77 as a fix and added it alongside a few other PRs I've sent week ago when reading the documentation. I think we can close this.

One thing though. I'm no MkDocs expert, but when learning about how to do internal links in MkDocs, I've seen them with the .md extension. Is it possible that if you added .md to all your internal links, MkDocs would interpret the links correctly even for the index pages instead of us needing to think about the ../ discrepancy when writing the document? I didnt't try it, but I'd expect it to work this way.

fralau commented 3 years ago

@honzajavorek Thanks a lot! I merged all PRs.

I had to perfom #72 manually, to solve conflict with another PR (link).