文档模板

这是一个完整的文档模板，展示了所有可用的功能。在 Docusaurus 中，.md 和 .mdx 文件功能完全相同，都可以使用 JSX 组件。

核心价值

完整模板 = Markdown 语法 + JSX 组件 + 样式定制 + 最佳实践

Markdown 语法：所有标准 Markdown 功能
JSX 组件：Tabs、Admonition 等组件
数据展示：表格、图表和对比
样式定制：内联样式和 HTML

一、文档元数据（Front Matter）

每个文档开头都应该包含元数据：

yaml

1---
2sidebar_position: 1          # 侧边栏位置
3title: 文档标题              # 页面标题
4description: 文档描述        # SEO 描述
5tags: [标签1, 标签2]         # 文档标签
6keywords: [关键词1, 关键词2] # SEO 关键词
7authors: [Laby]              # 作者
8last_update:                 # 最后更新
9  date: 2026-04-24
10  author: Laby
11---

二、标题层级

一级标题 (H1) - 通常用于文档标题

二级标题 (H2) - 主要章节

三级标题 (H3) - 子章节

四级标题 (H4) - 小节

五级标题 (H5) - 更小的节

六级标题 (H6) - 最小的节

三、文本格式

3.1 基本文本样式

这是普通文本。

这是粗体文本

这是斜体文本

这是粗斜体文本

~~这是删除线文本~~

这是行内代码

这是一个链接

这是一个带标题的链接

3.2 列表

无序列表：

项目 1
项目 2
- 子项目 2.1
- 子项目 2.2
  - 子子项目 2.2.1
项目 3

有序列表：

第一项
第二项
1. 子项 2.1
2. 子项 2.2
第三项

任务列表：

已完成的任务
未完成的任务
另一个未完成的任务

3.3 引用

这是一个引用块

可以包含多行文本

这是嵌套的引用

四、Admonition（提示框）

Docusaurus 提供了多种提示框样式，在 .md 文件中也可以使用：

备注

这是一个注意提示框，用于一般性说明。

提示

这是一个提示框，用于提供有用的建议或技巧。

信息

这是一个信息提示框，用于提供额外的信息。

注意

这是一个警告提示框，用于提醒用户注意潜在问题。

危险

这是一个危险提示框，用于警告严重问题或错误。

警告

这是一个注意提示框，用于提醒用户小心操作。

4.1 自定义标题的提示框

最佳实践

使用自定义标题可以让提示框更加醒目和有针对性。

扩展阅读

可以在提示框中添加 emoji 图标，使其更加生动。

性能陷阱

注意避免在循环中进行大量的 DOM 操作！

常见错误

不要在生产环境中使用 console.log 调试代码。

五、代码块

5.1 基本代码块

javascript

1// JavaScript 代码示例
2function greet(name) {
3  console.log(`Hello, ${name}!`)
4}
5
6greet('World')

python

1# Python 代码示例
2def greet(name):
3    print(f"Hello, {name}!")
4
5greet("World")

typescript

1// TypeScript 代码示例
2interface User {
3  name: string
4  age: number
5}
6
7const user: User = {
8  name: 'Alice',
9  age: 30
10}

5.2 带标题的代码块

src/components/Button.jsx

jsx

1import React from 'react'
2
3export default function Button({ children, onClick }) {
4  return (
5    <button onClick={onClick} className="custom-button">
6      {children}
7    </button>
8  )
9}

5.3 高亮特定行

javascript

1function calculateSum(a, b) {
2  // 这一行会被高亮
3  const sum = a + b
4  // 这些行也会被高亮
5  console.log('Sum:', sum)
6  return sum
7}

5.4 显示行号

javascript

1function fibonacci(n) {
2  if (n <= 1) return n
3  return fibonacci(n - 1) + fibonacci(n - 2)
4}
5
6console.log(fibonacci(10))

六、表格

6.1 基本表格

特性	React	Vue	Angular
学习曲线	中等	简单	陡峭
性能	优秀	优秀	良好
生态系统	丰富	丰富	完整
TypeScript	支持	支持	原生

6.2 对齐方式

左对齐	居中对齐	右对齐
左	中	右
Left	Center	Right
1	2	3

6.3 包含代码和图标的表格

方法	语法	说明	状态
`push()`	`arr.push(item)`	在数组末尾添加元素	推荐
`pop()`	`arr.pop()`	删除并返回数组最后一个元素	推荐
`shift()`	`arr.shift()`	删除并返回数组第一个元素	慎用
`unshift()`	`arr.unshift(item)`	在数组开头添加元素	慎用

6.4 对比表格

特性	方案 A	方案 B	方案 C	推荐
性能	优秀 5星	良好 4星	一般 3星	A
易用性	中等 3星	简单 5星	中等 3星	B
成本	高	中	低	C
可扩展性	支持	支持	不支持	A/B

七、图片和媒体

7.1 基本图片

图片说明：来自《Re:从零开始的异世界生活》的蕾姆

7.2 带链接的图片

点击图片查看炎柱炼狱杏寿郎的另一张图片

7.3 指定图片大小

图片说明：虫柱蝴蝶忍

八、链接和引用

8.1 外部链接

访问 Docusaurus 官网

8.2 内部链接

查看其他文档示例

8.3 锚点链接

跳转到代码块章节

九、分隔线

使用三个或更多的连字符、星号或下划线创建分隔线：

十、常用 Emoji 图标

10.1 状态图标

✅ 成功/完成
❌ 失败/错误
⚠️ 警告
🚫 禁止
ℹ️ 信息
💡 提示/想法
📌 重要

10.2 技术图标

🎯 目标/重点
⚡ 性能/快速
🔥 热门/流行
🚀 发布/启动
🔧 工具/配置
📊 数据/统计
🎨 设计/样式
📚 文档/学习
🔍 搜索/查找
🔄 更新/同步

10.3 评分图标

⭐ 星级评分
🟢 绿色/良好
🟡 黄色/警告
🔴 红色/危险
💰 成本/价格

十一、嵌套内容示例

11.1 提示框中的代码

代码示例

javascript

1// 在提示框中展示代码
2function example() {
3  console.log('这是提示框中的代码')
4}

11.2 提示框中的列表

功能列表

支持 Markdown
支持代码高亮
支持多种主题
支持图片和表格
不支持 JSX 组件（需要 .mdx）

11.3 提示框中的表格

性能对比

操作	时间复杂度	空间复杂度
查找	O(n)	O(1)
插入	O(1)	O(1)
删除	O(n)	O(1)

十二、实际应用示例

12.1 API 文档示例

API 端点

GET /api/users/:id

获取指定用户的详细信息。

参数：

id (string, required): 用户 ID

响应：

json

1{
2  "id": "123",
3  "name": "John Doe",
4  "email": "john@example.com"
5}

12.2 配置文件示例

package.json 配置：

package.json

json

1{
2  "name": "my-app",
3  "version": "1.0.0",
4  "scripts": {
5    "start": "react-scripts start",
6    "build": "react-scripts build",
7    "test": "react-scripts test"
8  },
9  "dependencies": {
10    "react": "^18.0.0",
11    "react-dom": "^18.0.0"
12  }
13}

12.3 步骤说明

安装步骤

安装 Node.js

bash

1# 下载并安装 Node.js
2https://nodejs.org/

创建项目
bash
```
1npx create-react-app my-app
2cd my-app
```
启动开发服务器
bash
```
1npm start
```
构建生产版本
bash
```
1npm run build
```

十三、最佳实践

文档编写建议

结构清晰：

使用合理的标题层级
每个章节有明确的主题
使用分隔线区分不同部分

代码完整：

提供可运行的完整代码
添加必要的注释
使用语法高亮

视觉丰富：

使用表格展示对比数据
使用提示框突出重要信息
使用 Emoji 增加可读性

实例充分：

提供真实的使用场景
包含常见问题的解决方案
展示最佳实践

保持更新：

定期更新文档内容
标注最后更新时间
记录版本变更

十四、Tabs 组件（标签页）

在 Docusaurus 中，.md 文件也可以使用 JSX 组件！只需在文件开头导入即可。

14.1 基本 Tabs 示例

JavaScript
TypeScript
Python

javascript

1// JavaScript 示例
2function greet(name) {
3  console.log(`Hello, ${name}!`)
4}
5
6greet('World')

typescript

1// TypeScript 示例
2function greet(name: string): void {
3  console.log(`Hello, ${name}!`)
4}
5
6greet('World')

python

1# Python 示例
2def greet(name):
3    print(f"Hello, {name}!")
4
5greet("World")

14.2 默认选中的 Tabs

Vue 3
React
Angular

vue

1<template>
2  <div>
3    <h1>{{ message }}</h1>
4    <button @click="updateMessage">Update</button>
5  </div>
6</template>
7
8<script setup>
9import { ref } from 'vue'
10
11const message = ref('Hello Vue 3!')
12
13const updateMessage = () => {
14  message.value = 'Updated!'
15}
16</script>

jsx

1import { useState } from 'react'
2
3function App() {
4  const [message, setMessage] = useState('Hello React!')
5  
6  return (
7    <div>
8      <h1>{message}</h1>
9      <button onClick={() => setMessage('Updated!')}>
10        Update
11      </button>
12    </div>
13  )
14}

typescript

1import { Component } from '@angular/core'
2
3@Component({
4  selector: 'app-root',
5  template: `
6    <div>
7      <h1>{{ message }}</h1>
8      <button (click)="updateMessage()">Update</button>
9    </div>
10  `
11})
12export class AppComponent {
13  message = 'Hello Angular!'
14  
15  updateMessage() {
16    this.message = 'Updated!'
17  }
18}

14.3 Tabs 中嵌套 Admonition

最佳实践
应避免
性能优化

推荐做法

使用 const 和 let 声明变量，避免使用 var。

javascript

1// 推荐
2const PI = 3.14159
3let count = 0
4
5// 不推荐
6var oldStyle = 'avoid this'

常见错误

不要在循环中使用 var 声明变量，会导致作用域问题。

javascript

1// 错误示例
2for (var i = 0; i < 5; i++) {
3  setTimeout(() => console.log(i), 100)
4}
5// 输出：5 5 5 5 5
6
7// 正确示例
8for (let i = 0; i < 5; i++) {
9  setTimeout(() => console.log(i), 100)
10}
11// 输出：0 1 2 3 4

性能提示

使用 Object.freeze() 可以防止对象被修改，提升性能。

javascript

1const config = Object.freeze({
2  API_URL: 'https://api.example.com',
3  TIMEOUT: 5000
4})
5
6// 尝试修改会失败（严格模式下会报错）
7config.API_URL = 'https://other.com' // 无效

14.4 复杂嵌套：Tabs → Admonition → Code → Table

框架对比
角色展示
鬼灭之刃·柱

主流前端框架对比

下面是 React、Vue 和 Angular 的详细对比：

特性	React	Vue	Angular
学习曲线	中等	简单	陡峭
性能	5星	5星	4星
生态系统	非常丰富	丰富	完整但封闭
TypeScript	支持	支持	原生
包体积	42KB	34KB	167KB

代码示例：

javascript

1// React 组件
2function Counter() {
3  const [count, setCount] = useState(0)
4  return <button onClick={() => setCount(count + 1)}>{count}</button>
5}
6
7// Vue 组件
8const Counter = {
9  data: () => ({ count: 0 }),
10  template: '<button @click="count++">{{ count }}</button>'
11}
12
13// Angular 组件
14@Component({
15  template: '<button (click)="increment()">{{ count }}</button>'
16})
17class Counter {
18  count = 0
19  increment() { this.count++ }
20}

Re:从零开始的异世界生活

主要角色：

蕾姆

温柔体贴的鬼族女仆

拉姆

毒舌傲娇的姐姐

爱蜜莉雅

银发半精灵女主角

角色特点对比：

角色	性格	能力	人气
蕾姆	温柔、忠诚	鬼化、流星锤	5星
拉姆	毒舌、傲娇	风魔法	4星
爱蜜莉雅	善良、坚强	冰魔法	5星

鬼杀队·九柱

炎柱 - 炼狱杏寿郎

1"心を燃やせ！"（让心燃烧起来！）

特点：

呼吸法：炎之呼吸
性格：热血、正义
实力：上弦之参级别
名场面：无限列车篇

虫柱 - 蝴蝶忍

1"あら、あら"（哎呀，哎呀）

特点：

呼吸法：虫之呼吸
性格：温柔、腹黑
特技：毒药专家
名场面：与童磨的战斗

水柱 - 富冈义勇

1"俺は嫌われていない"（我没有被讨厌）

特点：

呼吸法：水之呼吸
性格：寡言、冷静
实力：最强柱之一
名场面：与炭治郎的初遇

十五、高级嵌套示例

15.1 三层嵌套：Tabs → Admonition → Tabs

前端开发
后端开发
数据库

前端技术栈

HTML
CSS
JavaScript

html

1<!DOCTYPE html>
2<html lang="zh-CN">
3<head>
4  <meta charset="UTF-8">
5  <title>我的网页</title>
6</head>
7<body>
8  <h1>Hello World</h1>
9</body>
10</html>

css

1/* 现代 CSS 布局 */
2.container {
3  display: grid;
4  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
5  gap: 20px;
6  padding: 20px;
7}
8
9.card {
10  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
11  border-radius: 12px;
12  padding: 24px;
13  color: white;
14  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.2);
15  transition: transform 0.3s ease;
16}
17
18.card:hover {
19  transform: translateY(-5px);
20}

javascript

1// 现代 JavaScript 特性
2const fetchData = async (url) => {
3  try {
4    const response = await fetch(url)
5    const data = await response.json()
6    return data
7  } catch (error) {
8    console.error('Error:', error)
9    throw error
10  }
11}
12
13// 使用
14const users = await fetchData('/api/users')
15console.log(users)

后端技术栈

Node.js
Python
Java

javascript

1// Express.js 服务器
2const express = require('express')
3const app = express()
4
5app.use(express.json())
6
7app.get('/api/users', async (req, res) => {
8  const users = await db.users.findAll()
9  res.json(users)
10})
11
12app.post('/api/users', async (req, res) => {
13  const user = await db.users.create(req.body)
14  res.status(201).json(user)
15})
16
17app.listen(3000, () => {
18  console.log('Server running on port 3000')
19})

python

1# FastAPI 服务器
2from fastapi import FastAPI
3from pydantic import BaseModel
4
5app = FastAPI()
6
7class User(BaseModel):
8    name: str
9    email: str
10
11@app.get("/api/users")
12async def get_users():
13    users = await db.users.find_all()
14    return users
15
16@app.post("/api/users")
17async def create_user(user: User):
18    new_user = await db.users.create(user)
19    return new_user

java

1// Spring Boot 控制器
2@RestController
3@RequestMapping("/api/users")
4public class UserController {
5    
6    @Autowired
7    private UserService userService;
8    
9    @GetMapping
10    public List<User> getUsers() {
11        return userService.findAll();
12    }
13    
14    @PostMapping
15    public User createUser(@RequestBody User user) {
16        return userService.create(user);
17    }
18}

数据库操作

SQL
MongoDB
Redis

sql

1-- 创建用户表
2CREATE TABLE users (
3  id SERIAL PRIMARY KEY,
4  name VARCHAR(100) NOT NULL,
5  email VARCHAR(255) UNIQUE NOT NULL,
6  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
7);
8
9-- 查询用户
10SELECT * FROM users WHERE email LIKE '%@example.com';
11
12-- 更新用户
13UPDATE users SET name = 'New Name' WHERE id = 1;
14
15-- 删除用户
16DELETE FROM users WHERE id = 1;

javascript

1// MongoDB 操作
2const { MongoClient } = require('mongodb')
3
4// 连接数据库
5const client = new MongoClient('mongodb://localhost:27017')
6await client.connect()
7const db = client.db('myapp')
8
9// 插入文档
10await db.collection('users').insertOne({
11  name: 'John Doe',
12  email: 'john@example.com',
13  createdAt: new Date()
14})
15
16// 查询文档
17const users = await db.collection('users').find({
18  email: { $regex: /@example\.com$/ }
19}).toArray()
20
21// 更新文档
22await db.collection('users').updateOne(
23  { _id: userId },
24  { $set: { name: 'New Name' } }
25)

javascript

1// Redis 操作
2const redis = require('redis')
3const client = redis.createClient()
4
5await client.connect()
6
7// 字符串操作
8await client.set('user:1:name', 'John Doe')
9const name = await client.get('user:1:name')
10
11// 哈希操作
12await client.hSet('user:1', {
13  name: 'John Doe',
14  email: 'john@example.com'
15})
16
17// 列表操作
18await client.lPush('tasks', 'Task 1')
19await client.lPush('tasks', 'Task 2')
20
21// 设置过期时间
22await client.expire('user:1:session', 3600)

十六、快速复制模板

下面是一个简洁的文档模板，可以直接复制使用：

markdown

1---
2sidebar_position: 1
3title: 文档标题
4description: 文档描述
5tags: [标签]
6---
7
8# 文档标题
9
10文档简介...
11
12:::tip[核心价值]
13- 要点 1
14- 要点 2
15- 要点 3
16:::
17
18---
19
20## 章节标题
21
22### 小节标题
23
24内容...
25
26代码示例：
27
28\`\`\`javascript
29// 代码
30\`\`\`
31
32---
33
34## 总结
35
36总结内容...

十七、折叠面板（Details）

折叠面板用于隐藏大量内容，让用户按需展开查看。

17.1 基础折叠面板

点击展开查看详细内容

这是折叠面板的内容。可以包含任何 Markdown 元素：

列表项 1
列表项 2
列表项 3

javascript

1console.log('折叠面板中的代码');

17.2 默认展开的折叠面板

默认展开的面板

使用 open 属性可以让折叠面板默认处于展开状态。

这对于重要内容很有用。

17.3 嵌套折叠面板

外层折叠面板

外层内容...

内层折叠面板

内层内容可以进一步折叠。

17.4 折叠面板中的复杂内容

API 文档示例

请求参数

参数名	类型	必填	说明
userId	string	是	用户ID
token	string	是	访问令牌

响应示例

json

1{
2  "code": 200,
3  "message": "success",
4  "data": {
5    "userId": "12345",
6    "username": "developer"
7  }
8}

错误码

400: 请求参数错误
401: 未授权
500: 服务器错误

17.5 折叠面板最佳实践

使用建议

用于隐藏可选的详细信息
用于长代码示例或日志输出
用于 FAQ 问答列表
用于可选的高级配置说明
避免在折叠面板中放置关键信息

十八、卡片组件

18.1 基础卡片

基础卡片

这是一个基础卡片组件，使用 DevManga 风格的粗边框、阴影和倾斜效果。

卡片内容可以包含任何 Markdown 元素：文本、列表、代码等。

17.2 主题色卡片

Water Style (Primary)

使用主色调（蓝色）的卡片，适合展示主要功能或重点内容。

组件化开发
虚拟 DOM
丰富的生态系统

Success Style

使用成功色（绿色）的卡片，适合展示成功状态或正面信息。

操作成功
测试通过
部署完成

17.3 警告和危险卡片

Thunder Style (Warning)

使用警告色（黄色）的卡片，提醒用户注意潜在问题。

注意事项：

请仔细阅读文档
确保配置正确
建议先在测试环境验证

Flame Style (Danger)

使用危险色（红色）的卡片，警告严重问题或错误。

严重警告：

此操作不可逆
可能导致数据丢失
请务必备份数据

17.4 Tabs + 卡片组合

前端框架
后端框架

React

特点：

组件化开发
虚拟 DOM
丰富的生态系统

Vue

特点：

渐进式框架
双向数据绑定
简单易学

Angular

特点：

完整的框架
TypeScript 原生支持
企业级解决方案

最后更新时间： 2024-12-28

文件格式： Markdown (.md) with JSX support

标签： #文档模板 #Markdown #MDX #JSX组件 #卡片组件

forum

评论区 / Comments

share分享文章 / Share

一、文档元数据（Front Matter）​

二、标题层级​

一级标题 (H1) - 通常用于文档标题

二级标题 (H2) - 主要章节​

三级标题 (H3) - 子章节​

四级标题 (H4) - 小节​

五级标题 (H5) - 更小的节​

六级标题 (H6) - 最小的节​

三、文本格式​

3.1 基本文本样式​

3.2 列表​

3.3 引用​

四、Admonition（提示框）​

4.1 自定义标题的提示框​

五、代码块​

5.1 基本代码块​

5.2 带标题的代码块​

5.3 高亮特定行​

5.4 显示行号​

六、表格​

6.1 基本表格​

6.2 对齐方式​

6.3 包含代码和图标的表格​

6.4 对比表格​

七、图片和媒体​

7.1 基本图片​

7.2 带链接的图片​

7.3 指定图片大小​

八、链接和引用​

8.1 外部链接​

8.2 内部链接​

8.3 锚点链接​

九、分隔线​

十、常用 Emoji 图标​

10.1 状态图标​

10.2 技术图标​

10.3 评分图标​

十一、嵌套内容示例​

11.1 提示框中的代码​

11.2 提示框中的列表​

11.3 提示框中的表格​

十二、实际应用示例​

12.1 API 文档示例​

12.2 配置文件示例​

12.3 步骤说明​

十三、最佳实践​

十四、Tabs 组件（标签页）​

14.1 基本 Tabs 示例​

14.2 默认选中的 Tabs​

14.3 Tabs 中嵌套 Admonition​

14.4 复杂嵌套：Tabs → Admonition → Code → Table​

十五、高级嵌套示例​

15.1 三层嵌套：Tabs → Admonition → Tabs​

十六、快速复制模板​

十七、折叠面板（Details）​

17.1 基础折叠面板​

17.2 默认展开的折叠面板​

17.3 嵌套折叠面板​

17.4 折叠面板中的复杂内容​

请求参数​

响应示例​

错误码​

17.5 折叠面板最佳实践​

十八、卡片组件​

18.1 基础卡片​

基础卡片​

17.2 主题色卡片​

Water Style (Primary)​

Success Style​

17.3 警告和危险卡片​

Thunder Style (Warning)​

Flame Style (Danger)​

17.4 Tabs + 卡片组合​

React​

Vue​

Angular​

Node.js + Express​

Python + FastAPI​

Java + Spring Boot​

评论区 / Comments

一、文档元数据（Front Matter）

二、标题层级

二级标题 (H2) - 主要章节

三级标题 (H3) - 子章节

四级标题 (H4) - 小节

五级标题 (H5) - 更小的节

六级标题 (H6) - 最小的节

三、文本格式

3.1 基本文本样式

3.2 列表

3.3 引用

四、Admonition（提示框）

4.1 自定义标题的提示框

五、代码块

5.1 基本代码块

5.2 带标题的代码块

5.3 高亮特定行

5.4 显示行号

六、表格

6.1 基本表格

6.2 对齐方式

6.3 包含代码和图标的表格

6.4 对比表格

七、图片和媒体

7.1 基本图片

7.2 带链接的图片

7.3 指定图片大小

八、链接和引用

8.1 外部链接

8.2 内部链接

8.3 锚点链接

九、分隔线

十、常用 Emoji 图标

10.1 状态图标

10.2 技术图标

10.3 评分图标

十一、嵌套内容示例

11.1 提示框中的代码

11.2 提示框中的列表

11.3 提示框中的表格

十二、实际应用示例

12.1 API 文档示例

12.2 配置文件示例

12.3 步骤说明

十三、最佳实践

十四、Tabs 组件（标签页）

14.1 基本 Tabs 示例

14.2 默认选中的 Tabs

14.3 Tabs 中嵌套 Admonition

14.4 复杂嵌套：Tabs → Admonition → Code → Table

十五、高级嵌套示例

15.1 三层嵌套：Tabs → Admonition → Tabs

十六、快速复制模板

十七、折叠面板（Details）

17.1 基础折叠面板

17.2 默认展开的折叠面板

17.3 嵌套折叠面板

17.4 折叠面板中的复杂内容

请求参数

响应示例

错误码

17.5 折叠面板最佳实践

十八、卡片组件

18.1 基础卡片

基础卡片

17.2 主题色卡片

Water Style (Primary)

Success Style

17.3 警告和危险卡片

Thunder Style (Warning)

Flame Style (Danger)

17.4 Tabs + 卡片组合

React

Vue

Angular

Node.js + Express

Python + FastAPI

Java + Spring Boot