Rapide 主题语法完整指南

本文档详细介绍 Rapide 主题的所有语法特性，重点关注代码块和标注（Asides）的处理。

📌 一、标注（Asides）详解

标注（Asides）是用于突出显示特定信息的特殊块，在 Rapide 主题中样式优美，非常适合强调重要内容。

1.1 基本语法

标注使用三个冒号 ::: 包裹，后面跟标注类型：

:::note
这是一个普通提示。
:::

1.2 所有标注类型

Rapide 支持以下 5 种标注类型：

📘 Note（笔记/提示）

用于一般性的提示信息。

语法：

:::note
这是一个普通的提示信息，用于补充说明。
:::

效果：

💡 Tip（技巧/建议）

用于提供有用的技巧或最佳实践。

语法：

:::tip
这是一个技巧提示，建议你这样做会更好！
:::

效果：

⚠️ Caution（警告/注意）

用于提醒用户需要注意的事项。

语法：

:::caution
这是一个警告信息，请特别注意这个操作！
:::

效果：

🚨 Danger（危险）

用于严重警告，表示可能导致严重后果的操作。

语法：

:::danger
这是一个危险警告！此操作可能导致数据丢失或系统崩溃！
:::

效果：

1.3 自定义标注标题

你可以为标注添加自定义标题，使用方括号 [] 语法：

语法：

:::note[💡 重要提示]
使用自定义标题可以让标注更加醒目和个性化。
:::

效果：

更多示例：

1.4 标注中的富文本

标注内部可以使用所有 Markdown 语法：

标注内部支持：

加粗文本
斜体文本
行内代码
链接
列表项

甚至可以包含代码块：

const message = "标注中的代码";
console.log(message);

和公式： $E = mc^2$

💻 二、代码块详解

Rapide 主题对代码块有出色的支持，提供语法高亮、行号、标题等功能。

2.1 基本代码块

使用三个反引号包裹代码，并指定语言：

语法：

```javascript
function hello() {
  console.log("Hello, Rapide!");
}
```

效果：

function hello() {
  console.log("Hello, Rapide!");
}

2.2 支持的编程语言

Rapide 支持几乎所有主流编程语言的语法高亮：

JavaScript / TypeScript

// JavaScript 示例
const greeting = (name) => {
  return `Hello, ${name}!`;
};

console.log(greeting("World"));

// TypeScript 示例
interface User {
  name: string;
  age: number;
}

const user: User = {
  name: "Alice",
  age: 30
};

Python

# Python 示例
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

# 计算前10个斐波那契数
for i in range(10):
    print(f"F({i}) = {fibonacci(i)}")

Java

// Java 示例
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, Rapide!");

        // 创建数组
        int[] numbers = {1, 2, 3, 4, 5};
        for (int num : numbers) {
            System.out.println(num);
        }
    }
}

C / C++

// C 语言示例
#include <stdio.h>

int main() {
    printf("Hello, Rapide!\n");

    // 简单循环
    for (int i = 0; i < 5; i++) {
        printf("%d ", i);
    }

    return 0;
}

// C++ 示例
#include <iostream>
#include <vector>

int main() {
    std::vector<int> numbers = {1, 2, 3, 4, 5};

    for (const auto& num : numbers) {
        std::cout << num << " ";
    }

    return 0;
}

Rust

// Rust 示例
fn main() {
    let numbers = vec![1, 2, 3, 4, 5];

    let sum: i32 = numbers.iter().sum();
    println!("Sum: {}", sum);

    // 使用闭包
    numbers.iter()
        .map(|x| x * 2)
        .for_each(|x| println!("{}", x));
}

Go

// Go 语言示例
package main

import "fmt"

func main() {
    numbers := []int{1, 2, 3, 4, 5}

    sum := 0
    for _, num := range numbers {
        sum += num
    }

    fmt.Printf("Sum: %d\n", sum)
}

HTML / CSS

<!-- HTML 示例 -->
<!DOCTYPE html>
<html lang="zh">
<head>
    <meta charset="UTF-8">
    <title>Rapide 示例</title>
</head>
<body>
    <h1>欢迎使用 Rapide 主题</h1>
    <p>这是一个段落。</p>
</body>
</html>

/* CSS 样式示例 */
body {
    font-family: 'Arial', sans-serif;
    line-height: 1.6;
    max-width: 1200px;
    margin: 0 auto;
    padding: 20px;
}

.container {
    display: flex;
    justify-content: space-between;
    align-items: center;
}

.button {
    background-color: #3498db;
    color: white;
    padding: 10px 20px;
    border: none;
    border-radius: 5px;
    cursor: pointer;
    transition: background-color 0.3s ease;
}

.button:hover {
    background-color: #2980b9;
}

Shell / Bash

#!/bin/bash
# Bash 脚本示例

echo "开始执行脚本..."

# 变量定义
NAME="Rapide"
VERSION="1.0"

echo "主题: $NAME"
echo "版本: $VERSION"

# 条件判断
if [ -f "package.json" ]; then
    echo "找到 package.json 文件"
    npm install
fi

# 循环
for i in {1..5}; do
    echo "第 $i 次循环"
done

SQL

-- SQL 查询示例
SELECT
    users.id,
    users.name,
    users.email,
    COUNT(orders.id) as order_count
FROM users
LEFT JOIN orders ON users.id = orders.user_id
WHERE users.created_at >= '2024-01-01'
GROUP BY users.id, users.name, users.email
HAVING COUNT(orders.id) > 5
ORDER BY order_count DESC
LIMIT 10;

JSON / YAML

{
  "name": "rapide-theme",
  "version": "0.4.0",
  "description": "A beautiful theme for Starlight",
  "keywords": ["astro", "starlight", "theme"],
  "author": "Your Name",
  "license": "MIT",
  "dependencies": {
    "@astrojs/starlight": "^0.34.3",
    "astro": "^5.7.13"
  }
}

# YAML 配置示例
title: My Documentation
theme: rapide

features:
  - code-highlighting
  - dark-mode
  - responsive-design

social:
  - label: GitHub
    icon: github
    href: https://github.com/username/repo
  - label: Twitter
    icon: twitter
    href: https://twitter.com/username

2.3 代码块的高级特性

Rapide 主题的代码块支持强大的 Expressive Code 特性，包括行号、文件名、高亮行、Diff 标记等。

① 自动显示行号

项目已配置自动显示行号，所有代码块都会显示：

// 左侧会自动显示行号
function calculateSum(a, b) {
  return a + b;
}

const result = calculateSum(10, 20);
console.log(`结果是: ${result}`);

② 代码块命名（Editor Frame）

在代码块的第一行以注释形式添加文件名：

语法：

```javascript title="app.js"
const greeting = "Hello, Rapide!";
console.log(greeting);
```

效果：

const greeting = "Hello, Rapide!";
console.log(greeting);

③ 高亮特定行

使用 {行号} 语法高亮特定行：

语法：

```javascript {3,5-7}
function example() {
  const a = 1;
  const b = 2;  // 这行会被高亮
  const c = 3;
  // 这三行
  // 都会
  // 被高亮
  return a + b + c;
}
```

效果：

function example() {
  const a = 1;
  const b = 2;  // 这行会被高亮
  const c = 3;
  // 这三行
  // 都会
  // 被高亮
  return a + b + c;
}

④ Diff 标记（添加/删除）

使用 ins 和 del 标记代码的增删：

语法：

```javascript ins={3} del={2}
function greet(name) {
  return "Hello " + name;  // 删除这行
  return `Hello, ${name}!`;  // 添加这行
}
```

效果：

function greet(name) {
  return "Hello " + name;  // 删除这行
  return `Hello, ${name}!`;  // 添加这行
}

更复杂的 Diff 示例：

const express = require('express');
const port = 3000;  // 旧端口
const app = express();

// 新增：环境变量配置
const port = process.env.PORT || 3000;
const host = process.env.HOST || 'localhost';

app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

⑤ Terminal Frame（终端样式）

添加 Terminal 提示符样式：

npm install starlight-theme-rapide

npm run dev

⑥ 复制、换行、下载功能

代码块右上角自动提供三个功能按钮：

📋 复制按钮 - 一键复制代码到剪贴板
↔️ 换行切换 - 切换代码是否自动换行
⬇️ 下载按钮 - 下载代码为文件（如果有文件名）

这些功能已在配置中启用，无需额外设置！

⑦ 综合示例

结合多种特性：

export interface User {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'user';  // 旧的角色定义
}

// 新的角色系统
type Role = 'admin' | 'user' | 'moderator';
export interface User {
  id: string;
  name: string;
  email: string;
  role: Role;
  permissions: string[];
}

export function checkPermission(user: User, permission: string): boolean {
  return user.permissions.includes(permission);
}

行内代码

使用单个反引号创建行内代码：

语法：

使用 `const` 声明常量，使用 `let` 声明变量。

效果： 使用 const 声明常量，使用 let 声明变量。

2.4 代码块 + 标注组合使用

这是一个强大的组合，可以在标注中展示代码：

安装 Rapide 主题非常简单：

npm install starlight-theme-rapide

然后在 astro.config.mjs 中配置：

import starlightThemeRapide from 'starlight-theme-rapide';

export default defineConfig({
  integrations: [
    starlight({
      plugins: [starlightThemeRapide()],
      title: 'My Docs',
    }),
  ],
});

不要忘记在 frontmatter 后导入组件！

错误示例：

---
title: My Page
---

# 标题
import { Card } from '@astrojs/starlight/components';

正确示例：

---
title: My Page
---

import { Card } from '@astrojs/starlight/components';

# 标题

🎨 三、其他组件

3.1 徽章（Badge）

徽章用于标记状态、版本或重要信息。

基本用法：

<Badge text="新功能" />

效果：

新功能

不同样式：

默认提示成功警告危险

在标题中使用：

## API 文档 <Badge text="v2.0" variant="success" />

效果：

API 文档 v2.0

3.2 卡片（Card）

单个卡片

import { Card } from '@astrojs/starlight/components';

<Card title="卡片标题" icon="rocket">
  这是卡片的内容。
</Card>

效果：

功能介绍

Rapide 主题提供了出色的视觉体验和丰富的组件支持。

卡片网格

import { Card, CardGrid } from '@astrojs/starlight/components';

<CardGrid>
  <Card title="快速" icon="approve-check">
    闪电般的构建速度
  </Card>
  <Card title="美观" icon="star">
    现代化的设计
  </Card>
  <Card title="强大" icon="rocket">
    功能丰富
  </Card>
</CardGrid>

效果：

快速

闪电般的构建速度，优化的性能表现

美观

现代化的设计，优雅的视觉体验

强大

功能丰富，组件齐全

易用

简单配置，快速上手

3.3 选项卡（Tabs）

选项卡适合展示多个选项或不同语言的代码示例。

语法示例：

导入组件并使用：

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="选项1">
    内容1
  </TabItem>
  <TabItem label="选项2">
    内容2
  </TabItem>
</Tabs>

效果：

npm install starlight-theme-rapide

pnpm add starlight-theme-rapide

yarn add starlight-theme-rapide

3.4 步骤组件（Steps）

用于展示操作流程或教程步骤。

语法示例：

import { Steps } from '@astrojs/starlight/components';

<Steps>
  1. 第一步说明
  2. 第二步说明
  3. 第三步说明
</Steps>

效果：

安装依赖

使用你喜欢的包管理器安装依赖
Terminal window
```
npm install starlight-theme-rapide
```
配置主题

在 astro.config.mjs 中添加 Rapide 主题配置
创建内容

在 src/content/docs/ 目录下创建你的文档文件
启动开发服务器

运行开发服务器预览效果
Terminal window
```
npm run dev
```

3.5 文件树（FileTree）

用于展示项目结构。

import { FileTree } from '@astrojs/starlight/components';

<FileTree>
  - src/
    - content/
      - docs/
        - guides/
          - getting-started.md
          - syntax-guide.mdx
        - index.mdx
    - components/
    - styles/
  - astro.config.mjs
  - package.json
</FileTree>

效果：

Directorysrc/
- Directorycontent/
  - Directorydocs/
    Directoryguides/
    getting-started.md
    rapide-syntax-guide.mdx
    index.mdx
- Directorycomponents/
  - CustomHeader.astro
- Directorystyles/
  - custom.css
  - katex.css
astro.config.mjs
package.json
README.md

3.6 链接按钮（LinkButton）

创建醒目的行动号召按钮。

import { LinkButton } from '@astrojs/starlight/components';

<LinkButton href="https://example.com" variant="primary">
  开始使用
</LinkButton>

效果：

访问 Rapide 官网

📐 四、LaTeX 数学公式

Rapide 主题完美支持 LaTeX 数学公式（需要配置 remark-math 和 rehype-katex）。

4.1 行内公式

使用单个 $ 包裹：

语法：

爱因斯坦的质能方程：$E = mc^2$

效果： 爱因斯坦的质能方程： $E = mc^2$

4.2 块级公式

使用双 $$ 包裹：

语法：

$$
\frac{d}{dx}\left( \int_{a}^{x} f(u)\,du\right) = f(x)
$$

效果：

\frac{d}{dx}\left( \int_{a}^{x} f(u)\,du\right) = f(x)

4.3 复杂公式示例

矩阵：

\begin{pmatrix} a & b & c \\ d & e & f \\ g & h & i \end{pmatrix}

方程组：

\begin{cases} x + y = 5 \\ 2x - y = 1 \end{cases}

积分：

\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}

求和：

\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}

🎯 五、综合示例

下面是一个综合使用多种语法的完整示例：

跟随以下步骤学习 Rapide 主题：

了解基础语法

掌握 Markdown 基本语法和标注用法
学习代码块

了解如何在文档中展示代码
Terminal window
```
const theme = "rapide";
console.log(`当前主题: ${theme}`);
```
使用组件

学习使用卡片、选项卡等组件丰富内容
实践应用

创建自己的文档项目

代码示例

展示各种编程语言的代码片段

标注提示

使用不同类型的标注突出重要信息

数学公式

支持 LaTeX 公式： $\int_{0}^{1} x^2 dx$

交互组件

选项卡、步骤等丰富的交互组件

📖 六、最佳实践

🎉 总结

通过本指南，你应该已经掌握了 Rapide 主题的主要语法：

✅ 5种标注类型：note, tip, caution, danger
✅ 代码块：支持几乎所有编程语言，自动行号
✅ 组件：Badge, Card, Tabs, Steps, FileTree, LinkButton
✅ LaTeX 公式：行内和块级数学公式
✅ 最佳实践：如何编写高质量文档

现在开始使用 Rapide 创建你的精美文档吧！ 🚀