Write MDX

Smooth DOC uses MDX under the hood. A powerful markup language!

Use markdown syntax

MDX supports Markdown out of the box. Creating a page is easy as:

# Title of the page
Content of your page.

To learn more about markdown, see markdown cheatsheet.


Features like title, slug and navigation information take place in the frontmatter — a section present at the top of the markdown file written in YAML syntax.

title: Write MDX # Title of your page
slug: /docs/write-mdx/ # Slug of your page (uses file name as default)
section: Usage # Sidebar navigation group title
order: 2 # Order in the sidebar navigation group
Your page content...


To include a highlighted code snippet, use markdown code block syntax followed by language. Syntax highlighting is built-in thanks to Prism.

An example of code block:
const foo = 'bar'

Read React Live Editor Guide to learn how to create interactive examples.

Supported languages

By default, all languages included in prism-react-renderer are supported.

If you want to highlight code in another language such as Ruby or Rust, you can enable it by adding the following in gatsby-browser.js (see GitHub issue):

import Prism from 'prism-react-renderer/prism'
(typeof global !== 'undefined' ? global : window).Prism = Prism

Custom components

MDX allows you to include your own components. To do it, add an import statement directly in your MDX file and use your component.

name: Hello world
import { Button } from './Button'
# Hello world
Hello, I'm still a MDX file, but now I have a button component !
<Button onClick={() => { alert("You clicked me"); }}>Click me</Button>
Edit this page on GitHub