Page Structure

A MDX document generally consists of following 4 parts in the order of the list:

1. Frontmatter, where you can define metadata, like title, description, etc. of a page
2. Components imports needed on this page (optional)
3. Custom component exports needed on this page (optional)
4. Main content, mixing markdown and React components if required

#​Frontmatter

The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines. Currently we have 2 page standards, one that includes the usage of components while the other does not.

#​Standard Page

---
title: The Title
order: 0
---

The title above will be used in all navigational area, such as in the sidebar, breadcrumbs, browser tab title, etc. This field is the minimum required to start off a new page.

order is optional but recommended to be used to sort pages in the sidebar. It should always be an integer, and starting from 0. Please note that, this order number only affects the pages on the same level.

#​Component Page

For component pages, there are more metadata available to define the page.

---
title: The Title
order: 1
status: outdated
updated: 1999-12-31
designURL: https://example.com/design
codeURL: https://example.com/code
packageName: "@cloudflare/component-toast"
---

title and order are the same as standard page template, see above. status is optional and currently not being used. The idea is to mark certain component/document deprecated later on. updated is required and is used to indicate the last time this documentation page was updated. designURL and codeURL are optional and are used to link to the design file and source code of the component. packageName is required and is used to show related information of this component.

#​Main content

If you are familiar with markdown, there is no surprise to you to start writing. Still, this is a good reference of the markdown syntax. The key difference between MDX and a common markdown is its ability to add in React components to extend existing markdown syntax.

<Example>

This is an example box container mixing `React component` and `markdown` shown below.

</Example>

Notice the new line between React enclosing and markdown text? This is a requirement for the MDX syntax to recognise that the piece of text is actually markdown content instead of a string. Without the new line as shown below, markdown syntax would not be recognised.

To view the full list of all React components that can be used directly without importing, please refer to this page.

Lastly, number of heading 1 or # Heading should not exceed one per page. If there is no heading 1 present in a document, the title field in frontmatter will be used as the heading 1.