Writing reference
The grey boxes show what to type; the part below each one shows the result. Pages are MDX: Markdown plus components.
Links
Link to another page with its file name, and to a heading on it with the heading in lower case with dashes:
[Editing these docs](editing-these-docs.md)
[Images section](editing-these-docs.md#images)
Editing these docs · Images section
Stable section links
A heading's link changes when its text changes. To keep links working after a rename, give the heading a fixed ID at the end of the line:
### Support hours {/* #support-hours */}
Then link to it with that ID, from this page or any other: support hours.
Sveltia turns /* into /\* when it saves, which breaks a fixed ID and stops
the site from updating. Only add fixed IDs in a code editor. Headings still
get an automatic ID from their text, so this one is linkable without one.
Support hours
Support is available Monday to Friday, 8:00 to 17:00. For a link to a single paragraph, see Components.
Footnotes
Exports are limited to 10,000 rows.[^limit]
[^limit]: Contact support for larger exports.
Exports are limited to 10,000 rows.1
Boxes
:::note
Plain note. Also: tip, info, warning, danger.
:::
:::warning[Data loss]
A box with its own title.
:::
Plain note. Also: tip, info, warning, danger.
A box with its own title.
Boxes can contain other boxes; give the outer one an extra colon:
::::info[Before you start]
Check the following:
:::tip
You need admin rights.
:::
::::
Check the following:
You need admin rights.
Code
Code blocks get a copy button automatically. After the language you can add a title, highlighted lines and line numbers:
language: json title="sensor.json" {3} showLineNumbers
{
"name": "Warehouse 1",
"interval": 60,
"alerts": true
}
Shell commands use the language bash (or powershell):
curl -O https://example.com/agent.sh
sh agent.sh --token YOUR_TOKEN
Images
Diagrams
A code block with the language mermaid becomes a diagram:
Tables
Use the editor's table button, or type one:
| Plan | Sensors | Support |
|---|---|---|
| Basic | 10 | |
| Pro | 100 | Phone |
Page settings
Maintainers can set more fields at the top of a page file, for example a search-engine description (this page has one) or a shorter sidebar name:
description: Syntax for these docs, with examples.
sidebar_label: Syntax
Components
These use MDX: HTML-like tags and components inside the page. They are stock Docusaurus features, but the browser editor may remove them when it saves, so pages that use them are best edited in a code editor.
Keyboard keys
Press <kbd>Ctrl</kbd>+<kbd>S</kbd> to save.
Press Ctrl+S to save.
Collapsible section
<details>
<summary>Why is my sensor offline?</summary>
Check the power supply first.
</details>
Why is my sensor offline?
Check the power supply first.
Tabs
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs>
<TabItem value="windows" label="Windows">Download the installer.</TabItem>
<TabItem value="macos" label="macOS">Download the disk image.</TabItem>
</Tabs>
- Windows
- macOS
Variables
Define a value once at the top of a page and use it anywhere on it:
export const product = 'Acme Monitor';
Welcome to {product}.
Welcome to Acme Monitor.
Linking to a paragraph
Put an anchor in front of the paragraph and link to it like a heading:
import Link from '@docusaurus/Link';
<Link id="export-limit" />Exports are limited to 10,000 rows.
See the [export limit](#export-limit).
Exports are limited to 10,000 rows.
See the export limit.
Things to avoid in text
In MDX some characters have a meaning, and a mistake stops the site from updating until it is fixed:
{starts code. Write\{for a literal brace.<directly followed by a letter or number starts a tag. Write<or add a space (< 10).- Use
{/* comment */}for comments, not<!-- -->, and only in a code editor: Sveltia breaks them. - Task lists (
- [ ]) lose their checkboxes in the browser editor.
My Edit
I made this small edit here!