Consider moving to MkDocs

Just an idea. Pros:

Simpler stack, simpler config.
Markdown has won. People don't know reST, even myself, after years of using it, still make the most basic mistakes and need to lookup the most basic stuff.
Also supported by RTD.
Has the Material theme, which is modern, under active development, flexible, has dark theme, etc.
Is used at other projects, such as python.cz or junior.guru, so know-how would be shared (contributions, maintenance).

Cons:

We extend Sphinx and would need to rewrite those things.
We use reST extensively. I'm not sure we can port it 1:1 (but is it necessary?)

How:

This can happen gradually. Our current setup supports Markdown, so texts can be converted first and we would see.
I already moved from builtin Sphinx link check to Lychee, as it works better.

I like reST so much, but the truth is Markdown is the leader now.. Slowly let's rewrite the content and once we'd 100% coverage, we could make the move.

.md mkdocs material theme

Pros: they all look the same
Cons: they all look the same

I would still support it 😺

Haha! Well, I did my best so that https://python.cz/ doesn't look the same 😈

I like it! After all, markdown is almost everywhere: GitHub, Obsidian, and even Slack understands basic markdown. We took the similar approach with our internal docs: new projects in Material for mkdocs and we plan to migrate some of our older docs.

I also volunteer to help, the least I can to is to help with the Markdown rewrite.

I prefer markdown to reST, so I'm on board with the idea.
Since I don't know MkDocs, is it mature enough for our needs? And, probably, stable enough (as I don't see us chasing possible deprecations too actively)?
Would appreciate (~need) a set of instructions how to work with this framework (here in README is enough). If it's abstracted away by uv magic, maybe that's enough.

@encukou

MkDocs is pretty much just Markdown files thrown to a folder, then something like uv pyvec-docs build or uv pyvec-docs serve and that's it.

Regarding spinning up the environment it's not much different from how is it now though: https://docs.pyvec.org/contributing.html (it wasn't linked from the README though until @encukou added the link a few days ago)

Regarding maturity of MkDocs, it exists since 2014 and for many these days it's number one static docs generator written in Python, for many it's number two behind Sphinx, depending on nostalgia, preference, or requirements.

I use MkDocs extensively at the junior.guru website, I extend it heavily, upgrade versions regularly, and I didn't find any limitations or shortcomings. It supports plugins, there's both a public ecosystem of them, and you can write a custom ones, too. I remember when it was less mature and less extensible, but that time is gone.

Sphinx Pros:

Config is already done (though it could be simplified).
Markdown is supported.
- Most (all?) reST features are available as Markdown extensions
Also supported by RTD.
Is used at other projects, such as docs.python.org, docs.scipy.org or kernel.org/doc/html/latest/, so know-how is useful.

Cons:

We don't know what theme to pick.
- If we do pick one, we'd need to do some work to port to it (e.g. make images light/dark friendly).
~~Needs external link checker.~~ [edit: no difference from MkDocs here]
Most people will need to look up the syntax for Markdown extensions.

I'm team Sphinx. But I'm also biased, I chat with Sphinx's current lead maintainer regularly ;)

The Cons belong to Sphinx or to MkDocs?

If we're with Sphinx, I'd stay with the RTD theme, but its capabilities are limited and it might feel less nice than MkDocs Material. Unfortunately Sphinx Material is unmaintained and I didn't find anything else as modern (subjective). Making images light/dark friendly would need to be done with either Sphinx or MkDocs if the theme supports dark mode. If we use Material, dark mode can be added as a second step, it's configurable, not required.
Sphinx doesn't need external link checker, but the built-in one doesn't seem to be as good as Lychee is, so I switched it. MkDocs has no link checker.
Most people will need to look up the syntax for Markdown extensions, that's true. But most people need to look up 90 % of reST, including me, who used to write it quite a lot (maybe subjective?).

I used to be team Sphinx for a very long time.

MkDocs has no link checker

To be super precise, maybe as a plugin, but no builtin one. Anyway, I think Lychee would be superior to random plugins, as it is a dedicated project focused only on the problem of verifying links in docs, and it's language- and generator- agnostic.

@jsmitka

I think it's useful to have these findings by @jsmitka (see #450) also here in this issue:

If we end up using MkDocs, please note that MyST (the markdown parser for Sphinx) use a different syntax than MkDocs for several elements:

* Extra properties of Images: MyST vs Material for MkDocs
* Admonitions - notes, warnings, etc.: MyST vs Material for MkDocs
* Cross-references: MyST vs regular links with anchors in MkDocs (there might be another solution I am not aware of).
* Custom in-line roles: {slack}`<...>`, {twitter}`<...>`, {gh-repo}`<...>` - those will need to be re-implemented as plugins, or just rewritten as plain links (might be an better option).
* Source comments: MyST vs HTML comments in PyMdown extensions.

Navigation Menu

Repository navigation

Consider moving to MkDocs #434

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Consider moving to MkDocs #434

Description

Activity

kvbik commented on May 12, 2025

JakubDotPy commented on May 14, 2025

honzajavorek commented on May 14, 2025

jsmitka commented on May 16, 2025

befeleme commented on May 31, 2025

honzajavorek commented on May 31, 2025

honzajavorek commented on May 31, 2025

encukou commented on Aug 15, 2025

honzajavorek commented on Aug 16, 2025

honzajavorek commented on Aug 22, 2025

honzajavorek commented on Aug 23, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions