Migrate GitHub Pages documentation from Jekyll to Docusaurus

Owned by Joseph Pearson
Last updated: Jul 15, 2024
2 min read

Rationale

See GitHub issue #545 for the work to migrate the page management system (JAM stack, Static Site Generation).  The stated reasons for this migration effort include:


  • The current Jekyll-based solution is fragile and brittle - dependencies can be frequently updated and typically rely on differing versions of shared libraries

  • complex to learn and support - it's easy to install or use the wrong libraries and misconfigure the ruby environment so badly that you cannot preview pages

  • does not support different versions per branch - as we begin to use two or more branches at once, it is important to keep the diverging features documented separately (in their own branch)



  • Documentation is generated in Markdown, associated with each repository, moved to open-horizon.github.io repo when merged, and the site is generated in Jekyll with keywords abstracted out and inserted at page generation time.

Structure



Directives

Manual HTML element IDs

IDs are currently assigned using this syntax, which throws an acorn parsing error:

# Accessing management hub logs {: #accessing_logs}

The proposed solution is to remove the colon and space from the tag and move it up to the previous line separated from the title by a space:

# Accessing management hub logs {#accessing_logs}

Code blocks with CSS className for styling

Code blocks are currently written using this pattern:

```bash oc get pods --namespace kube-system | grep ibm-edge ``` {: codeblock}

The hanging colon directive at the end is causing an acorn parsing error.  Proposed solution is to remove the trailing directive and edit site configuration to add className to all code blocks if still needed:



Navigation

  • How should we indicate alternate content to be "hidden" behind tabs?

Keywords



I18N



Automation/Generation



Branches/Versioning documentation

Open Horizon currently supports three branches simultaneously: 2.30 (on VM1 in the lab), 2.31 (on VM2), and main (VM3).  Let's investigate how to track and use documentation for features specific to one or more branches.