Skip to main content

Markdown guide

This guide covers the Docusaurus Markdown conventions used in both Axxya documentation sites (public/docs and runbooks/docs). For writing style questions, see the Style guide. This is not an exhaustive Docusaurus reference; for anything not covered here, see the Docusaurus docs.

Frontmatter​

Every page starts with a frontmatter block that sets at least title. Keep sidebar_label, sidebar_position, and description where the surrounding pages use them:

---
title: Install the desktop app
sidebar_label: Install the desktop app
sidebar_position: 1
description: How to install the Nutritionist Pro desktop app.
---

Sidebar order comes from sidebar_position in each page and position in each folder's _category_.json. File and folder names exist so people can find things in the file system; the sidebar metadata overrides them. If you rename a file or folder, update every link that references the old path.

Headings​

The frontmatter title renders as the page H1. Do not add a # heading in the body; the first in-body heading must be an H2 (##), and headings nest from there. Write headings in sentence case.

Whitespace​

Keep whitespace to a minimum:

  • One space after a period, and none at the end of a paragraph.
  • Do not split long lines or add line breaks inside a paragraph. One paragraph is one line; readers use word wrap.
  • Do not add a horizontal rule (---) unless there is a real need for it.
  • End every file with a single empty line.

Hiding pages​

  • Add draft: true to the frontmatter to hide an unreleased page. Drafts are excluded from production builds entirely but still render on the dev server.
  • Use unlisted: true instead when the page should stay reachable by direct URL but hidden from the sidebar, search, and sitemap.

Font formatting​

Use font formatting sparingly:

  • Bold (**text**) is for UI element names and user input: "click Save to save your changes."
  • Italics (*text*) are rare; prefer plain prose.
  • Do not bold inline code. Code gets backticks, not bold, so spellcheck ignores it.

Inline code​

Wrap any code, method name, filename, folder, or path quoted in a sentence in single backticks, for example `UpdateAll()` or `config.ini`.

Also wrap code-like special characters in backticks. The Markdown parser treats {} as a variable placeholder and <> as HTML tags, so text such as <Base URL> or ADMIN:{namespace}:USER must be inside backticks or it will break the page. If the placeholder is part of a longer string, wrap the whole string: `<StudioName>.example.com`.

Placeholders for variables​

When instructions include a user-supplied value, put the value between <> with a descriptor, no spaces, and tell the reader to replace it:

1. Log in at `https://<YourCompanyName>.example.com/admin`, replacing `<YourCompanyName>` with your company name.

Code blocks​

Open every fenced code block with three backticks and a language, and close it with three backticks. Never open a bare fence; without a language there is no syntax highlighting. Common languages in this repo are bash, json, php, ts, sql, and md.

npm run build

Admonitions (callouts)​

Use Docusaurus admonitions to alert the reader to important text: :::note, :::tip, :::info, :::warning, and :::danger, each closed with :::. Use info when redirecting the reader to another page for more information, and note when calling attention to additional information within the page itself.

You can give an admonition a short title (:::warning Keep your key private), but never use the name of one type as the title of another (no :::note TIP).

Collapsed sections​

Add a collapsed section with the HTML details element:

<details>
  <summary>References</summary>

  Longer content here.

</details>

Note that Markdown inside the <summary> tag does not render, so don't put backticks there.

  • Link between docs with relative paths that include the .md extension, for example ./setup.md or ../labels/index.md. Only external links use a full URL.
  • Markdown links with extensions work on GitHub and in editors, survive slug changes, and are the method recommended by the Docusaurus maintainers.
  • Link to a section by appending # and the heading's anchor, which is the kebab-case of the heading text: ./introduction.md#get-your-mcp-key.
  • Link text must describe the destination; never use "here" or "this."
  • Both sites build with onBrokenLinks: 'throw', so a bad link fails the build. Verify with npm run build after editing.

Images​

Add images with alt text and an optional mouseover title:

![descriptive alt text](./img/label_editor.png "Label editor")
  • Alt text is required on every image, for accessibility and SEO.
  • Use snake_case names with no spaces in file names or paths.
  • Indent the image syntax to line up with the text when it sits inside a numbered or bulleted list item.
  • See the Style guide for when to use images and how to prepare them.

Diagrams​

Use Mermaid for simple diagrams; they are easy to update and need no designer. Add them in a fenced code block with the mermaid language:

```mermaid
graph TD;
  A-->B;
  A-->C;
```

You can experiment in the Mermaid live editor.

Tables​

Use Markdown tables, not embedded HTML:

| Column name 1 | Column name 2 |
|---------------|---------------|
| Content 1     | Content 2     |

Generators such as tableconvert.com can build or convert tables for you.

Lists​

  • Add a blank line before and after a list, and no blank lines between items. The theme styling handles spacing.
  • Number list items with their real numbers (1, 2, 3), not "1." for every item, so a reference to a step number can't silently break.
  • If the list items are sentences, end them with periods.

Referencing navigation​

When writing navigation instructions, name the starting point, tell the reader to "go to" the destination, and separate each level with an angle bracket:

1. In the dashboard, go to **Settings > Users**.

You do not need to say where the navigation options are located (for example, "on the sidebar") unless it is unclear.

Special characters​

Use HTML entities for special characters that Markdown or MDX would otherwise parse, for example &lt; for a literal less-than sign outside of code. Remember that em dashes are not used in this repo at all, so there is no need for &mdash;.

Verify​

After editing pages, run a build to catch broken links, bad anchors, and MDX parse errors:

cd runbooks && npm run build   # or: cd public && npm run build
  • Style guide, the prose writing rules for these sites.
  • Skills formatting, writer, and editor in the repo's .claude/skills/ folder encode these rules for AI-assisted writing and review.