Using the documentation system effectively

The Fluid docs are built using Hugo. It contains many of the features one would expect from a modern documentation system. Content is written in Markdown.


Building documentation locally

Generating API documentation

To build the API documentation, do the following from the root of the repository:

npm install
npm run build:fast -- --symlink:full --install --all
npm run build:fast -- -s build:docs --all

This will generate a JSON representation of all the TSDoc comments, which will be transformed into Markdown in the next step.

Building documentation site with Hugo

To build the docs themselves, you’ll need to switch to the docs/ folder, install the dependencies, and then build the site.

cd docs
npm install

npm start will serve the local documentation from http://localhost:1313/, while npm run build will build the full documentation site and output it to docs/public/.

Both npm start and npm run build will convert the TSDoc JSON into a tree of Markdown files under docs/content/apis/ as part of the site build. These files should not be committed to Git.

Documentation sources

The Fluid documentation comes from multiple sources.

Narrative documentation
The overall structure of the documentation comes from Markdown files in the docs/ folder.
Automated API documentation
The contents of the API section is built from TSDoc comments in the source code.


Reusable snippets

If you want to re-use a snippet in multiple places, place the snippet file in docs/_includes/. You can then reference it in a Markdown file like so:

{{% include file="_includes/" %}}

Syntax formatting and line highlighting

Code blocks can specify a language to enable syntax highlighting of the block. You can also highlight specific lines in the code block.


```ts {linenos=inline,hl_lines=["2-6",9]}
const numericInput = (keyString: string, coord: string) => {
  let valueToSet = Number(keyString);
  valueToSet = Number.isNaN(valueToSet) ? 0 : valueToSet;
  if (valueToSet >= 10 || valueToSet < 0) {

  if (coord !== undefined) {
    const cellInputElement = getCellInputElement(coord);
    cellInputElement.value = keyString;

    const toSet = props.puzzle.get<SudokuCell>(coord);
    if (toSet.fixed) {
    toSet.value = valueToSet;
    toSet.isCorrect = valueToSet === toSet.correctValue;
    props.puzzle.set(coord, toSet);


 1const numericInput = (keyString: string, coord: string) => {
 2  let valueToSet = Number(keyString);
 3  valueToSet = Number.isNaN(valueToSet) ? 0 : valueToSet;
 4  if (valueToSet >= 10 || valueToSet < 0) {
 5    return;
 6  }
 8  if (coord !== undefined) {
 9    const cellInputElement = getCellInputElement(coord);
10    cellInputElement.value = keyString;
12    const toSet = props.puzzle.get<SudokuCell>(coord);
13    if (toSet.fixed) {
14      return;
15    }
16    toSet.value = valueToSet;
17    toSet.isCorrect = valueToSet === toSet.correctValue;
18    props.puzzle.set(coord, toSet);
19  }

Info/tip callouts

It is often useful to draw special attention to some content in the docs, such as a tip about proper usage, a warning about possible security issues when using an API, etc. This can be done using the following syntax in Markdown files:

{{< callout tip >}}

This is a tip.

{{< /callout >}}

Which would render this:


This is a tip.


Several different “types” are defined, each with special formatting. tip is show above, but note, important, warning, and danger are also supported.


This is a note.


This is important!


This is a warning


This is a dangerous warning

Custom titles

By default, each box’s heading is the type. You can change this by providing a title after the type.


{{% callout note "A note about syntax" %}}

Markdown formatting _goes_ **here.**

{{% /callout %}}


A Note about Syntax

Markdown formatting goes here.


We prefer text-based diagrams that are converted to images at build time. You can create inline diagrams with Mermaid, or you can create ASCII art diagrams that will be converted to PNGs at build time.

Mermaid diagrams

Mermaid diagrams can be put inline in a Markdown file using the {{< mermaid >}} shortcode.

Mermaid examples and syntax reference.


{{< mermaid >}}
Class01 <|-- VeryLongClass : Cool
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --> C2 : Where am I?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 <--> C2: Cool label
{{< /mermaid >}}


ASCII art diagrams with ditaa

ditaa is a tool to convert ASCII art block diagrams to PNGs. Any file in the /docs/content folder with a .ditaa file extension will be converted to a PNG file in the same folder at build time.

asciiflow is an in-browser editor that makes it easier to create ASCII art block diagrams.


+-------------------+    +---------------------+
|                   |    |                     |
|                   |    |                     |
|  Input            +--->+   Output            |
|                   |    |                     |
|                   |    |                     |
|                   |    |                     |
+-------------------+    +---------------------+


An example ditaa diagram that has been converted to a PNG image

Read more about ditaa here. Note that we are using a fork of the original implementation re-written in Go to remove a Java dependency.

Markdown enhancements


Ellipsis: … ...

Em dash: — ---

En dash: – --

Definition lists

You can create definition lists using the syntax defined by PHP Markdown Extra.


: Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.

: The fruit of an evergreen tree of the genus Citrus.


Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
The fruit of an evergreen tree of the genus Citrus.