← BACK TO ARCHIVE
Guide Markdown Components MDX

Markdown Style Guide & Components

05.22.2024 • ADUCG RESEARCH

欢迎阅读 ADUCG Research 风格指南。本文档展示了在文章中可用的标准 Markdown 语法以及受 Starlight 启发的自定义 MDX 组件。

Standard Markdown

Headings

支持从 H1 到 H6 的标准 Markdown 标题。

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

Text Formatting

基本的文本格式包括粗体、斜体、删除线和行内代码。

粗体文本 (Bold text) 用于突出重要信息。 斜体文本 (Italic text) 用于轻微强调术语或概念。 粗斜体 (Bold and italic) 结合了两种风格以达到最大强调效果。 删除线文本 (Strikethrough text) 表示已弃用或过时的信息。 使用 inline code (行内代码) 来标记技术术语或文件路径。

Horizontal Rules

使用水平分隔线来从视觉上分割内容。你可以使用三个或更多的连字符、星号或下划线。

---
***
___

Lists

Unordered List

  • 列表中的第一项
  • 带有 粗体文本 的第二项
  • 带有 斜体文本 的第三项
  • 嵌套项
    • 子项一
    • 子项二
      • 深层嵌套项

Ordered List

  1. 流程的第一步
  2. 带有更多细节的第二步
  3. 包含以下内容的第三步：
    • 一个子步骤
    • 另一个子步骤
  4. 完成流程的最后一步

Task List

  • 已完成的任务
  • 待处理的任务
  • 另一个已完成的任务

Blockquotes

Basic Blockquote

这是一个基本的引用块，用于高亮重要信息或引用外部来源。

> 这是一个基本的引用块，用于高亮重要信息或引用外部来源。

Nested Blockquotes

包含重要信息的主引用块。

用于补充上下文的嵌套引用块。

用于复杂讨论的深层嵌套引用。

> 包含重要信息的主引用块。
>
> > 用于补充上下文的嵌套引用块。
> >
> > > 用于复杂讨论的深层嵌套引用。

Blockquotes with Attribution

预测未来的最好方法就是去创造它。

— Alan Kay

> 预测未来的最好方法就是去创造它。
>
> — Alan Kay

Tables

表格支持对齐语法并可包含格式化内容。

Feature (功能)Status (状态)Description (描述)
Markdown✅完整的 Markdown 支持
Syntax highlighting✅代码块高亮显示
Responsive design✅移动端友好的布局
Custom components✅扩展的功能性
| Feature (功能) | Status (状态) | Description (描述) |
| :--- | :---: | :--- |
| Markdown | ✅ | 完整的 Markdown 支持 |
| Syntax highlighting | ✅ | 代码块高亮显示 |
| Responsive design | ✅ | 移动端友好的布局 |
| Custom components | ✅ | 扩展的功能性 |

Code Blocks

Code blocks support syntax highlighting, titles, and line highlighting.

Basic Syntax with Title

You can add a file title by appending title="filename.ext" to the code block info string.

console.log('Hello, World!');

```js title="greeting.js"
console.log('Hello, World!');
```

Line Highlighting

Highlight specific lines using {line_number} syntax. Ranges are supported (e.g., {1-3, 5}).

export default function App() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

```tsx {2-3} title="App.tsx"
export default function App() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}
```

Text Wrapping

Long lines of code will automatically wrap to the next line to prevent horizontal scrolling.

npx create-astro@latest --template starlight --install --git --typescript --skip-houston --yes

Custom Components

Asides (Admonitions)

使用 <Aside> 来高亮重要信息。支持的类型包括 note (默认), tip, caution, 和 danger。

Note

这是一个默认的提示 (note)。它适用于需要突出的常规信息。

<Aside>
  这是一个默认的提示 (note)。它适用于需要突出的常规信息。
</Aside>
Tip

Pro Tip: 你可以在 aside 内部使用 Markdown 格式，例如 斜体 或 代码。

<Aside type="tip">
  **Pro Tip:** 你可以在 aside 内部使用 Markdown 格式，例如 *斜体* 或 `代码`。
</Aside>
Caution

请小心！这用于警告用户潜在的陷阱或边缘情况。

<Aside type="caution">
  请小心！这用于警告用户潜在的陷阱或边缘情况。
</Aside>
Danger

危险区域 (Danger Zone): 可能导致数据丢失或系统故障的严重警告。

<Aside type="danger">
  **危险区域 (Danger Zone):** 可能导致数据丢失或系统故障的严重警告。
</Aside>

Steps

使用 <Steps> 可视化顺序流程。该组件会自动将步骤开头的粗体文本解析为标题。

Basic Steps

  1. 初始化项目 - 运行 npm init 创建一个新的 package.json 文件。

  2. 安装依赖 - 使用 npm install 添加必要的包。

  3. 构建与部署 - 运行构建脚本并部署你的应用程序。

<Steps>

1. **初始化项目** - 运行 `npm init` 创建一个新的 `package.json` 文件。

2. **安装依赖** - 使用 `npm install` 添加必要的包。

3. **构建与部署** - 运行构建脚本并部署你的应用程序。

</Steps>

Tight List (紧凑列表)

条目之间不空行的紧凑写法同样支持，渲染效果与宽松列表完全一致（标题纯黑、描述正文灰）。描述紧跟粗体标题时，可用 -、：、（ 等任意分隔方式：

  1. v001：Clay（全灰，先看造型与比例）
  2. v002：Primary materials（先把主要材质区分清楚，保证数值合理）
  3. v003：Secondary breakup（脏污/磨损/微变化，但仍在可控范围内）
  4. Final：Publish & lock（可复现、可回滚）
<Steps>

1. **v001：Clay**（全灰，先看造型与比例）
2. **v002：Primary materials**（先把主要材质区分清楚，保证数值合理）
3. **v003：Secondary breakup**（脏污/磨损/微变化，但仍在可控范围内）
4. **Final：Publish & lock**（可复现、可回滚）

</Steps>

Complex Steps with Mixed Content

步骤中可以包含代码块、表格和其他元素。

  1. 项目设置 - 首先设置你的开发环境。

    在继续之前，请确保你已安装 Node.js 18 或更高版本。

  2. 配置 - 使用必要的设置配置你的项目。

    SettingValueDescription
    titlestring站点标题
    descriptionstring站点描述

  3. 测试 - 测试你的配置以确保一切正常工作。

    npm run test

<Steps>

1. **项目设置** - 首先设置你的开发环境。

   在继续之前，请确保你已安装 Node.js 18 或更高版本。

2. **配置** - 使用必要的设置配置你的项目。

   | Setting | Value | Description |
   |---------|-------|-------------|
   | `title` | `string` | 站点标题 |
   | `description` | `string` | 站点描述 |

3. **测试** - 测试你的配置以确保一切正常工作。

   ```bash
   npm run test
   ```

</Steps>

Tabs

Tabs (标签页) 将内容组织成可切换的视图。

Basic Tabs

此标签页提供主题的概览。

此标签页包含详细信息和示例。

<Tabs>
  <TabItem label="概览">
    此标签页提供主题的概览。
  </TabItem>
  <TabItem label="详情">
    此标签页包含详细信息和示例。
  </TabItem>
</Tabs>

Tabs with Icons and Code

npm install @astrojs/starlight

pnpm add @astrojs/starlight

yarn add @astrojs/starlight

<Tabs>
  <TabItem label="npm" icon="seti:npm">
    ```bash
    npm install @astrojs/starlight
    ```
  </TabItem>
  <TabItem label="pnpm" icon="pnpm">
    ```bash
    pnpm add @astrojs/starlight
    ```
  </TabItem>
  <TabItem label="yarn" icon="seti:yarn">
    ```bash
    yarn add @astrojs/starlight
    ```
  </TabItem>
</Tabs>

File Tree

显示带有语法高亮和注释的目录结构。

  • .github/
    • workflows/
      • deploy.yml
  • src/
    • components/
      • Header.astro
    • content/
      • config.ts
    • pages/
      • index.astro
  • astro.config.mjs
  • package.json
 
<FileTree>

- .github/
  - workflows/
    - deploy.yml
- src/
  - components/
    - **Header.astro**
  - content/
    - config.ts
  - pages/
    - index.astro
- astro.config.mjs
- package.json

</FileTree>

Cards & Link Cards

Feature Cards

star 特性一

此卡片展示了第一个特性，带有图标和描述。

moon 特性二

此卡片展示了带有不同图标的第二个特性。

<CardGrid>
  <Card title="特性一" icon="star">
    此卡片展示了第一个特性，带有图标和描述。
  </Card>
  <Card title="特性二" icon="moon">
    此卡片展示了带有不同图标的第二个特性。
  </Card>
</CardGrid>

链接卡片 (Link cards) 是用于导航的可点击区域。

文档

浏览我们全面的文档

示例

查看实用示例和用例 

<CardGrid>
  <LinkCard title="文档" href="/docs" description="浏览我们全面的文档" />
  <LinkCard title="示例" href="/examples" description="查看实用示例和用例" />
</CardGrid>

Details (Collapsible)

使用 <Details> 将复杂或可选的内容隐藏在可切换的摘要下。

Basic Usage

点击显示隐藏内容

此内容默认隐藏。这对于 FAQ、长代码块或可能使主视图混乱的可选详细信息非常有用。

<Details summary="点击显示隐藏内容">
  此内容默认隐藏。这对于 FAQ、长代码块或可能使主视图混乱的可选详细信息非常有用。
</Details>

Nested Details

主主题

这是顶级内容。

子主题

这是主主题内的嵌套内容。

<Details summary="主主题">
  这是顶级内容。
  
  <Details summary="子主题">
    这是主主题内的嵌套内容。
  </Details>
</Details>

Complex Content

配置选项

以下是可用的配置标志：

FlagTypeDefault
verbosebooleanfalse
timeoutnumber3000
{
  "verbose": true,
  "timeout": 5000
}

<Details summary="配置选项">
  以下是可用的配置标志：
  
  | Flag | Type | Default |
  | :--- | :--- | :--- |
  | `verbose` | `boolean` | `false` |
  | `timeout` | `number` | `3000` |
  
  ```json
  {
    "verbose": true,
    "timeout": 5000
  }
  ```
</Details>

带图注的插图必须使用 <Lightbox> 组件：图片可点击放大浏览，图注显示在图片下方居中、与正文样式区分。不要写裸的 ![image](url) 再在下面跟一行正文图注。

单张图片（图注写在图片的 caption 里）：

图 1：单张图片的图注效果，居中显示在图片下方。
<Lightbox
  sourceName="styleguide_lightbox_single"
  images={[
    { src: 'https://图片地址.jpg', alt: '简短描述', caption: '图 1：完整的图注文字。' },
  ]}
/>

多张图片一组（整组图注放组件的 caption 属性，每张图带 (a)(b)(c) 子标签）：

1 / 3
图 2：整组图片的统一说明文字，点击任意一张可左右翻页浏览。
<Lightbox
  sourceName="styleguide_lightbox_group"
  caption="图 2：整组图片的完整说明文字。"
  images={[
    { src: 'https://图1.jpg', alt: '子图 a 描述', caption: '(a) 子图 a 的说明' },
    { src: 'https://图2.jpg', alt: '子图 b 描述', caption: '(b) 子图 b 的说明' },
  ]}
/>

注意事项：

  • sourceName 在同一篇文章内必须唯一，建议用 文章简称_figN 格式。
  • 没有图注语义的普通配图仍可用标准 Markdown ![alt](url)，不必强行套组件。
  • 批量转换旧文可用 python scripts/convert-images-to-lightbox.py <文件>，详见 README 第 4 节。

Video (视频灯箱)

正文中的视频必须使用 <Video> 组件，样式与 Lightbox 统一：圆角深色舞台，说明文字居中显示在视频下方。不要写裸的 <video controls ...></video> 标签。

视频说明文字居中显示在视频下方，样式与图片图注一致。 
<Video src="https://视频地址.mp4" caption="视频说明文字（可选）。" />

注意事项：

  • caption 可选；没有说明文字的视频写 <Video src="..." /> 即可。
  • 原文章视频下方整行粗体的说明属于图注，应收进 caption；“粗体起头、后接正文”的段落是正文，不要收。
  • 一组连续视频共用一条说明时，说明收进该组最后一个视频的 caption。
  • 批量转换旧文可用 python scripts/convert-videos-to-videobox.py，之后务必再跑 python scripts/repair-video-glued-text.py 并 npm run build 验证，详见 README 第 5 节。
End of Article