Markdown Guide

Every page on the developer documentation site is a markdown file (either a plain text file with the extension .md or a markdown file containing embedded JSX components with the extension .mdx). Markdown is a format that allows for easy and quick formatting that is easily converted to HTML. Mdx is an advanced Markdown format with React component support.

A detailed guide on how use Markdown with Nextra, the static site generator that powers this site, can be found in the Nextra Documentation Guide (opens in a new tab).

Front Matter

Front matter is optional for documentation written for docs.nhmlac.org. However, there might be instances where the features it provides are useful.

At the very top of a markdown file is the front matter. It includes metadata about a documentation page. The front matter is written in YAML, and is surrounded by three dashes. The front matter for this page is as follows:

---
title: Add & Edit Documentation
description: How to write documentation for docs.nhmlac.org
image: /images/documentation/add-edit-documentation.png
---

title: Determines the name of the page displayed in the sidebar, it does not change the title text of the page (that is determined by the h1 tag).
description: Determines the description of the page when shared on social media or a messaging app share cards.
image: Determines the image displayed when shared on social media or a messaging app share cards.

File types (.md vs .mdx)

There are two files types that can be used for documentation: Markdown (.md) and MDX (.mdx). Markdown is a lightweight markup language that is easy to learn and use. MDX is a superset of Markdown that allows for the use of JSX (React) components. For more information on MDX, refer to the MDX documentation (opens in a new tab).

There are two available components that can be used in docs.nhmlac.org MDX files: <Callout/> and Steps. For more information on these components, refer to the Markdown Guide page.

How to use an MDX component

To use an MDX component, import it at the top of the file, below the front matter. To see a list of available components, see Components. To use the <Callout/> component, for example, add the following line to the top of the file, below the front matter:

import { Callout } from 'nextra-theme-docs'

To add a Callout to the page, use the following syntax:

<Callout type="info">
  This is an info callout
</Callout>

Which should render as below:

This is an info callout

Headers

# This is an h1 header (there should only be one of me!)
## This is an h2 header
### This is an h3 header
#### This is an h4 header

Headers begin with number signs (#) in front of a word or phrase. The amount of number signs correspond to the heading level. For example, heading level three <h3> use three number signs (i.e. ### h3).

The h1 text, denoted with one number sign before the text, is often used as a title. Only one h1 element should exist in any document. For the documentation site, the title should reside in the front matter.

Headers are also used to the populate the table of contents (which resides in the right hand panel of each document), and are used for the documentation site's search engine.

Photos

To add an image, add an exclamation mark (!), and the path or URL to the image asset in parentheses. You can optionally add a title after the URL in the parentheses.

![Path to create Ticket Release](/photos/buyTickets/ticket-release-menu.png)

The url of the image must be placed in a public folder under the root of your project: nextra-docs/public/photos/. The photos folder contains subfolders with names that correspond to the names of pages.

Links

Links use a similar syntax as photos. To add a link, add the text that you want to be displayed in square brackets ([]), and the URL in parentheses.

[Link text](www.google.com)

Code and code blocks

Markdown provides two ways to present code — with inline code and fenced code blocks.

Inline code looks like this and is intended for individual words or phrases. When a snippet of code is presented a code block should be used, with syntax highlighting.

function example() {
  console.log("This is an example of a fenced code block with syntax highlighting");
}

Inline code is writen with surrounding backticks, such as`hi`.

Fenced code blocks begin with three backticks (```) and end with a matching set of three backticks.

Components

Below is a list of all available components that can be used in docs.nhmlac.org .mdx files and how to use them:

Callout

The Callout component is used to highlight important information. It can be used to display warnings, tips, or other information.

💡

This is a default callout

This is an info callout

⚠️

This is a warning callout

🚫

This is an alert callout

import { Callout } from 'nextra-theme-docs'
 
<Callout type="info">
  This is an info callout
</Callout>

type (optional): Determines the type (color and emoji) of callout. Options: 'default' | 'info' | 'warning' | 'error'.
emoji (optional): Determines the icon that is displayed in the callout.
children: The text that is displayed in the callout. (ReactNode).

Steps

The Steps component is used to display a list of steps. To use, wrap a set of markdown h3 headings with the Steps component to turn them into visual steps:

Step 1

Content for Step 1

Step 2

Content for Step 2

import { Steps } from 'nextra-theme-docs'
 
<Steps>
  ### Step 1
  Content for Step 1
 
  ### Step 2
  Content for Step 2
</Steps>

Installation Dokku