MkDocs VS Docusaurus

Because of my frustrations, I've released two example GitHub repositories for two popular static site generators: MkDocs and Sphinx. The goal with these repositories is to be focussed on a minimal project using the static site generator, that builds into a Read The Docs theme compatible website, and provide supporting tooling regarding formatting of the underlying formatting language. It also provides the tooling needed to deploy to GitHub Pages both from the command line and via GitHub Actions (both are powered by the ghp-import project).

The documentation of the CLI is provided via a GitHub page as part of the repository. We are using MkDocs to generate the content, but I think most of the tools in that area are well integrated with GitHub and GitHub Actions.

The original mkdocs uses a Python package for its installer, so you can just pip install mkdocs, mkdocs new ., and then mkdocs build to convert markdown files into HTML.

If you don't like to run javascript outside of a browser, MkDocs is a great Python-based alternative: https://www.mkdocs.org/

I like Markdown because it's simple and doesn't give me that many headaches.

You know what I don't like? HTML, for user submitted content in particular. The mess I've seen, after someone opted for using HTML for messages in a system, because that's what JS based editors were available for at the time. Endless need to work against XSS, with more and more incremental updates needed to the sanitization logic, some of which broke the presentation of the data in the DB.

Never again. Markdown, BBCode, anything but that.

As for docs? Currently just some Markdown, because that's what GitHub, GitLab, Gitea and others all know how to render.

Maybe something like https://www.mkdocs.org/ for the more standalone use cases.

Developing the documentation website using an open-source static site generator like Sphinx or MkDocs to build the files locally through the command line, rather than using a commercial program.

MkDocs is BSD-2-Clause licensed and has a vibrant community; GitHub Discussion is used for questions and high-level discussion, while the Gitter/Matrix chat room is used to discuss less complex topics. These communities provide essential resources and support.

I really like the idea and what you’re building here. That said, I’d argue the documentation website is the face of any open-source project. Reinventing the wheel rarely ends well — the current docs are hard to navigate and read.

Just use an off-the-shelf solution for docs, like Docusaurus, for example:

https://github.com/facebook/docusaurus

Static websites are so good that they even have their own three-letter abbreviation: SSG (Static Site Generation). And of course, there are plenty of frameworks that generate them for you, no need in manual labour: Next.js supports SSG, Gatsby is still pretty popular, lots of people love Docusaurus, Astro promises the best performance, and probably many more.

hCaptcha docs is built using Docusaurus and their developer guide provides a vanilla example, but there’s framework specific examples provided as well.

Create visibility: A good mental model of your systems, data and code is beneficial to solving for errors so create tangible mind maps or documentation for the whole team to benefit from. Miro and Docusaurus are excellent tools for this.

VitePress and Docusaurus seem decent. I think VitePress might be more suited to blogging, but I admit I haven’t actually used or tested either.

https://docusaurus.io/

https://vitepress.dev/

For efficient workflows, Commander.js offers a custom CLI, while Docusaurus powers documentation, ensuring that everything is easy to find and well-maintained.

I am aware of Docusaurus, since I have seen other documentation and some of our course material site built on it. Under the hood it uses React so I was familiar with it. But this documentation website was written in Python. Although I'm not a fan of Python, it intrigued me, since not only it is written in python, more specifically using Sphinx which utilizes reStructuredText as its markup language. There was Makefile in it as well. A lot of new things but it looked very interesting.

Docusaurus (https://docusaurus.io) is a well-regarded open-source tool for building documentation websites. It is a static-site generator that builds a single-page application leveraging the full power of React. However, it does not provide any kind of authentication out of the box. Adding authentication is crucial for securing access to your documentation.

- [Optional] List of language codes

I want to avoid JavaScript lock-in at all costs.

https://docusaurus.io/ (far from being a one-liner, still uses JavaScript)