Programmable Docusaurus Configuration

[ericpassmore]

Summary

Use m4 macros to build docusuaurus.config.js @kj4ezj @lparisc @iamveritas for review

Problem Statement

By design the Docusaurus config is one large file with all the options https://docusaurus.io/docs/configuration This creates issues.

1. All versions of documents listed in the config need to exist for a successful build Today we have two configuration files to support the two states.
   • docusaurus.config.js for the initial build, used when building from nothing
   • docusaurus.config.js.new for the multi version build for the end state This causes confusion.
   • Hard to figure out which file to update
   • Hard to keep both files in sync
2. Lack of isolation. Today you build and test everything, with all versions of documentation and all features enabled. Currently the configuration and text for the homepage is stored in the config file. If you want to update some text on the homepage you need to edit this massive config file. There are other examples, the point is many sections of the config are separate and distinct. There is no need for everything to be in a single configuration file. This massive config causes issues
   • Long build times for testing
   • Need to install lots of software like doxybook and java8 to support the full build
   • Hard to isolate issues to your work, as you need to pull in everything
   • Accidentally change the wrong config

Scenarios

• New site design. Want change CSS and update some homepage text. Want to iterate fast, and only need the latest version of docs repo for testing.
• Review presentation for specific repository. Made markup changes to a repository and want to preview those changes on local box. Want to build just that repository from scratch.
• Test advanced build of docusaurus. Want to see if mermaid support is working by testing specific Docusaurus canary version. Will branch and add new configuration section for mermaid support. Want easy path to merge in changes if this works.

Requirements

Keep it simple, and only target 4 configuration sections.

• Homepage presentation - separate file
• Navigation that references specific repositories - new m4 macro
• Version configuration for repositories - new m4 macro
• Redocly configuration - separate file

Seperate File

Easy enough the m4 macro pulls in contents of a file

Navigation Macro

List of repositories is set at build time. There are two macros. The m4 navigation-macro generate a navigation element from the argument passed in. Will need to build an array of repositories in m4 language, iterate over the array, and call the navigation-macro with the positional argument.

Version Configuration

Three macros. A Macro for the version. A Macro for the entire configuration group. Finally a macro to iterate over the possible version.

[ericpassmore]

started work with redocly macros completed in ENF staging