Markdown
MDX
删除线
~~removed~~
效果
removed
任务列表
- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media
效果
- Write the press release
- Update the website
- Contact the media
表格
| Syntax | Description | Test Text |
| :------------ | :---------: | ----------: |
| Header | Title | Here's this |
| Paragraph | Text | And more |
| Strikethrough | | ~~Text~~ |
效果
Syntax | Description | Test Text |
---|---|---|
Header | Title | Here's this |
Paragraph | Text | And more |
Strikethrough |
自动链接
Visit https://nextjs.org.
效果
Visit https://nextjs.org (opens in a new tab).
语法高亮
Nextra 使用 Shiki (opens in a new tab) 在构建时进行语法高亮。它非常可靠且高效。例如,在你的 Markdown 文件中添加这个:
```js
console.log('hello, world')
```
效果
console.log('hello, world')
内嵌代码
Inlined syntax highlighting is also supported `let x = 1{:jsx}` via:
效果
Inlined syntax highlighting is also supported let x = 1
via:
高亮行
可以通过给代码块添加一个 属性来高亮特定的代码行:
```js {1,4-5}
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>
}
高亮子字符串
可以通过给代码块添加一个 // 属性来高亮特定的代码 子字符串: 例如下面将高亮 useState
```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>
}
复制按钮
通过添加一个 copy
属性,在用户悬停在代码块上时会添加一个复制按钮:
```js copy
console.log('hello, world')
```
效果
console.log('hello, world')
或者 next.config.js
文件中设置 defaultShowCopyCode: true
来全局启用这个功能。
const withNextra = require('nextra')({
defaultShowCopyCode: true
})
一旦它在全局启用了,你可以通过 copy=false 属性来禁用它。
```js copy=false
console.log('hello, world')
```
效果
console.log('hello, world')
行号
可以通过添加一个 showLineNumbers 属性来给代码块添加行号:
```js showLineNumbers
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>
}
文件名和标题
可以通过添加 filename 属性为代码块添加文件名或标题:
```js filename="example.js"
console.log('hello, world')
```
效果
console.log('hello, world')
ANSI 高亮
可以突出显示 ANSI 转义码
```ansi
[0m [0;32m✓[0m [0;2msrc/[0mindex[0;2m.test.ts (1)[0m
[0;2m Test Files [0m [0;1;32m1 passed[0;98m (1)[0m
[0;2m Tests [0m [0;1;32m1 passed[0;98m (1)[0m
[0;2m Start at [0m 23:32:41
[0;2m Duration [0m 11ms
[42;1;39;0m PASS [0;32m Waiting for file changes...[0m
[0;2mpress [0;1mh[0;2m to show help, press [0;1mq[0;2m to quit
```
效果
✓ src/index.test.ts (1)
Test Files 1 passed (1)
Tests 1 passed (1)
Start at 23:32:41
Duration 11ms
PASS Waiting for file changes...
press h to show help, press q to quit
自定义主题
Nextra 使用 CSS 变量来定义标记的颜色。您可以注入 全局 CSS (opens in a new tab) 以在亮色/暗色主题下进行自定义。例如,这是默认的 标记,您可以覆盖其中的任何一个:
:root {
--shiki-color-text: #414141;
--shiki-color-background: transparent;
--shiki-token-constant: #1976d2;
--shiki-token-string: #22863a;
--shiki-token-comment: #aaa;
--shiki-token-keyword: #d32f2f;
--shiki-token-parameter: #ff9800;
--shiki-token-function: #6f42c1;
--shiki-token-string-expression: #22863a;
--shiki-token-punctuation: #212121;
--shiki-token-link: #22863a;
}
.dark {
--shiki-color-text: #d1d1d1;
--shiki-token-constant: #79b8ff;
--shiki-token-string: #ffab70;
--shiki-token-comment: #6b737c;
--shiki-token-keyword: #f97583;
--shiki-token-parameter: #ff9800;
--shiki-token-function: #b392f0;
--shiki-token-string-expression: #4bb74a;
--shiki-token-punctuation: #bbb;
--shiki-token-link: #ffab70;
}
禁用语法高亮 ???
您可以选择不使用内置的语法高亮显示功能,而使用自己的方式。 您可以在 Nextra 配置 (next.config.js
文件) 中设置 codeHighlight: false
来全局禁用语法高亮显示。
自定义主题
在 mdxOptions.rehypePrettyCodeOptions
中,你也可以提供自定义主题,而不是依赖 CSS 变量:
nextra({
// ... other options
mdxOptions: {
rehypePrettyCodeOptions: {
// VSCode theme or built-in Shiki theme, see Shiki documentation for more information
theme: JSON.parse(
readFileSync('./public/syntax/arctis_light.json', 'utf8')
)
}
}
})
Next.js 图片
在 MDX 中使用 Next.js 图片 的标准方式是直接导入组件:

静态图片
此功能默认通过 Nextra 配置中的 staticImage: true 启用。
Nextra 支持使用 Markdown 语法自动优化静态图片导入。您无需指定图片的宽度和高度,只需使用 ![]()
Markdown 语法:

这会加载public
文件夹中的demo.png
文件,并自动使用 Next.js <Image>
将其包装。
如果您不想通过 public 托管图像,还可以使用 
从相对路径加载图像。
使用 Next.js 图片,加载图像时不会有布局变化,并且默认情况下会显示一个漂亮的模糊占位符:
Next.js SSG 静态生成
使用 Next.js,你可以使用 静态生成 (SSG) (opens in a new tab) 预渲染你的页面。你的页面将在构建时生成,并以静态方式提供给访问者。它也可以由 CDN 缓存,以最大化性能。
Nextra 也支持这个功能。以下是一个示例:
注:TODO 此处样式没生效待处理
Nextra 在Github上现在有 12670 颗Star!
上面的数字是通过 getStaticProps
在构建时生成的。 启用了 增量静态再生 (opens in a new tab) 后,它将保持最新状态。
下面是上述示例的 MDX 代码:
import { useData } from 'nextra/data'
export const getStaticProps = ({ params }) => {
return fetch(`https://api.github.com/repos/shuding/nextra`)
.then(res => res.json())
.then(repo => ({
props: {
// We add an `ssg` field to the page props,
// which will be provided to the Nextra `useData` hook.
ssg: {
stars: repo.stargazers_count
}
},
// The page will be considered as stale and regenerated every 60 seconds.
revalidate: 60
}))
}
export const Stars = () => {
// Get the data from SSG, and render it as a component.
const { stars } = useData()
return <strong>{stars}</strong>
}
Nextra 在Github上现在有 <Stars /> 颗Star!
Next.js I18n 多语言支持
Nextra 支持Next.js 国际化路由 (opens in a new tab)。这些文档解释如何配置和使用它。
添加国际化配置
To add multi-language pages to your Nextra application, you need to config
i18n
in next.config.js
first:
const withNextra = require('nextra')({
theme: 'nextra-theme-docs',
themeConfig: './theme.config.tsx'
})
module.exports = withNextra({
i18n: {
locales: ['en-US', 'zh-CN', 'de-DE'],
defaultLocale: 'en-US'
}
})
添加中间件
然后,你需要在你项目的根目录中添加一个 middleware.js 文件 (相关 Next.js 文档 (opens in a new tab)):
export { locales as middleware } from 'nextra/locales'
如果已经定义了中间件,则可以改为执行以下操作:
import { withLocales } from 'nextra/locales'
export const middleware = withLocales(request => {
// Your middleware code...
})
将地区代码添加到文件名中
然后,将地区代码添加到你的文件扩展名中(默认地区也必需添加):
/pages
_meta.en-US.json
_meta.zh-CN.json
_meta.de-DE.json
index.en-US.md
index.zh-CN.md
index.de-DE.md
...
配置文档主题
最后,将 i18n
选项添加到你的 theme.config.jsx
中,以配置语言下拉菜单:
i18n: [
{ locale: 'en-US', text: 'English' },
{ locale: 'zh-CN', text: '中文' },
{ locale: 'de-DE', text: 'Deutsch' },
{ locale: 'ar-SA', text: 'العربية', direction: 'rtl' }
]
自定义CSS
Nextra 与 Next.js 的内置 CSS 支持完全兼容, 包括 .css
、.module.css
和 Sass(.scss
、.sass
、.module.scss
、.module.sass
)文件。
例如,考虑以下名为 styles.css
的样式表:
body {
font-family: 'SF Pro Text', 'SF Pro Icons', 'Helvetica Neue', 'Helvetica',
'Arial', sans-serif;
padding: 20px 20px 60px;
max-width: 680px;
margin: 0 auto;
}
你可以创建一个 pages/_app.js
文件,并在那里导入你的 CSS 文件:
import '../styles.css'
// This default export is required in a new `pages/_app.js` file.
export default function MyApp({ Component, pageProps }) {
return <Component {...pageProps} />
}
要了解更多关于 Next.js 中的 CSS 支持,请查看Next.js (opens in a new tab) 文档。
高级
LaTeX
Nextra 使用 KaTeX (opens in a new tab) 来直接在 MDX 中渲染 LaTeX 表达式。 要启用 LaTeX 支持,你必须在你的 next.config.js 文件中启用 latex 选项:
module.exports = require('nextra')({
latex: true
})
当启用时,KaTeX的CSS和字体将自动包含在您的站点中,您可以开始在MDX文件中编写数学表达式。在MDX中使用LaTeX就像将您的表达式包裹在$
或$$
中一样简单。
示例
例如以下Markdown代码:
The **Pythagorean equation**: $a=\sqrt{b^2 + c^2}$.
将会渲染成:
The Pythagorean equation: .
您仍然可以在与您的LaTeX表达式相同的行中使用Markdown和MDX语法。
如果您想要在内容中显示$
而不是将其渲染为等式, 您可以使用反斜杠(\
)进行转义。例如 \$e = mc^2\$
将被渲染为 。
内置组件
Callout 提示组件
默认信息
Space Invaders is a 1978 shoot 'em up arcade game developed by Tomohiro Nishikado.
import { Callout } from 'nextra/components'
<Callout emoji="👾">
**Space Invaders** is a 1978 shoot 'em up arcade game developed by Tomohiro
Nishikado.
</Callout>
提示信息
Today is Friday.
import { Callout } from 'nextra/components'
<Callout type="info" emoji="ℹ️">
Today is Friday.
</Callout>
警告信息
This API will be deprecated soon.
import { Callout } from 'nextra/components'
<Callout type="warning" emoji="⚠️">
This API will be deprecated soon.
</Callout>
错误信息
This is a dangerous feature that can cause everything to explode.
import { Callout } from 'nextra/components'
<Callout type="error" emoji="️🚫">
This is a dangerous feature that can cause everything to explode.
</Callout>
Tab选项卡
示例
用法
默认
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>
默认选定的索引
你可以使用 defaultIndex
属性来设置默认的选项卡索引:
import { Tabs } from 'nextra/components'
<Tabs items={['pnpm', 'npm', 'yarn']} defaultIndex="1">
...
</Tabs>
这样你就将 npm
设置为默认选项卡:
Cards卡片组件 ??
Steps 步骤组件
一个内置组件,将编号列表转换为步骤的视觉表示。
示例
这是第一步
This is the first step description.
这是第二步
This is the second step description.
这是第三步
This is the third step description.
用法
使用 Steps
组件将一组 markdown h3 标题包裹起来,将它们转换为可视化的步骤。
import { Steps } from 'nextra/components'
<Steps>
### 这是第一步
This is the first step description.
### 这是第二步
This is the second step description.
### 这是第三步
This is the third step description.
</Steps>
File Tree 文件树组件
示例
- _meta.json
- contact.md
- index.mdx
用法
import { FileTree } from 'nextra/components'
<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>