跳到主要内容

Markdown 语法指南

· 阅读需 10 分钟
Jiajie Wu
Jiajie Wu
一名崭新水手

Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档，然后转换成有效的 HTML 文档。本文将系统地总结 Markdown 的各种语法用法，帮助你更好地掌握这个强大的文档编写工具。

基础语法​

标题和目录（TOC）​

1. Markdown 标题​

Markdown 支持使用 # 符号创建不同级别的标题：

## 二级标题
### 三级标题
#### 四级标题

扩展语法​

标题 ID​

每个标题都会自动生成一个 ID，用于链接跳转。你可以：

自动生成的 ID​

### 你好世界
<!-- 自动生成 ID: "你好世界" -->

使用方法：

[链接到基础语法标题](#基础语法)

链接到基础语法标题

自定义 ID​

## 扩展语法 \{#extension-syntax}
<!-- 使用自定义 ID: "extension-syntax" -->

使用方法：

[链接到扩展语法标题](#extension-syntax)

链接到扩展语法标题

代码块增强​

Docusaurus 为代码块提供了强大的增强功能。

1. 代码标题​

可以为代码块添加标题：

```jsx title="/src/components/HelloWorld.js"
function HelloWorld(props) {
  return <h1>Hello, {props.name}</h1>;
}
```
/src/components/HelloWorld.js
function HelloWorld(props) {
  return <h1>Hello, {props.name}</h1>;
}

2. 语法高亮​

** 基本用法 ** 代码块会自动根据语言进行语法高亮：

```js
console.log('自动语法高亮');
```
console.log('自动语法高亮');

3. 行高亮​

可以使用特殊注释来高亮代码行：

```js
function highlightDemo() {
  // highlight-next-line
  const highlighted = 'This line is highlighted';
  // highlight-start
  const multipleLines = [
    'These',
    'lines',
    'are',
    'highlighted',
  ];
  // highlight-end
}
```
function highlightDemo() {
  const highlighted = 'This line is highlighted';
  const multipleLines = [
    'These',
    'lines',
    'are',
    'highlighted',
  ];
}

4. 多语言代码块​

以下是一个简单的多语言代码示例：


<Tabs>
<TabItem value="js" label="JavaScript">

```js
function greet() {
  console.log('Hello!');
}
```

</TabItem>
<TabItem value="py" label="Python">

```python
def greet():
    print("Hello!")
```

</TabItem>
</Tabs>
function greet() {
  console.log('Hello!');
}

5. 实时代码编辑演示​

这个页面展示了 Docusaurus 的实时代码编辑功能。

简单的 React 组件

你可以编辑下面的代码，更改会实时显示：


```jsx live
function Clock(props) {
  const [date, setDate] = React.useState(new Date());
  
  React.useEffect(() => {
    const timerID = setInterval(() => tick(), 1000);
    return () => clearInterval(timerID);
  }, []);

  function tick() {
    setDate(new Date());
  }

  return (
    <div>
      <h2>现在时间是：{date.toLocaleTimeString()}</h2>
    </div>
  );
}
```
实时编辑器
function Clock(props) {
  const [date, setDate] = React.useState(new Date());
  
  React.useEffect(() => {
    const timerID = setInterval(() => tick(), 1000);
    return () => clearInterval(timerID);
  }, []);

  function tick() {
    setDate(new Date());
  }

  return (
    <div>
      <h2>现在时间是：{date.toLocaleTimeString()}</h2>
    </div>
  );
}
结果
Loading...

按钮示例

这是一个简单的按钮组件示例：


```jsx live
function ButtonExample() {
  const [count, setCount] = React.useState(0);
  
  return (
    <div>
      <button 
        onClick={() => setCount(count + 1)}
        style={{
          padding: '10px 20px',
          fontSize: '16px',
          backgroundColor: '#25c2a0',
          color: 'white',
          border: 'none',
          borderRadius: '4px',
          cursor: 'pointer'
        }}
      >
        点击次数：{count}
      </button>
    </div>
  );
}
```
实时编辑器
function ButtonExample() {
  const [count, setCount] = React.useState(0);
  
  return (
    <div>
      <button 
        onClick={() => setCount(count + 1)}
        style={{
          padding: '10px 20px',
          fontSize: '16px',
          backgroundColor: '#25c2a0',
          color: 'white',
          border: 'none',
          borderRadius: '4px',
          cursor: 'pointer'
        }}
      >
        点击次数：{count}
      </button>
    </div>
  );
}
结果
Loading...

使用说明

  1. 上面的代码块都是可以编辑的
  2. 更改代码后，右侧的预览会立即更新
  3. 你可以尝试修改文本、样式或添加新的功能
  4. 如果代码有错误，预览区域会显示错误信息

注意事项

  1. 代码高亮：

    • 默认支持常用语言
    • 可以通过配置添加更多语言支持
    • 可以自定义高亮主题

  2. 行高亮：

    • 可以使用注释或行号进行标记
    • 可以自定义高亮颜色

  3. JSX 使用：

    • 在 JSX 中需要使用 <CodeBlock> 组件
    • 支持所有 Markdown 代码块的功能

提示框（Admonitions）​

Docusaurus 提供了一种特殊的提示框语法，通过使用三个冒号和标签类型来创建不同样式的提示框。

1. 基本用法​

:::note

这是一个**普通**提示框，支持 _Markdown_ 语法。

:::

:::tip

这是一个**提示**框，用于展示提示信息。

:::

:::info

这是一个**信息**框，用于展示一般信息。

:::

:::warning

这是一个**警告**框，用于展示警告信息。

:::

:::danger

这是一个**危险**框，用于展示危险警告。

:::
备注

这是一个普通提示框，支持 Markdown 语法。

提示

这是一个提示框，用于展示提示信息。

信息

这是一个信息框，用于展示一般信息。

注意

这是一个警告框，用于展示警告信息。

危险

这是一个危险框，用于展示危险警告。

2. 自定义标题​

可以为提示框添加自定义标题：

:::note[自定义标题]

这里是提示框的内容。标题支持 **Markdown** 语法。

:::
自定义标题

这里是提示框的内容。标题支持 Markdown 语法。

3. 嵌套提示框​

提示框可以嵌套使用，每一层增加一个冒号：

:::::info[父级提示框]

这是父级内容

::::warning[子级提示框]

这是子级内容

:::tip[深层提示框]

这是深层内容

:::

::::

:::::
父级提示框

这是父级内容

子级提示框

这是子级内容

深层提示框

这是深层内容

4. 在 MDX 中使用​

提示框中可以使用 MDX 组件：

:::tip[使用标签页]

<Tabs>
  <TabItem value="apple" label="苹果">这是一个苹果 🍎</TabItem>
  <TabItem value="orange" label="橙子">这是一个橙子 🍊</TabItem>
</Tabs>

:::
使用标签页
这是一个苹果 🍎

注意事项

  1. Prettier 格式化：

    • 在提示框指令周围添加空行以避免格式化问题
    • 错误示例： 
      :::note
      内容
      :::
    • 正确示例： 
      :::note

      内容

      :::

  2. 提示框类型：

    • note: 普通提示
    • tip: 小技巧
    • info: 信息
    • warning: 警告
    • danger: 危险

  3. 自定义功能：

    • 可以通过配置自定义提示框样式
    • 支持自定义图标
    • 可以创建自定义类型的提示框

响应式图片​

在 .mdx文件中，可以使用 <ZoomImage /> 组件来支持响应式图片。

import ZoomImage from '@site/src/components/ZoomImage';

你只需要在正文中使用 <ZoomImage /> 组件，并传入图片的 src 和 alt 属性。

<ZoomImage src="https://s2.loli.net/2025/01/10/Xj47aLr5SGEM3ln.jpg" alt="图　保时捷911E,1973年产" />
图　保时捷911E,1973年产

引用跳转​

在正文需要引用的地方，使用 ^[数字] 来创建一个引用链接。

> 创业点子中你需要的，也是你所需要的，是你朋友真正想要的。一旦你擅长技术，这些想法就不难看到。到处都是粘门。^[1]

创业点子中你需要的，也是你所需要的，是你朋友真正想要的。一旦你擅长技术，这些想法就不难看到。到处都是粘门。[1]

在引文的位置，插入：

^1: 这句话的修辞技巧是"谷歌"指的是不同的东西。我的意思是：一家有很大机会像谷歌一样发展壮大的公司，最终会像拉里和谢尔盖一样，在他们开始创业的时候，可以合理地预期谷歌本身会这样做。但我认为最初的版本更敏捷。

[1] 这句话的修辞技巧是"谷歌"指的是不同的东西。我的意思是：一家有很大机会像谷歌一样发展壮大的公司，最终会像拉里和谢尔盖一样，在他们开始创业的时候，可以合理地预期谷歌本身会这样做。但我认为最初的版本更敏捷。 ↩

评论