Jekyll VS Docusaurus

If you don't want to use Jekyll as your static site generator for GitHub Pages and you want to have a custom domain for your GitHub Pages. This post is for you!

Jekyll is a static site generator that transforms Markdown files into a fully functional website. Everything is generated into plain HTML, which makes it simple to deploy on platforms like GitHub Pages.

Obviously, there are a dozen choices for generating static websites (efficiently and quickly), from the classic Jekyll to the new Next.js. And you are good to go with any of them as long as your confident with it. I choose 11ty because:

That would be an improvement, but it still wouldn't be equivalent to what you can do with Ruby and Jekyll. For example I do [1] so I don't need to put dates in my post names, which also fixes a bug [2] I encountered but was never fixed.

[1]: https://stackoverflow.com/a/68287682/660921

[2]: https://github.com/jekyll/jekyll/issues/8707

In your repository settings you need to turn on GitHub Pages to make it pull Jekyll content (that's the magic✨ default GitHub Pages build tool) from your GitHub repository.

If you're looking to start a blog (or if you're thinking of redesigning yours although you haven't posted in 2 years), you'll stumble upon a lot of options and it can be incredibly daunting; and if you stumble with the newest Josh's post about his stack it is easy to feel overwhelmed with the shown stack.

Here I am, signing off from a self-hosted WordPress site and finding a welcome change in Jekyll, a blog-aware static site generator. There is nothing new about this, several well-known bloggers have already migrated to Jekyll in the last few years. Ever since Tom Preston Werner created this software in 2008 and published his infamous article about Blogging Like a Hacker, it has become the go-to thing for at least the small and indie bloggers.

First I've looked at the tools I was already familiar with. I have some old blog where I've posted updates during my Google Summer of Code projects. It uses Jekyll to generate static files, automatically published by GitHub Pages. It works very well when you have the website tied to a version-controlled repository, but it's cumbersome when you need to rebuild container images or replace files in a remote volume even for small changes

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)