代码块和容器

Rspress 提供强大的代码块功能和自定义容器,用于创建丰富、信息丰富的文档。本章探讨如何有效地使用这些功能。

代码块

基本语法高亮

使用语言标识符启用语法高亮:

markdown

```javascript
function hello() {
  console.log('Hello, World!');
}
```

```python
def hello():
    print("Hello, World!")
```

```typescript
function greet(name: string): void {
  console.log(`Hello, ${name}!`);
}
```

渲染结果:

javascript

function hello() {
  console.log('Hello, World!');
}

支持的语言

Rspress 支持广泛的编程语言:

javascript, typescript, jsx, tsx, python, java, c, cpp, csharp,
go, rust, php, ruby, swift, kotlin, dart, sql, bash, shell,
html, css, scss, sass, less, json, yaml, xml, markdown, diff

行号

启用行号

默认情况下启用行号。使用 showLineNumbers 选项控制:

markdown

```javascript showLineNumbers
function calculateSum(a, b) {
  return a + b;
}

const result = calculateSum(5, 10);
console.log(result);
```

自定义起始行号

从特定行号开始:

markdown

```javascript showLineNumbers=10
function processData(data) {
  // 这将从行号 10 开始
  return data.map(item => item * 2);
}
```

禁用行号

对于简单的代码片段:

markdown

```bash {showLineNumbers=false}
npm install rspress
```

高亮行

单行高亮

高亮特定行以引起注意:

markdown

```javascript {2}
function greet(name) {
  console.log(`Hello, ${name}!`); // 这行被高亮
  return name;
}
```

多行高亮

高亮多个单独的行:

markdown

```javascript {1,3,5}
import React from 'react';

function Component() {
  const [count, setCount] = useState(0);
  return <div>{count}</div>;
}
```

行范围高亮

高亮行范围:

markdown

```javascript {4-7}
function processArray(arr) {
  const result = [];

  for (let i = 0; i < arr.length; i++) {
    result.push(arr[i] * 2);
  }

  return result;
}
```

组合高亮

组合单行和范围:

markdown

```javascript {1,3-5,8}
import React, { useState, useEffect } from 'react';

function UserProfile({ userId }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchUser(userId).then(setUser);
  }, [userId]);

  return <div>{user?.name}</div>;
}
```

代码标题

添加文件名

显示代码块的文件名:

markdown

```typescript title="config.ts"
export interface Config {
  title: string;
  description: string;
}
```

带路径的标题

包含完整文件路径:

markdown

```javascript title="src/components/Button/Button.tsx"
import React from 'react';

export function Button({ children, onClick }) {
  return <button onClick={onClick}>{children}</button>;
}
```

差异高亮

添加和删除行

显示代码变更:

markdown

```javascript
function greet(name) {
- console.log('Hello ' + name);
+ console.log(`Hello, ${name}!`);
}
```

复杂差异

显示多个变更:

markdown

```typescript
interface User {
  name: string;
- age: number;
+ birthDate: Date;
  email: string;
+ isActive: boolean;
}

function formatUser(user: User) {
- return `${user.name} (${user.age})`;
+ const age = calculateAge(user.birthDate);
+ return `${user.name} (${age})${user.isActive ? ' ✓' : ''}`;
}
```

代码组

创建标签页

将相关代码组织在标签页中:

markdown

:::code-group

```bash [npm]
npm install rspress
```

```bash [yarn]
yarn add rspress
```

```bash [pnpm]
pnpm add rspress
```

:::

不同语言的示例

在标签页中显示多种语言:

markdown

:::code-group

```javascript [JavaScript]
function hello() {
  console.log('Hello!');
}
```

```typescript [TypeScript]
function hello(): void {
  console.log('Hello!');
}
```

```python [Python]
def hello():
    print("Hello!")
```

:::

配置示例

展示不同的配置选项:

markdown

:::code-group

```json [package.json]
{
  "name": "my-app",
  "scripts": {
    "dev": "rspress dev"
  }
}
```

```typescript [rspress.config.ts]
import { defineConfig } from 'rspress/config';

export default defineConfig({
  title: 'My Docs'
});
```

```yaml [.github/workflows/deploy.yml]
name: Deploy
on:
  push:
    branches: [main]
```

:::

自定义容器

提示容器

为用户提供有用的提示:

markdown

::: tip
这是一个有用的提示,可以帮助用户更好地理解内容。
:::

::: tip 自定义标题
您可以自定义提示的标题。
:::

渲染为:

TIP

这是一个有用的提示,可以帮助用户更好地理解内容。

信息容器

提供附加信息:

markdown

::: info
这提供了补充的背景信息。
:::

::: info 版本说明
此功能在版本 1.2.0 中添加。
:::

INFO

这提供了补充的背景信息。

警告容器

警告用户潜在问题:

markdown

::: warning
小心使用此功能,因为它可能会影响性能。
:::

::: warning 弃用通知
此 API 已被弃用,将在下一个主要版本中删除。
:::

WARNING

小心使用此功能,因为它可能会影响性能。

危险容器

突出显示关键警告:

markdown

::: danger
不要在生产中使用此方法!它仅用于测试目的。
:::

::: danger 数据丢失风险
此操作将永久删除所有数据且无法撤消。
:::

DANGER

不要在生产中使用此方法!它仅用于测试目的。

详情容器

创建可折叠的详细信息部分:

markdown

::: details 点击查看详细信息
这是隐藏的内容,只有在点击后才会显示。

您可以在这里包含代码、列表和其他 Markdown:

```javascript
function example() {
  return 'hidden content';
}

:::


## 高级代码块功能

### 专注模式

高亮特定行并淡化其他行:

````markdown
```javascript {2-3} focus
function processData(data) {
  const filtered = data.filter(item => item.active);
  const mapped = filtered.map(item => item.value);
  return mapped;
}


### 带行号的差异

组合行号和差异:

````markdown
```typescript showLineNumbers
interface Config {
  name: string;
- port: number;
+ port: number | string;
  host: string;
+ timeout?: number;
}
```

字高亮

高亮特定字符:

markdown

```javascript /console.log/ /error/
function handleError(error) {
  console.log('An error occurred');
  console.error(error);
}
```

实际示例

API 文档

记录 API 端点:

markdown

### 获取用户

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

**端点:**

```
GET /api/users/:id
```

**请求:**

```bash title="cURL"
curl https://api.example.com/users/123 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**响应:**

```json title="200 OK" {2-3}
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "createdAt": "2024-01-26T10:00:00Z"
}
```

**错误响应:**

```json title="404 Not Found"
{
  "error": "User not found",
  "code": "USER_NOT_FOUND"
}
```

教程步骤

逐步指导:

markdown

## 步骤 1: 安装

:::code-group

```bash [npm]
npm install rspress
```

```bash [yarn]
yarn add rspress
```

:::

## 步骤 2: 初始化

```bash
npx rspress init my-docs
cd my-docs
```

## 步骤 3: 配置

```typescript title="rspress.config.ts" {4-6}
import { defineConfig } from 'rspress/config';

export default defineConfig({
  title: 'My Documentation',
  description: 'A comprehensive guide',
  themeConfig: {
    sidebar: {
      '/guide/': [/* ... */]
    }
  }
});
```

::: tip
根据您的需求自定义配置。
:::

迁移指南

显示代码变更:

markdown

## 从 v1 迁移到 v2

### 配置变更

旧配置格式:

```javascript title="rspress.config.js (v1)"
module.exports = {
  title: 'My Site',
  theme: {
    navbar: [/* ... */]
  }
};
```

新配置格式:

```typescript title="rspress.config.ts (v2)"
import { defineConfig } from 'rspress/config';

export default defineConfig({
  title: 'My Site',
  themeConfig: {
    navbar: [/* ... */]
  }
});
```

### API 变更

```typescript
// 旧方式 (v1)
- import { createPage } from 'rspress';
+ import { definePage } from 'rspress/runtime';

- const page = createPage({ /* ... */ });
+ const page = definePage({ /* ... */ });
```

::: warning 破坏性变更
`createPage` API 已被删除。使用 `definePage` 代替。
:::

配置

全局配置

在 rspress.config.ts 中自定义代码块:

typescript

import { defineConfig } from 'rspress/config';

export default defineConfig({
  markdown: {
    // 配置代码高亮
    highlight: {
      theme: 'github-dark',
      languages: ['javascript', 'typescript', 'bash']
    },

    // 行号配置
    showLineNumbers: true,

    // 默认代码复制按钮
    codeCopy: true
  }
});

主题配置

自定义代码块主题:

typescript

export default defineConfig({
  markdown: {
    highlight: {
      // 使用不同的主题
      theme: {
        light: 'github-light',
        dark: 'github-dark'
      }
    }
  }
});

自定义语言

添加自定义语言支持:

typescript

export default defineConfig({
  markdown: {
    highlight: {
      languages: [
        'javascript',
        'typescript',
        // 添加自定义语言
        {
          id: 'myLang',
          scopeName: 'source.myLang',
          grammar: {/* ... */}
        }
      ]
    }
  }
});

样式定制

CSS 变量

使用 CSS 变量自定义代码块:

css

/* styles/custom.css */
:root {
  --rp-code-bg: #1e1e1e;
  --rp-code-color: #d4d4d4;
  --rp-code-line-number-color: #858585;
  --rp-code-highlight-bg: rgba(255, 255, 255, 0.1);
  --rp-code-title-bg: #2d2d2d;
}

自定义类

添加自定义样式:

css

/* 自定义代码块样式 */
.rspress-code-block {
  border-radius: 8px;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}

/* 自定义行高亮 */
.rspress-code-block .highlighted {
  background: rgba(255, 255, 0, 0.1);
  border-left: 3px solid #ffd700;
}

/* 自定义容器样式 */
.rspress-container.tip {
  border-left: 4px solid #42b983;
}

.rspress-container.warning {
  border-left: 4px solid #ffa500;
}

.rspress-container.danger {
  border-left: 4px solid #ff0000;
}

最佳实践

代码组织

使用有意义的标题

markdown

✅ 好
```typescript title="src/utils/validation.ts"
export function validateEmail(email: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}
```

❌ 不好
```typescript title="file.ts"
function validate(s) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s);
}
```

高亮重要行

markdown

✅ 突出关键部分
```javascript {5-7}
async function fetchUser(id) {
  try {
    const response = await fetch(`/api/users/${id}`);
    const data = await response.json();
    // 这是重要的错误处理
    if (!response.ok) {
      throw new Error(data.message);
    }
    return data;
  } catch (error) {
    console.error(error);
  }
}
```

使用代码组进行选项

markdown

✅ 清晰的选项
:::code-group

```bash [npm]
npm install package
```

```bash [yarn]
yarn add package
```

:::

❌ 分开的块
```bash
npm install package
```

或

```bash
yarn add package
```

容器使用

选择合适的容器类型

markdown

✅ 适当的使用
::: tip
使用快捷键 Ctrl+K 快速搜索。
:::

::: warning
此功能在移动设备上不可用。
:::

::: danger
删除此资源将永久移除所有相关数据。
:::

提供清晰的标题

markdown

✅ 描述性标题
::: warning 性能影响
在大型数据集上使用此方法可能会影响性能。
:::

❌ 通用标题
::: warning
小心这个。
:::

组合内容类型

markdown

::: tip 最佳实践
始终验证用户输入:

```typescript
function validateInput(input: string): boolean {
  return input.length > 0 && input.length < 100;
}

查看验证指南了解更多详情。 :::


## 故障排除

### 常见问题

1. **语法高亮不工作**

```markdown
问题: 代码未高亮显示
解决方案: 检查语言标识符拼写

❌ 错误
```javascrip
// 错字

✅ 正确

javascript

// 正确的语言标识符


2. **行高亮未显示**

````markdown
问题: 高亮行未应用
解决方案: 确保语法正确

❌ 错误
```javascript {1, 2, 3}
// 高亮范围中的空格

✅ 正确

javascript

// 无空格


3. **容器未渲染**

```markdown
问题: 容器显示为纯文本
解决方案: 检查语法和冒号

❌ 错误
:: tip
缺少冒号
::

✅ 正确
::: tip
三个冒号
:::
```

### 调试提示

1. **检查配置**

```typescript
// 在 rspress.config.ts 中启用调试
export default defineConfig({
  markdown: {
    debug: true, // 启用调试日志
  }
});
```

2. **验证语言支持**

```javascript
// 检查可用语言
import { getHighlighter } from 'rspress/runtime';

const highlighter = await getHighlighter();
console.log(highlighter.getLoadedLanguages());
```

3. **测试容器**

```markdown
<!-- 测试每种容器类型 -->
::: tip
测试提示
:::

::: info
测试信息
:::

::: warning
测试警告
:::

::: danger
测试危险
:::
```

---

## 下一步

- 学习[自定义页面](./custom-pages.md)
- 探索[自定义主题](./custom-theme.md)
- 阅读[内置组件](./built-in-components.md)

---

::: tip 最佳实践
- 为所有代码块使用适当的语言标识符
- 高亮重要行以引起注意
- 为文件提供有意义的标题
- 为相关选项使用代码组
- 选择适当的容器类型
:::

::: warning 性能
- 避免在页面上使用过多的代码块
- 考虑长代码片段的代码折叠
- 优化自定义语法高亮器
:::

::: info 资源
- [Shiki 主题](https://github.com/shikijs/shiki/blob/main/docs/themes.md)
- [语言支持](https://github.com/shikijs/shiki/blob/main/docs/languages.md)
- [Rspress Markdown 指南](https://rspress.dev/guide/basic/markdown)
:::

代码块和容器 ​

代码块 ​

基本语法高亮 ​

支持的语言 ​

行号 ​

启用行号 ​

自定义起始行号 ​

禁用行号 ​

高亮行 ​

单行高亮 ​

多行高亮 ​

行范围高亮 ​

组合高亮 ​

代码标题 ​

添加文件名 ​

带路径的标题 ​

差异高亮 ​

添加和删除行 ​

复杂差异 ​

代码组 ​

创建标签页 ​

不同语言的示例 ​

配置示例 ​

自定义容器 ​

提示容器 ​

信息容器 ​

警告容器 ​

危险容器 ​

详情容器 ​

字高亮 ​

实际示例 ​

API 文档 ​

教程步骤 ​

迁移指南 ​

配置 ​

全局配置 ​

主题配置 ​

自定义语言 ​

样式定制 ​

CSS 变量 ​

自定义类 ​

最佳实践 ​

代码组织 ​

容器使用 ​

代码块和容器

代码块

基本语法高亮

支持的语言

行号

启用行号

自定义起始行号

禁用行号

高亮行

单行高亮

多行高亮

行范围高亮

组合高亮

代码标题

添加文件名

带路径的标题

差异高亮

添加和删除行

复杂差异

代码组

创建标签页

不同语言的示例

配置示例

自定义容器

提示容器

信息容器

警告容器

危险容器

详情容器

字高亮

实际示例

API 文档

教程步骤

迁移指南

配置

全局配置

主题配置

自定义语言

样式定制

CSS 变量

自定义类

最佳实践

代码组织

容器使用