Skip to main content

Markdown Guide

This section contains guidelines and examples for how to use markdown, specifically for Docusaurus.

MDX​

One feature of Docusaurus is that it supports the popular MDX standard. This it what allows it to embed dynamic react components.

MDX is a superset of markdown that lets you write JSX directly in your markdown files. It is a powerful way to add dynamic interactivity, and embed components within your content, helping you to bring your pages to life.

Why use MDX?

Authoring in markdown is an intuitive way to write content, its terse syntax, once adopted, can enable you to write content that is both readable and maintainable. Because you can use HTML elements in your markdown, you can also get creative when styling your markdown pages. However, because markdown is essentially static content, you can't create dynamic content based on user interactivity. Where MDX shines is in its ability to let you create and use your React components directly in the markup. This opens up a wide range of possibilities when composing your sites pages with interactivity in mind.

Read more here:

Plugins​

There exists a community around MDX with available open-source plugins, allowing to extend the project with pre-built functionality.

If you wish to integrate a new MDX Plugin, reach out to CST, as this decision needs to be taken on a holistic level.

Read more here:

Front matter​

At the top of each docs page, there is a section where you can specify page metadata as front matter.

The following is the minimum required front matter on each page, divided by content section:

---
title: Markdown Guide
sidebar_label: Markdown Guide
sidebar_position: 3              
last_update:
  author: Jane Doe
---

List of selected front matter:

NameTypeDefaultDescription
titlestringFirst headline of the pageThe text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title
last_update - authorstringN/AOwner of the page, to whom one would reach out for questions. Only shown on internal portal. Format: Firstname Lastname.
last_update - datestringN/ADate of last review. Only shown on internal portal. Format: month/day/year.
slugstringN/AAllows to customize the document URL. Example: "myDoc" will replace only the filename, "/myDoc" will replace everything from the routeBasePath of the product. For more info see: https://docusaurus.io/docs/create-doc#doc-urls
descriptionstringThe first sentence of the documentThe description of your document, which will become metadata used by search engines.
tags[string, string]N/ATags show up at the end of the document. Clicking on tags show other entries within the same plugin instance. Edgenius is implemented as a single plugin instance.
draftboolfalseSet to true to only show document during local development, and hide it from production deployments.
pagination_labelstringTitle of the next pageThe text used in the document next/previous buttons for this document
custom_edit_urlstringN/AThe URL for editing this document. Use null to disable showing "Edit this page" for this page
keywords[string, string]N/AKeywords meta tag for the document page, for search engine. Example:
- docs
- edgenius
imagestringN/AURL to cover or thumbnail image that will be used when displaying the link to your post.

For a full list and up to date explanation, see the Docusaurus docs.

note

Most of front matter does not impact md/mdx files placed in the pages folder. Title still works to set the browser tab title.

Draft toggle​

Purpose: Hide single pages from builds.

Docusaurus has a concept of "drafts" within the docs folder, where there is a front matter parameter called "draft" that can be set to either true or false (default). If set to true, the page is not rendered during builds (both internal and external), but only for the local development server (controlled by the NODE_ENV env variable which can not be modified).

Limitations:

  • Does not work on non-docs pages (even markdown pages in /pages folder), those used for navigation. These are however mostly unversioned.
  • The risk is quite high that someone accidentally change this parameter, thus unintentionally expose draft documentation. Therefore this should not be the primary method of excluding larger sections/products.

Headings and titles​

People accessing this documentation may use a screen reader or other assistive technology (AT). Screen readers are linear output devices, they output items on a page one at a time. If there is a lot of content on a page, you can use headings to give the page an internal structure. A good page structure helps all readers to easily navigate the page or filter topics of interest.

DoDon't
Update the title in the front matter of the page.Use first level heading, as Docusaurus automatically converts the title matter of the page into a first-level heading in the front. Most importantly, don't use both.
Use ordered headings to provide a meaningful high-level outline of your content.Use headings level 4 through 6, unless it is absolutely necessary. If your content is that detailed, it may need to be broken into separate articles.

It is possible to set a custom id for each heading, in case the heading text needs to be repeated within the page. If the heading is duplicated, the URL will be numbered (such as #headings-1). Observe the heading of this section, which translates to a URL of #headings using the following syntax:

## Headings and titles \{#headings}

Lists​

Group items in a list that are related to each other and need to appear in a specific order or to indicate a correlation between multiple items. When a screen reader comes across a list---whether it is an ordered or unordered list---it will be announced to the user that there is a group of list items. The user can then use the arrow keys to move up and down between the various items in the list. Website navigation links can also be marked up as list items; after all they are nothing but a group of related links.

  • End each item in a list with a period if one or more items in the list are complete sentences. For the sake of consistency, normally either all items or none should be complete sentences.
    Note

    Ordered lists that are part of an incomplete introductory sentence can be in lowercase and punctuated as if each item was a part of the introductory sentence.

  • Use the number one (1.) for ordered lists.
  • Use (+), (*), or (-) for unordered lists.
  • Leave a blank line after each list.
  • Indent nested lists with four spaces (for example, ⋅⋅⋅⋅).
  • List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either four spaces or one tab.

Numbered lists with additional elements​

Sometimes lists are interrupted by additional elements. This example shows how to keep the numbering by using indentation.

Code:

1. Item one
    ```sh
    This is some code
  1. Item two Docusaurus image
  2. Item three
    1. Sub item 1 
      This is some code
    2. Sub item 2 with some extra distance to image

      Docusaurus image
  3. Item four
Render:
1. Item one
    ```sh
    This is some code
  1. Item two Docusaurus image
  2. Item three
    1. Sub item 1 
      This is some code
    2. Sub item 2 with some extra distance to image

      Docusaurus image
  3. Item four

Tables​

The semantic purpose of a data table is to present tabular data. Sighted users can quickly scan the table but a screen reader goes through line by line. A table caption is used to create a descriptive title for a data table. Assistive technologies (AT) use the HTML table caption element to identify the table contents to the user within the page structure.

While HTML table tags are supported, do avoid them and use the following simple markdown format whenever possible:

| Heading | Heading |
| -- | -- |
| Content | Content|
tip

In cases where it is imperative that you include a note, caution or tip as part of the table content, refer Admonitions.

Add lists or line breaks in tables​

To add lists or introduce line breaks in tables:

| Heading | Heading |
| -- | -- |
| Content | Content|
| Content | Content<br /> -item1 <br /> - item2<br />|
| Content | Content<br /> Content in next line in the cell.|

Images​

The simplest approach to adding an image is using the markdown syntax:

![image.png](./.attachments/image207.png)

If there is a need to style the image (for instance to fit in line with text), then a JSX image tag need to be used. Note that the formatting is in JSX and not HTML (which may break).

<img
  src={require("./.attachments/image207.png").default}
  style={{width: "3.4in", height: "2.4in"}} 
/>

Diagrams​

Diagrams are similar to images, but with the additional need to be able to update the diagram.

Recommendations:

  • Use draw.io to create the diagram, either browser or desktop client
  • Save the draw.io diagram to the .attachments folder on the same folder level
  • Export the diagram to a .png file and also place this one in the .attachments folder
  • Only keep the latest version of the .png file. Keep more versions in the .drawio file.
caution

Do NOT include a copy of your diagram in the export. Make sure that this file extension does not include .drawio. If it does, then users can download the images and get access to the files, which may include other sensitive information.

DoDon't
Write Markdown-style links: [link text](URL). For example:
[Contributing to UserDoc](./Contributing) .		Write HTML-style links:
<a href="/Contributing.html" target="_blank"> Contributing to UserDoc</a>
Create links that open in new tabs or windows. For example: [example website](https://example.com){target="_blank"}
note

Do not include the file extension in the link, like (./Contributing.md). This may be auto-suggested by editors, but it will be treated like a broken link in Docusaurus.

Anchors​

If you're linking to a markdown file with an anchor (e.g.[Link](./markdownfile#anchor)) follow these rules for the links validation to work correctly:

  • Use only lower case letters
  • If the anchor points to a header that consists of a few words, in the anchor separate words by hyphens (e.g. # My Header -> [article](./article#my-header))

Admonitions​

Admonitions are used to accentuate some information for the user. The syntax is as follows:

:::note[Optional Title]

Some **content** with _Markdown_ `syntax`.

:::

Above syntax produces the following result:

Optional Title

Some content with Markdown syntax.

Guidelines:

  • It is advised to skip the optional title. Sticking to the defaults aligns the style across the portal.
  • Make sure to have spacing between the content and the tags, reason explained here.

The following options are available in the current version of the theme:

Electrical Warning

It indicates the presence of a hazard that could result in electrical shock.

warning

It indicates the presence of a hazard that could result in a plant shutdown or personal injury.

caution

It indicates the presence of a hazard that could result in corruption of software or damage to equipment/property.

tip

It indicates advice on, for example, how to design project or how to use a certain function.

note

It highlights important information pertaining to a particular descriptive text (for example: 'Module description', 'Installation', 'Configuration', or 'Operational procedure', etc.) in the document.

info

Similar to NOTE, use NOTE instead unless specifically needed.

It is also possible to use JSX instead of markdown syntax. The import statement should be placed right below the document front matter in the top of the document. The snippets below shows the usage in both a markdown table.

---
import Admonition from '@theme/Admonition';


| Markdown Table | Description |
|-- | -- |
| Placeholder  | Placeholder <br /><br /><Admonition type="info"><p>Some other information</p></Admonition>|
| Placeholder | Placeholder |

Above syntax produces the following result:

Markdown TableDescription
PlaceholderPlaceholder

info

Some other information

PlaceholderPlaceholder

If styling of the table is required, then JSX syntax is required:

<table>
<colgroup>
<col style={{width: "30%"}} />
<col style={{width: "69%"}} />
</colgroup>
<thead>
<tr class="header">
<th>
<strong>JSX Table</strong>
</th>
<th>
<strong>Placeholder</strong>
</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>
Placeholder
</td>
<td>
Placeholder
<br />
<br />
<Admonition type="info">
<p>Some information</p>
</Admonition>
</td>
</tr>
</tbody>
</table>

Above syntax produces the following result:

JSX TablePlaceholder

Placeholder

Placeholder



info

Some information

It's possible to add custom admonitions, such has been done for electrical warning. In order to do this, you need to extend the theme here, and also add the option to the metadocs config like below, including all other admonitions also:

{
    "github-example": {
        "title": "Github Example",
        "packageName": "@abb-iiot-test/github-example-docs",
        "admonitions": {
            "keywords": ["note", "tip", "info", "caution", "danger", "warning", "electricalwarning"],
        }
    }
},

You can read more about admonitions in the Docusuarus docs here.

Code Blocks​

The code block allows the user to easily copy the code. To create a code block, use the following syntax:

```md
<code>
```

Remember to specify the source language.

Formatting​

DoDon't
Use meaningful variable names that have a context.Use variable names such as 'foo','bar', and 'baz' that are not meaningful and lack context.
Remove trailing spaces in the code.Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well.
Remove the command prompt: kubectl get nodes\$ kubectl get nodes

  • Don't use multi-line blocks of code to create diagrams, flowcharts, or other illustrations.

  • Separate commands from output

    Verify that the pod is running on your chosen node:

    kubectl get nodes

    The output is similar to this:

    NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
    nginx    1/1       Running   0          10s    12.100.0.1   worker0

Inline Code Block​

The inline code block is used to indicate code in line with text, created by enclosing the statement in either one or two backticks (`).

DoDon't
Use single backticks to enclose inline code. For example, var example = true.Use two asterisks (**) or an underscore (_) to enclose inline code. For example, var example = true.
The npm run docs:dev command launches the site on the localhost.The "npm run docs:dev" command launches...

Tabs​

Tabs allow you to toggle between different content depending on the context. One example is different guides based on Github and ADO.

This is a guide for Github.

To set this up, first add the following import statement directly under the front matter.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Then use this syntax to create the tabs. You can sync the user selection across tabs by using the same groupId.

---
<Tabs groupId="provider">
<TabItem value="Github" >

This is a guide for Github.

</TabItem>
<TabItem value="Azure DevOps">

This is a guide for Azure DevOps.

</TabItem>
</Tabs>

Math​

Mathematical equations can be rendered using KaTeX.

For more information, read the Docusaurus docs.

Inline​

Code:

Let $f\colon[a,b]\to\R$ be Riemann integrable. Let $F\colon[a,b]\to\R$ be
$F(x)=\int_{a}^{x} f(t)\,dt$. Then $F$ is continuous, and at all $x$ such that
$f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$.

Render:

Let f ⁣:[a,b]→Rf\colon[a,b]\to\R be Riemann integrable. Let F ⁣:[a,b]→RF\colon[a,b]\to\R be F(x)=∫axf(t) dtF(x)=\int_{a}^{x} f(t)\,dt. Then FF is continuous, and at all xx such that ff is continuous at xx, FF is differentiable at xx with F′(x)=f(x)F'(x)=f(x).

Blocks​

Code:

$$
I = \int_0^{2\pi} \sin(x)\,dx
$$

Render:

I=∫02πsin⁡(x) dxI = \int_0^{2\pi} \sin(x)\,dx

Line breaks​

To create a newline, use the following syntax:

<br />

Regarding formatting: Use a single newline to separate block-level content like headings, lists, images, code blocks, and others. The exception is second-level headings, where it should be two newlines. Second-level headings follow the first-level (or the title) without any preceding paragraphs or texts. A two line spacing helps visualize the overall structure of content in a code editor better.

Footnotes​

It is possible to add footnotes in markdown. These will appear at the bottom of the page.

Here we add a footnote [^1].

[^1]: This is a footnote

Render:

Here we add a footnote 1.

caution

For PDF generation, these footnotes will be placed after the full web page, not after the same page as the footnote. The link will however work.

Consider other solutions if the page is long and it would be hard for the user to follow the footnote in a printed version.

It is possible to place a the footnote description where you want it by omitting the colon (:) [^2].

[^2] But note that the link does not work in this case. Be careful during PDF generation so that these are placed well.

Collapsible component​

Here is a collapsible component

<details>
<summary>How do I do action A?</summary>
This is how you solve this.
</details>
Details

How do I do action A? This is how you solve this.

Quote​

> This is a quoted statement

This is a quoted statement

Videos​

The strategy for including videos depends on the size and origin of the video. Most videos (especially if they have a large file size) are preferably stored separate from the portal repo, for instance in sharepoint, and then IFramed in. It is however still possible to store smaller videos (e.g. <10mb .mp4 videos) in the portal repo, for instance for animated banners, which require a better responsiveness.

Local File​

If a video file is stored in the repo, use this syntax:

Code:

import ReactPlayer from 'react-player';

<ReactPlayer url={"/general/banner-video.mp4"} width="100%" height="100%" controls={false} playing={true} muted={true} loop={true}/>

Render:

IFrame​

To include a video from sharepoint (which is the foundation for all Microsoft Teams and OneDrive storage), navigate to the website of that video and click the share button, then select Embed code.

Select the video size and toggle on Responsive (this will improve resizing of video with different screen sizes).

Copy the code from the box below, and paste this into the MDX page. See the following subsections for how to reformat the parameters to be JSX compatible.

Imported Markdown​

It is possible to import markdown from other files. This is useful if you want to reuse content in multiple places.

Code:

---
<frontmatter>
---
import ImportExample from './_import-example.md'

<ImportExample />

Render:

Imported Example​

This is an imported markdown file.

Limitations:

  • The filepath can't include a dot. Example: ./_atttachments/_import-example.md works, but ./.attachments/_import-example.md does not work.
  • The imported file extention can be either mdx or md, but MD (uppercase) does not work.

DocCard​

This is a single DocCard.

Code:

---
<frontmatter>
---
import DocCard from '@theme/DocCard';
import DocCardList from '@theme/DocCardList';

export const new_item = {
    docId: "markdown-guide",
    href: "./markdown-guide",
    label: "Markdown Guide",
    type: "link"  
}

<DocCard item={new_item} />

Render:

📄️ Markdown Guide

This section contains guidelines and examples for how to use markdown, specifically for Docusaurus.

DocCardList​

This is DocCardList with multiple DocCards.

Code:

---
<frontmatter>
---
import DocCard from '@theme/DocCard';
import DocCardList from '@theme/DocCardList';

export const new_item_list = [
    {
        docId: "markdown-guide",
        href: "./markdown-guide",
        label: "Markdown Guide",
        type: "link"   
    },{
        docId: "markdown-guide",
        href: "./markdown-guide",
        label: "Markdown Guide",
        type: "link"    
    },{
        docId: "markdown-guide",
        href: "./markdown-guide",
        label: "Markdown Guide",
        type: "link" 
    }
]

<DocCardList items={new_item_list} />

Render:

HTML pages​

If you want to include a larger HTML page without rewriting the syntax to JSX, then you can IFrame it like below. It requires the page to be placed in the static folder.

TODO: solve how to dynamically fit height to content.

Code:

<iframe id="myIframe" src='/pages/status-placeholder.html' width="100%" height="2200" scrolling="no" ></iframe>

Render:

Footnotes​

  1. This is a footnote ↩