MDX Syntax here in Nextra

MDX is a combination of Markdown and JSX, and regular Markdown syntax can be used for most formatting. What follows is a guide to the Markdown syntax supported by Gatsby. Each section gives the Markdown syntax, the HTML element it creates, and a demonstration of the element.

Syntax Highlighting

```js
console.log('hello, world')
```

Results in:

console.log('hello, world')

Inlined Code

Inlined syntax highlighting like let x = 1 is also supported via the {:} syntax:

Inlined syntax highlighting is also supported `let x = 1{:jsx}` via:

Highlighting Lines

You can highlight specific lines of code by adding a {} attribute to the code block:

```js {1,4-5}
import { useState } from 'react'
 
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}
```

Result:

import { useState } from 'react'
 
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

Highlighting Substrings

You can highlight specific substrings of code by adding a // attribute to the code block:

```js /useState/
import { useState } from 'react'
 
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}
```

import { useState } from 'react'
 
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

You can highlight only a part of the occurrences of that substring by adding a number it: /str/1, or multiple: /str/1-3, /str/1,3.

Copy Button

By adding a copy attribute, a copy button will be added to the code block when the user hovers over it:

```js copy
console.log('hello, world')
```

Renders:

console.log('hello, world')

You can enable this feature globally by setting defaultShowCopyCode: true in your Nextra configuration (next.config.js file). Once it's enabled globally, you can disable it via the copy=false attribute.

Line Numbers

You can add line numbers to your code blocks by adding a showLineNumbers attribute:

```js showLineNumbers
import { useState } from 'react'
 
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}
```

Renders:

import { useState } from 'react'
 
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

Filenames and Titles

You can add a filename or a title to your code blocks by adding a filename attribute:

```js filename="example.js"
console.log('hello, world')
```

Renders:

console.log('hello, world')

Link

Click here to read more.

Click [here](/about) to read more.

Will be equivalent to:

import Link from 'next/link'
 
Click <Link href="/about">here</Link> to read more.

Image

import Image from 'next/image'
 
<Image src="/demo.png" alt="Hello" width={500} height={500} />

Static Image

Nextra supports automatically optimizing your static image imports with the Markdown syntax. You do not need to specify the width and height of the image, just use the ![]() Markdown syntax:

![Hello](/demo.png)

This loads the demo.png file inside the public folder, and automatically wraps it with Next.js <Image>.

With Next.js Image, there will be no layout shift, and a beautiful blurry placeholder will be shown by default when loading the images

Video

export function Video() {
  return (
    <video width="320" height="auto" controls preload="none">
      <source src="/videos/outro.mp4" type="video/mp4" />
      
      Your browser does not support the video tag.
    </video>
  )
}
 
<Video/>
 
 

Headings

Headings are usually created in Markdown with a set of hash (#) characters placed before the text for the heading, with a space in between (this space is required in Gatsby). The number of hashes corresponds to the level of the heading (i.e., # corresponds to a first-level heading, or the <h1> HTML tag).

There is alternative syntax for <h1> and <h2> headings:

Emphasis

Italics

To mark text in italics, add an asterisk (*) or underscore (_) before and after the text to be formatted.

Bold

To mark text in boldface, add two asterisks (**) or two underscores (__) before and after the text to be formatted.

Bold and italics together

To emphasize text with both boldface and italics, use three asterisks (***) or three underscores (___) before and after the text to be formatted.

Note To emphasize text with bold or italics in the middle of a sentence, use asterisks but not underscores. For example,

middle **of** sentence becomes middle of sentence, but

middle_of_sentence becomes middle_of_sentence.

The underscores only work when there is spacing before and after the emphasized word.

Line breaks

To create a line break, follow a line with two spaces and then hit enter.

This is the first line.
This is the second line.

<hr/>

just type 3 dashes

---

Block quotes

type this > before the centense

you git this

This is a Block quote

Lists

Unordered lists

* Oranges
* Apples

+ Oranges
+ Apples

- Oranges
- Apples

This renders as

• Oranges
• Apples

Ordered lists

1. Oranges
2. Apples

This renders as

1. Oranges
2. Apples

Nested lists

* Apples
* Oranges
* Berries
    * Strawberries
    * Raspberries

This renders as

• Apples
• Oranges
• Berries
  • Strawberries
  • Raspberries

Built-ins Components

Nextra includes a couple of built-in components that you can use to better style your content:

Callout

Examples

Default

import { Callout } from 'nextra/components'
 
<Callout emoji="👾">
  **Space Invaders** is a 1978 shoot 'em up arcade game developed by Tomohiro
  Nishikado.
</Callout>

Info

import { Callout } from 'nextra/components'
 
<Callout type="info" emoji="ℹ️">
  Today is Friday.
</Callout>

Warning

import { Callout } from 'nextra/components'
 
<Callout type="warning" emoji="⚠️">
  This API will be deprecated soon.
</Callout>

Error

import { Callout } from 'nextra/components'
 
<Callout type="error" emoji="️🚫">
  This is a dangerous feature that can cause everything to explode.
</Callout>

Cards

Examples

Usage

import { Cards, Card } from 'nextra/components'
 
<Cards>
  <Card title="Callout" href="/..." />
  <Card title="Tabs" href="/..." />
  <Card title="Steps" href="/..." />
</Cards>

Tabs

Example

Default

import { Tabs } from 'nextra/components' 
 
<Tabs items={['pnpm', 'npm', 'yarn']}>
  <Tabs.Tab>**pnpm**: Fast, disk space efficient package manager.</Tabs.Tab>
  <Tabs.Tab>**npm** is a package manager for the JavaScript programming language.</Tabs.Tab>
  <Tabs.Tab>**Yarn** is a software packaging system.</Tabs.Tab>
</Tabs>

Default Selected Index

You can use the defaultIndex prop to set the default tab index:

import { Tabs } from 'nextra/components'
 
<Tabs items={['pnpm', 'npm', 'yarn']} defaultIndex="1">
  ...
</Tabs>

And you will have npm as the default tab:

Steps

Usage

Wrap a set of markdown h3 headings with the Steps component to turn them into visual steps.

import { Steps } from 'nextra/components'
 
<Steps>
### Step 1
 
Contents for step 1.
 
### Step 2
 
Contents for step 2.
</Steps>

File Tree

Example

Usage

 
<FileTree>
  <FileTree.Folder name="pages" defaultOpen>
    <FileTree.File name="_meta.json" />
    <FileTree.File name="contact.md" />
    <FileTree.File name="index.mdx" />
    <FileTree.Folder name="about">
      <FileTree.File name="_meta.json" />
      <FileTree.File name="legal.md" />
      <FileTree.File name="index.mdx" />
    </FileTree.Folder>
  </FileTree.Folder>
</FileTree>

Escaping characters

Certain characters, such as the hash symbol (#) and the plus sign (+), can be interpreted by Markdown as part of its syntax. To print one of these characters literally on screen, you can escape it using a backslash (\). For example, \\ prints the \ character itself.

Alternatively, treat the symbol as inline code or a code block by enclosing it in backticks (`). Note, however, that this will change its font and/or background color.

The following characters can be escaped using a backslash (\) to ensure they are rendered literally on screen:

To escape a fenced code block, increase the number of backticks in the outer code block:

````

outer code block

```
inner code block
```

````

This renders as

outer code block

```
inner code block
```