NetIP

NetIP Documentation source release using... Docusaurus?

Goodbye MkDocs, hello Docusaurus!

Nov 8, 2024

Today, I'm happy to announce two things: the update of the documentation for NetIP v0.2.0, and the release of the documentation's source code.

Let's dive in!

v0.2.0 Documentation

The title pretty much says it all. I just pushed the documentation content for NetIP v0.2.0. It notably includes:

Improved Quick Start explanation
DNS Profile Switcher
New settings (shortcuts & key bindings)

You can read it here!

Documentation Source Code Release

This was on my to-do list since the public release of NetIP, and it's finally done! The documentation's source code is now available on Gitlab. 🚀

It is versioned (more on that in a bit), written in Markdown, and built using Docusaurus with a bit of Structurizr. It is split in two main categories:

The User Guide - written for the end-user of NetIP.
The Contributor Manual - written for the volunteers working on NetIP.

For the full details on how to explore/edit the source code, please find the README.md file at the root of the repository.

The issue with MkDocs

In my Master Plan, I mentioned that I chose Material for Mkdocs for the documentation of NetIP. At the time, I was very happy with it. It just worked well. However, I found out while writing the v0.2.0 content that the way MkDocs handles versioning isn't ideal with my workflow.

In short, it uses the plugin mike, which heavily relies on git branches and Github Pages to function properly. This is explained in details here and here.

Unfortunately for me, I don't really like this workflow. I prefer having a single "monolith" folder, with each version content in their respective subfolder/plaintext files. MkDocs doesn't support this, so I had to find another way...

Docusaurus

Enters Docusaurus, an open source static documentation software developed by the folks at Meta. I won't bother you with the details, it's a static documentation tool that pretty much works like you assume it does.

What matters for me is the way it handles versioning:

website
├── sidebars.json        # sidebar for the current docs version
├── docs                 # docs directory for the current docs version
│   ├── foo
│   │   └── bar.md       # https://mysite.com/docs/next/foo/bar
│   └── hello.md         # https://mysite.com/docs/next/hello
├── versions.json        # file to indicate what versions are available
├── versioned_docs
│   ├── version-1.1.0
│   │   ├── foo
│   │   │   └── bar.md   # https://mysite.com/docs/foo/bar
│   │   └── hello.md
│   └── version-1.0.0
│       ├── foo
│       │   └── bar.md   # https://mysite.com/docs/1.0.0/foo/bar
│       └── hello.md
├── versioned_sidebars
│   ├── version-1.1.0-sidebars.json
│   └── version-1.0.0-sidebars.json
├── docusaurus.config.js
└── package.json

This is exactly what I was looking for. Sorry Mkdocs, hello Docusaurus!

Migrating from Mkdocs to Docusaurus

Fortunately, the NetIP documentation is still relatively short, so the migration went pretty smoothly. Both tools handle Markdown file almost the same way. It pretty much a matter of moving them to the correct folder, and fix a few things:

The pages' metadata are a bit different (e.g: weight becomes sidebar_position)
Category folders must have a _category_.json file for their metadata instead of a index.md file
The landing page was rewritten in Typescript (instead of pure Markdown)
Buttons and Admonitions are formatted differently
Same goes for images and links between pages, a bit of tinkering was required, but nothing too hard.

It took me a short couple of weeks, but all in all, I'm very happy with the result of this migration! It gives me a clear path forward for each new version of the documentation. If you're looking for a documentation tool that works great and handles versioning like this, I highly recommend checking out Docusaurus!