Consider moving to MkDocs
Open
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 13
- Forks
- 18
- Avg merge
- 2h 42m
- Merged PRs (30d)
- 5
Description
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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the current Sphinx configuration and existing Markdown and reST documentation, then compare the custom extensions with MkDocs and its Material theme. Check the existing Lychee link-check setup and the feasibility of gradual Markdown conversion. The issue names no files or acceptance criteria, so an agreed migration scope and definition of done are still needed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100