Switch from mkdocs to mdbook #2847
Conversation
|
Hmm... mdBook is a good tool, and I appreciate the work you put in here, but MkDocs is far more popular in the Python ecosystem and will be more familiar to our users. I'm partial to keeping MkDocs around, even if it requires workarounds for some of its idiosyncrasies.
From the linked issue: do you understand what this is describing? The link is broken for me. |
|
Yes I understand what's being described. Instead of I am personally not interested in implementing regex hacks for deviations from well-established standards. From a website user standpoint I don't think the tool that generated the website should matter. Also note that if we want to strictly lint our Markdown that is much easier when it is CommonMark-compliant, since that is actually well defined. |
I agree with this sentence (seems hard to disagree with!), but it's an inaccurate description of the change. Unless I'm mistaken, we're not just using a different tool to _generate _the website -- the entire UI of website itself is changing dramatically, since we're moving from Material to mdBook. I'd prefer not to change this right now. Maybe we'll change our minds in the future. In the meantime, I'd rather find another solution for doc links. If you don't want to work on that, no worries, I'll figure something out. |
|
I think from an UX perspective there is very little difference between mkdocs and mdBooks ... both have a sidebar on the left and a search on top ... they even have the same keyboard shortcut |
|
#2867 is somewhat related, as we need a solution for that too. |
not-my-profile
force-pushed
the
mdbook
branch
from
a55d851 to
ddfaeb9
Compare
In 28c9263 I introduced automatic linkification of option references in rule documentation, which automatically converted the following: ## Options * `namespace-packages` to: ## Options * [`namespace-packages`] [`namespace-packages`]: ../../settings#namespace-packages While the above is a correct CommonMark[1] link definition, what I was missing was that we used mkdocs for our documentation generation, which as it turns out uses a non-CommonMark-compliant Markdown parser, namely Python-Markdown[2], which contrary to CommonMark doesn't support link definitions containing code tags.[3] Mkdocs doesn't support CommonMark[4][5]. This commit therefore switches our documentation to use mdbook[6] instead, which uses the pulldown-cmark[7] CommonMark implementation, sparing us from having to deal with such parser idiosyncracies. [1]: https://commonmark.org/ [2]: https://github.com/Python-Markdown/markdown/ [3]: Python-Markdown/markdown#280 [4]: mkdocs/mkdocs#361 [5]: mkdocs/mkdocs#1835 [6]: https://github.com/rust-lang/mdBook [7]: https://github.com/raphlinus/pulldown-cmark
They mess up the heading anchors generated by mdbook.
not-my-profile
force-pushed
the
mdbook
branch
from
ddfaeb9 to
e244ff7
Compare
not-my-profile
force-pushed
the
mdbook
branch
from
e244ff7 to
cea4c16
Compare
|
Closing this since you're not interested. |
In 28c9263 I introduced automatic
linkification of option references in rule documentation,
which automatically converted the following:
to:
While the above is a correct CommonMark1 link definition,
what I was missing was that we used mkdocs for our documentation
generation, which as it turns out uses a non-CommonMark-compliant
Markdown parser, namely Python-Markdown2, which contrary to CommonMark
doesn't support link definitions containing code tags.3
Mkdocs doesn't support CommonMark4.
This commit therefore switches our documentation to use mdbook6
instead, which uses the pulldown-cmark7 CommonMark implementation,
sparing us from having to deal with such parser idiosyncracies.