Writing for the site

This guide tells you how to add content to the diagrams.mbt docs site. Write all content in ASD-STE100 Simplified Technical English. Use short sections, and mix prose with tables, code and diagrams. Do not write long walls of text.

Where content goes

The build reads only these sources. A file below docs/ is a page. A link from a page to a file that is not a page goes to the file on GitHub.

Front matter

Start each page with front matter between two --- lines.

---
title: Design overview
summary: How diagrams.mbt hosting and configuration work.
order: 1
status: proposed
---

The build fails on an unknown key.

The sidebar

The nav key of site/site.json sets the sidebar groups. Each group has a label and a list of items. An item is a top-level file or directory below docs/, for example design/ or WRITING_FOR_THE_SITE.md, or a glob such as guides/*.

"nav": [
  { "group": "Design", "items": ["design/"] },
  { "group": "Contribute", "items": ["WRITING_FOR_THE_SITE.md"] }
]

The build fails when an item matches no page, or when a top-level page or directory is not in nav. When you add a new top-level page, add it to nav in the same pull request.

Links

Write links as relative paths to the source file, so the same link works on GitHub and on the site.

Example: the Design overview explains the design.

A link to a path that does not exist, or that leaves the repository, fails the build. Each internal link on the site starts with the site base path. The build adds it, so do not write /diagrams.mbt/ yourself.

API links

To link to an API reference page, use a Markdown link with the target api:<package path>. Add #<item> to go to an item, or #<Type>.<method> to go to a method. The link text is free.

[`version`](api:moonrockz/diagrams#version)
[`Type::method`](api:moonrockz/diagrams#Type.method)
[the diagrams API](api:moonrockz/diagrams)

The build changes the target to the route of the API page, for example /diagrams.mbt/api/moonrockz/diagrams/#version. This link goes to version.

The build fails when the package has no API page, or when the page has no item or method with that name. The API pages show the packages of the modules in the api key of site/site.json.

A method of a trait implementation has the trait name between the type and the method, for example #Metadata.Eq.equal. Below a trait, it has the type, for example #Validate.Map[String,T].validate. To find an anchor, open the API page and copy the link of the heading.

Building blocks

Each building block is plain Markdown. The build turns it into HTML. A page needs no JavaScript to show a block.

Table

Write a GitHub Markdown table.

| Target | Status |
| --- | --- |
| native | Supported |
| js | Supported |

Code

Write a fenced block with a language. The site highlights it for the light and the dark theme.

```shell
mise run build:site
```

mise run build:site

Diagram

Write a mermaid block. The build draws it as an SVG image, so the page loads no diagram script.

```mermaid
flowchart LR
  Source[Markdown source] --> Build[build:site]
  Build --> Site[Static site]
```

Image or SVG asset

Put the image next to the page and link it with a relative path. The build copies the file.

![The layer stack](layers.svg)

Callout

Use the GitHub alert syntax. The kinds are NOTE, TIP, IMPORTANT, WARNING and CAUTION. GitHub shows the same callout.

> [!TIP]
> Run `mise run dev:site` to see your change before you push it.

Status

Put status: proposed in the front matter of a page about a design that is not implemented. The page then shows the banner "Proposed — not implemented", and the sidebar shows a badge.

Layer stack

Write a layers block with one name | detail line for each layer. The first line is the top layer.

```layers
Application | Your commands and services
Hosting | Builder, lifetime and exit codes
Configuration | Sources, merge and binding
```

1. ApplicationYour commands and services
2. HostingBuilder, lifetime and exit codes
3. ConfigurationSources, merge and binding

Code examples

The build does not compile code in a page below docs/. Put a MoonBit example that a reader can copy in a README.mbt.md file of its package. moon test compiles and runs its mbt check blocks, and the package page shows it.

In a page below docs/, a moonbit or mbt block must say notest. The build fails without it.

```moonbit notest
let config = @config.build(sources)
```

Planning documents

Design and implementation plans in docs/superpowers/ are local agent documents. They never go on the site, and you must not commit them. Add this line to .git/info/exclude in your clone:

docs/superpowers/

Do not change the tracked .gitignore for this. The build fails when a file below docs/superpowers/ is tracked or not ignored, and check:site fails when the built site has that path.

Preview and check

Run these tasks from the repository root.

Before you open a pull request, run mise run build:site -- --main and mise run check:site. CI runs them too.