We use Docusaurus 2 as a generator to produce the static web site from markdown documents.

At the core the website is a collection of markdown documents that are translated to static HTML, which can be hosted on any web server, in our case github pages. Docusaurus 2 uses Remark.js under the covers, which gives the user the option to rely on additional remark plugins in the rendering process.

Scala mdoc can be used to run Scala codeblocks through the compiler to ensure that the code examples given in the documentation do compile. Furthermore, it provides the option to amend the code block by inserting commented lines with REPL output.

Mdoc is applied by the sbt mdoc plugin and creates a copy of the markdown files used as input with the Scala code blocks changed according to the mdoc processing rules.

The mdoc plugin can be invoked via sbt by

sbt docs/mdoc

The resulting output is written to a directory within the website folder structure, so that it can be picked up by docusaurus.

In many cases we want to reference code either from within our own project or from a URL. Within Blended ZIO we are using the Include Code Plugin which allows us to copy code blocks from the file system of from URLs into our documentation.

Within the documentation we often have the requirement to produce technical images such as graph visualizations, flow charts, sequence diagrams etc. Rather than using a dedicated graphics program, we prefer to create the images from a textual description. There are many generators that support that.

The fantastic Kroki Web Service provides a unified web service as a common interface to many generators that can create images from various specialized DSL's.

The Kroki Image Plugin is used within Blended ZIO to execute the Kroki web service for code blocks having kroki as their language.

The project documentation is located within the docs directory of the projects. All markdown files from this directory will be preprocessed by Scala Mdoc.

Everything related to the web site is located within the website directory.

The overall site generation can be triggered by

sbt docs/docusaurusCreateSite

First, the content of docs is run through Scala Mdoc. This will produce a modified copy of the markdown files in website/docs. This will be the primary input to the site generator.

The markdown input will be run though the chain of Remark processors, the last of which will actually generate the HTML pages. We have configured the plugins above into our Docusaurus 2 config file as below:

presets: [
  [
    '@docusaurus/preset-classic',
    {
      docs: {
        routeBasePath: '/',
        sidebarPath: require.resolve('./sidebars.js'),
        remarkPlugins: [
          [require('blended-include-code-plugin'), { marker: 'CODE_INCLUDE' }],
          [require('remark-kroki-plugin'), { krokiBase: 'https://kroki.io', lang: "kroki", imgRefDir: "/img/kroki", imgDir: "static/img/kroki" }]
        ],
      },
      theme: {
        customCss: [require.resolve('./src/css/custom.css')],
      },
    },
  ],
],

Before running the documentation locally, install Node.js dependencies:

cd website
yarn install

This needs to be run once to download all npm packages into node_modules. Subsequent runs only require yarn start.

To work on the documentation locally, it is best to run two terminal windows to execute the individual parts of the generator chain:

In the first terminal, navigate to the project's root checkout directory and start a sbt shell.

Within the sbt shell, execute

sbt

Then within the sbt prompt:

docs/mdoc --watch

This will monitor the docs directory and execute the mdoc preprocessor whenever a change in one of the markdown documents is detected.

In the second terminal, navigate to the website directory and run:

yarn start

This will start a local web server on port 3000, so that the documentation can be viewed at http://localhost:3000/.

When changes to markdown files in docs are made and saved:

1. MDoc detects the change (Terminal 1)
2. Processes Scala code blocks and outputs to website/docs
3. Docusaurus detects the change (Terminal 2)
4. Rebuilds and refreshes the browser automatically

:::note Important: Both terminals must be running for the local preview to work correctly. Without the mdoc preprocessor running in Terminal 1, changes to markdown files in the docs directory will not appear on the website served by Terminal 2. :::

To build the complete website for production:

# From the project root
sbt "docs/mdoc; docs/unidoc"

# Then in the website directory
cd website
yarn build

The static HTML output will be generated in website/build/. This build includes:

• All processed markdown documentation
• API documentation (Scaladoc)
• Optimized CSS and JavaScript

To preview the production build locally:

cd website
yarn serve

This serves the static build at http://localhost:3000/.