Proposal: Migrate docs from Jekyll to MkDocs + Material for MkDocs

[nscuro]

Current Behavior:

We currently use Jekyll to build our documentation.

Jekyll is a generic static site generator and was never really intended for technical documentation, but for websites and blogs.

Although the template being used provides some basic features (syntax highlighting, search), I feel like it looks a bit dated and is missing some features that'd make both writing and reading our docs more appealing.

Jekyll is also painful to setup locally (requires Ruby, Ruby Gems, Bundler, building of native extensions).

Proposed Behavior

What I'm proposing is the following:

• Migrate documentation from Jekyll to MkDocs
• Use Material for MkDocs to make the docs more visually appealing

MkDocs is written in Python and can be installed with pip, doesn't need native extensions and is made for writing technical documentation. Like Jekyll, it lets us write in Markdown (which can be extended in multiple ways) and can be deployed to GitHub pages and supports custom domains.

Linking to internal pages is less painful than with Jekyll, and it has a great built-in search UX. It auto-generates table-of-contents for each page, which makes discovery and navigation a lot easier. Creating links to specific sections of a page is also very easy, which makes referring to our docs in Slack or GitHub issues a bit more practical.

Material for MkDocs provides a more modern look, ships with loads of advanced features and is highly customizable.

Because so many things are built-in, we won't have to deal with many scripts or stylesheets anymore.

For reference, here are some examples I found that also use this stack:

• Material for MkDocs itself
• SAP Mobile Services
• AquaSec Trivy
• Traefik (although heavily modified)

[nscuro]

Threw a quick POC together and migrated a few pages here: https://nscuro.github.io/dependency-track/4.6.0-SNAPSHOT/

Docs are automatically deployed using GitHub Actions: https://github.com/nscuro/dependency-track/blob/mkdocs/.github/workflows/deploy-docs.yml

Using mike, we can serve multiple versions of the documentation: https://github.com/nscuro/dependency-track/tree/gh-pages