Compatibility shim for Github Flavored Markdown and MkDocs

[stevelandeyasana]

I work at a company whose source of truth for engineering documentation is hundreds of Markdown files in a GitHub repo. People had mostly been browsing the GitHub UI, which has just-OK navigation. Eventually I got fed up with it and tried rendering everything with Material for MkDocs, which is a huge improvement to readability.

It works great, but there are some things GitHub Flavored Markdown (GFM) supports that MkDocs doesn't. I needed to address these issues before making the MkDocs HTML the canonical way of experiencing our internal documentation.

1. Links to source code in GitHub, like a README that points to a Python file. This can be "fixed" by substituting the URL with a direct link to the file in GitHub.
2. Direct links to README.md files need to be replaced with links to their parent directories, since MkDocs uses index.html as the path for README.md.
3. Absolute links need to be replaced with relative links.

I solved these problems by writing a small MkDocs plugin that rewrites link targets, and I'm considering open sourcing it, but first I want to see if anyone would actually care. 🙂 GFM seems to be a superset of what MkDocs can handle, so if you write your Markdown for MkDocs, GitHub will display it just fine. But if for some reason you want to write (or have already written) your Markdown with GFM primarily in mind, this plugin makes it possible to render it with MkDocs without needing to manually fix all your links. I guess you could also see it as a "make absolute links work" plugin.

So, does anyone else have this problem, or just me?

[squidfunk]

Looping in @oprypin, the maintainer of markdown-callouts, an extension that makes admonitions more readable on GitHub.

[oprypin]

This is pretty much a discussion for MkDocs, not mkdocs-material.
I am the current maintainer of mkdocs and I happen to care about GitHub compatibility and all my own doc sites try to follow it.

Your claim 1. about links to source code in GitHub I think is true.

For 2 I can see how it can be a problem with some approaches but there exist approaches to make it work seamlessly. Please just show what you have and why it's not what you expected.

For 3 yes- but do absolute links work on GitHub itself in the first place? Anyway, this is also something that I have on my radar, so (precise) input is welcome.

And then as a bonus, indeed there is markdown-callouts

[stevelandeyasana]

Regarding README.md links: Apparently this isn't a problem after all, and when I remove code related to this from my plugin everything still works. There are more errors in my output, but they are all legit issues with my source files. Not sure what happened here, sorry for the misinformation!

Absolute links do work on GitHub. If you have a file at /foo/bar.md and you write [A link](/foo/bar.md), it works. In a large repo, relative links are annoying to write because there can be a lot of ../ to link somewhere else in the hierarchy. If you want, I could spend a few minutes spinning up a new GitHub repo with some minimal examples.

The plugin API was super easy to use, so thanks for that!