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.

Contents:

Building documentation locally

For instructions to build the documentation locally, see the Fluid Framework wiki on GitHub: https://github.com/microsoft/FluidFramework/wiki/Building-documentation-locally .

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 docs/api section is built from TSDoc comments in the source code.

Features

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/node-versions.md" %}}

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.

Input

```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) {
    return;
  }

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

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

Output

 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  }
 7
 8  if (coord !== undefined) {
 9    const cellInputElement = getCellInputElement(coord);
10    cellInputElement.value = keyString;
11
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  }
20};

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:

Tip

This is a tip.

Types

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

Note

This is a note.

Important

This is important!

Warning

This is a warning

Danger

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.

Input

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

Markdown formatting *goes* **here.**

{{% /callout %}}

Output

A note about syntax

Markdown formatting goes here.

Diagrams

We prefer text-based diagrams that are converted to images/SVGs at build time or run time. You can create inline diagrams with Mermaid or GoAT .

Mermaid diagrams

Mermaid diagrams can be put inline in a Markdown file using a code block with the mermaid language type.

Mermaid examples and syntax reference.

Input

```mermaid
classDiagram
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
```

Output

classDiagram 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

ASCII art diagrams with GoAT

GoAT is a tool to convert ASCII art block diagrams to SVGs. GoAT diagrams can be put inline in a Markdown file using a code block with the goat language type.

To more easily create block diagrams, you can try asciiflow , an in-browser editor for ASCII art block diagrams.

Some simple samples are included below. See the Hugo docs and the GoAT repo for more examples.

Example 1

Input

```goat
+-------------------+    +---------------------+
|                   |    |                     |
|                   |    |                     |
|  Input            +--->+   Output            |
|                   |    |                     |
|                   |    |                     |
+-------------------+    +---------------------+
```

Output

I n p u t O u t p u t
Example 2

Input

```goat
          .               .                .               .--- 1          .-- 1     / 1
         / \              |                |           .---+            .-+         +
        /   \         .---+---.         .--+--.        |   '--- 2      |   '-- 2   / \ 2
       +     +        |       |        |       |    ---+            ---+          +
      / \   / \     .-+-.   .-+-.     .+.     .+.      |   .--- 3      |   .-- 3   \ / 3
     /   \ /   \    |   |   |   |    |   |   |   |     '---+            '-+         +
     1   2 3   4    1   2   3   4    1   2   3   4         '--- 4          '-- 4     \ 4
```

Output

1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4

Markdown enhancements

Typography

Ellipsis: … ...

Em dash: — ---

En dash: – --

Definition lists

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

Input

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

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

Output

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