Markdown components
Docusaurus provides a rich set of features to write really nice documentation. Please read their online docs to check out the markdown features.
This page details the custom markdown extensions available when writing the documentation.
Command block​
If you what to generate the contents of a code block at build time, then you can use the special command
directive to indicate that the code-blocks contents should be set from the output of a command.
Property | Type | Description |
---|---|---|
command | string | Command to be executed during build time. Command must return an exit code 0. |
If the code block title is not provided, then the plugin will set it to Output
.
Example: Simple command​
For example, the following snippet will execute ls -l
and store the command's output in the code block.
```text command="ls -l"
```
Output
total 584
-rw-r--r-- 1 runner docker 209 Sep 7 19:15 Dockerfile
-rw-r--r-- 1 runner docker 3782 Sep 7 19:15 README.md
-rw-r--r-- 1 runner docker 89 Sep 7 19:15 babel.config.js
lrwxrwxrwx 1 runner docker 24 Sep 7 19:16 docs -> ../thin-edge.io/docs/src
-rw-r--r-- 1 runner docker 9360 Sep 7 19:15 docusaurus.config.js
-rw-r--r-- 1 runner docker 2062 Sep 7 19:15 justfile
drwxr-xr-x 804 runner docker 36864 Sep 7 19:16 node_modules
-rw-r--r-- 1 runner docker 1896 Sep 7 19:15 package.json
drwxr-xr-x 6 runner docker 4096 Sep 7 19:15 remark
drwxr-xr-x 2 runner docker 4096 Sep 7 19:15 scripts
-rw-r--r-- 1 runner docker 783 Sep 7 19:15 sidebars.js
drwxr-xr-x 5 runner docker 4096 Sep 7 19:15 src
drwxr-xr-x 3 runner docker 4096 Sep 7 19:15 static
drwxr-xr-x 4 runner docker 4096 Sep 7 19:15 versioned_docs
drwxr-xr-x 2 runner docker 4096 Sep 7 19:15 versioned_sidebars
-rw-r--r-- 1 runner docker 19 Sep 7 19:15 versions.json
-rw-r--r-- 1 runner docker 493596 Sep 7 19:15 yarn.lock
Example: Simple command with custom title​
Execute a command and store the output. Use a custom title for the code block.
```text command="ls -l" title="My custom title"
```
Output
total 584
-rw-r--r-- 1 runner docker 209 Sep 7 19:15 Dockerfile
-rw-r--r-- 1 runner docker 3782 Sep 7 19:15 README.md
-rw-r--r-- 1 runner docker 89 Sep 7 19:15 babel.config.js
lrwxrwxrwx 1 runner docker 24 Sep 7 19:16 docs -> ../thin-edge.io/docs/src
-rw-r--r-- 1 runner docker 9360 Sep 7 19:15 docusaurus.config.js
-rw-r--r-- 1 runner docker 2062 Sep 7 19:15 justfile
drwxr-xr-x 804 runner docker 36864 Sep 7 19:16 node_modules
-rw-r--r-- 1 runner docker 1896 Sep 7 19:15 package.json
drwxr-xr-x 6 runner docker 4096 Sep 7 19:15 remark
drwxr-xr-x 2 runner docker 4096 Sep 7 19:15 scripts
-rw-r--r-- 1 runner docker 783 Sep 7 19:15 sidebars.js
drwxr-xr-x 5 runner docker 4096 Sep 7 19:15 src
drwxr-xr-x 3 runner docker 4096 Sep 7 19:15 static
drwxr-xr-x 4 runner docker 4096 Sep 7 19:15 versioned_docs
drwxr-xr-x 2 runner docker 4096 Sep 7 19:15 versioned_sidebars
-rw-r--r-- 1 runner docker 19 Sep 7 19:15 versions.json
-rw-r--r-- 1 runner docker 493596 Sep 7 19:15 yarn.lock
Example: Simple command with default contents​
If you would like to make the code block still readable by other markdown renders (e.g. GitHub), then you can provide a sensible default value inside the code block.
Execute a command and store the output. Use a custom title for the code block.
```text command="ls -l" title="My custom title"
total 848
-rw-r--r--@ 1 tedge staff 209 Jun 22 11:13 Dockerfile
-rw-r--r-- 1 tedge staff 2718 Jul 4 15:31 README.md
-rw-r--r--@ 1 tedge staff 89 Jun 22 11:13 babel.config.js
drwxr-xr-x@ 21 tedge staff 672 Jul 4 15:13 build
lrwxr-xr-x@ 1 tedge staff 24 Jun 20 18:41 docs -> ../thin-edge.io/docs/src
-rw-r--r-- 1 tedge staff 6200 Jul 4 15:19 docusaurus.config.js
-rw-r--r-- 1 tedge staff 3296 Jul 3 17:36 justfile
drwxr-xr-x@ 751 tedge staff 24032 Jul 4 09:10 node_modules
-rw-r--r-- 1 tedge staff 1363 Jul 4 09:18 package.json
-rw-r--r--@ 1 tedge staff 781 Jun 22 11:13 sidebars.js
drwxr-xr-x@ 6 tedge staff 192 Jul 1 11:08 src
drwxr-xr-x@ 4 tedge staff 128 Jun 22 11:13 static
drwxr-xr-x@ 3 tedge staff 96 Jul 4 15:22 versioned_docs
drwxr-xr-x@ 3 tedge staff 96 Jul 3 18:55 versioned_sidebars
-rw-r--r--@ 1 tedge staff 10 Jul 4 15:22 versions.json
-rw-r--r-- 1 tedge staff 394026 Jul 4 09:18 yarn.lock
```
Output
total 584
-rw-r--r-- 1 runner docker 209 Sep 7 19:15 Dockerfile
-rw-r--r-- 1 runner docker 3782 Sep 7 19:15 README.md
-rw-r--r-- 1 runner docker 89 Sep 7 19:15 babel.config.js
lrwxrwxrwx 1 runner docker 24 Sep 7 19:16 docs -> ../thin-edge.io/docs/src
-rw-r--r-- 1 runner docker 9360 Sep 7 19:15 docusaurus.config.js
-rw-r--r-- 1 runner docker 2062 Sep 7 19:15 justfile
drwxr-xr-x 804 runner docker 36864 Sep 7 19:16 node_modules
-rw-r--r-- 1 runner docker 1896 Sep 7 19:15 package.json
drwxr-xr-x 6 runner docker 4096 Sep 7 19:15 remark
drwxr-xr-x 2 runner docker 4096 Sep 7 19:15 scripts
-rw-r--r-- 1 runner docker 783 Sep 7 19:15 sidebars.js
drwxr-xr-x 5 runner docker 4096 Sep 7 19:15 src
drwxr-xr-x 3 runner docker 4096 Sep 7 19:15 static
drwxr-xr-x 4 runner docker 4096 Sep 7 19:15 versioned_docs
drwxr-xr-x 2 runner docker 4096 Sep 7 19:15 versioned_sidebars
-rw-r--r-- 1 runner docker 19 Sep 7 19:15 versions.json
-rw-r--r-- 1 runner docker 493596 Sep 7 19:15 yarn.lock
Generic code block tabs​
Generic code block tabs can be created by adding the tab
directive to consecutive code blocks. This allows you to display the related code blocks in a tab format which not only saves spaces, but also give the user more control over what they want to focus on.
The directive is provided by the mrazauskas/docusaurus-remark-plugin-tab-blocks plugin.
Example: Simple tabs​
The following uses code blocks and uses the syntax highlighter option as the tab names. This only makes sense if you don't want to use syntax highlighting in your commands.
```systemd tab
systemctl status tedge
```
```openrc tab
service tedge status
```
Output
- systemd
- openrc
systemctl status tedge
rc-service tedge status
Example: Tabs with custom labels​
Custom labels can be added to each table by specifying the "label"
option on the tab
directive.
Below shows two sets of code blocks, the first being instructions how to connect the mapper to 3 different clouds, and the other set shows how to disconnect the mapper for the same clouds. By default any tabs that use the same label-name will be automatically synced.
**Connect mapper**
```sh tab={"label":"c8y"}
tedge connect c8y
```
```sh tab={"label":"az"}
tedge connect az
```
```sh tab={"label":"aws"}
tedge connect aws
```
**Disconnect mapper**
```sh tab={"label":"c8y"}
tedge disconnect c8y
```
```sh tab={"label":"az"}
tedge disconnect az
```
```sh tab={"label":"aws"}
tedge disconnect aws
```
Output
Connect mapper
- c8y
- az
- aws
tedge connect c8y
tedge connect az
tedge connect aws
Disconnect mapper
- c8y
- az
- aws
tedge disconnect c8y
tedge disconnect az
tedge disconnect aws
MQTT Code block​
One of the main interfaces for thin-edge.io is MQTT, therefore a special plugin has been created to display how to publish/subscribe to messages on an MQTT broker.
The code block only expects the writer to provide the tedge mqtt ...
command, and the plugin will take care of the translation to the various formats. The decision was made to use the tedge mqtt
command as the base format so that the code blocks would also still be useful when viewing the raw markdown documents.
The MQTT code block is activated by using the te2mqtt
directive. The directive will translate the tedge mqtt
command into the different variants and display them as a grouped tab. The reader is then able to select the tab which is relevant to their use-case and this setting will sticky (stored in their browser's local storage).
Example: Publish MQTT message​
The following shows how to document how to publish a single MQTT message.
Markdown
```sh te2mqtt formats=v1
tedge mqtt pub te/device/main///m/ '{"temperature": 21.3}'
```
Output
- tedge
- mosquitto
- mqtt
tedge mqtt pub 'te/device/main///m/' '{
"temperature": 21.3
}'
mosquitto_pub -t 'te/device/main///m/' -m '{
"temperature": 21.3
}'
te/device/main///m/
{
"temperature": 21.3
}
Example: Use legacy MQTT api​
The tedge api code blocks also have the option to set which formats should be displayed, for example the legacy or new v1 api.
Markdown
```sh te2mqtt formats=legacy,v1
tedge mqtt pub tedge/alarms/major/temp_hi_hi/child01 '{"text": "Temperature Hi Hi"}'
```
Output
- tedge
- mosquitto
- mqtt
tedge mqtt pub 'tedge/alarms/major/temp_hi_hi/child01' '{
"text": "Temperature Hi Hi"
}'
tedge mqtt pub 'te/device/child01///a/temp_hi_hi' '{
"text": "Temperature Hi Hi",
"severity": "major"
}'
mosquitto_pub -t 'tedge/alarms/major/temp_hi_hi/child01' -m '{
"text": "Temperature Hi Hi"
}'
mosquitto_pub -t 'te/device/child01///a/temp_hi_hi' -m '{
"text": "Temperature Hi Hi",
"severity": "major"
}'
API version: legacy
tedge/alarms/major/temp_hi_hi/child01
{
"text": "Temperature Hi Hi"
}
API version: v1
te/device/child01///a/temp_hi_hi
{
"text": "Temperature Hi Hi",
"severity": "major"
}
Example: Use new MQTT api​
The MQTT code block can also be written using the new MQTT api and the command will be automatically translated to the legacy (if there is an equivalent).
Markdown
```sh te2mqtt formats=legacy,v1
tedge mqtt pub te/device/child01///a/temp_hi_hi '{"text": "Temperature Hi Hi", "severity": "warning"}'
```
Output
- tedge
- mosquitto
- mqtt
tedge mqtt pub 'tedge/alarms/warning/temp_hi_hi/child01' '{
"text": "Temperature Hi Hi"
}'
tedge mqtt pub 'te/device/child01///a/temp_hi_hi' '{
"text": "Temperature Hi Hi",
"severity": "warning"
}'
mosquitto_pub -t 'tedge/alarms/warning/temp_hi_hi/child01' -m '{
"text": "Temperature Hi Hi"
}'
mosquitto_pub -t 'te/device/child01///a/temp_hi_hi' -m '{
"text": "Temperature Hi Hi",
"severity": "warning"
}'
API version: legacy
tedge/alarms/warning/temp_hi_hi/child01
{
"text": "Temperature Hi Hi"
}
API version: v1
te/device/child01///a/temp_hi_hi
{
"text": "Temperature Hi Hi",
"severity": "warning"
}