欢迎来到我的文档网站

my-book/
├── book.toml          # 配置文件
├── src/              # 源文件目录
│   ├── SUMMARY.md    # 目录结构
│   ├── chapter_1.md  # 章节文件
│   └── images/       # 图片资源
└── book/             # 构建输出目录

配置文件 (book.toml)

book.toml 是 mdBook 的主要配置文件，包含：

[book] 部分：书籍的基本信息
[build] 部分：构建相关设置
[output] 部分：输出格式配置

目录文件 (SUMMARY.md)

SUMMARY.md 定义了书籍的目录结构和导航。它支持：

嵌套章节
链接到外部资源
分割线和分组

Markdown 扩展

mdBook 支持标准 Markdown 语法，同时还提供了一些扩展功能：

代码块

支持语法高亮：

fn main() {
    println!("Hello, mdBook!");
}

数学公式

支持 KaTeX 数学公式（需要启用）：

\[ \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} \]

提示框

注意： 这是一个重要的提示信息。

链接

内部链接：[章节名称](./chapter.md)
外部链接：[网站](https://example.com)

配置说明

本章详细介绍 mdBook 的各种配置选项。

基本配置

[book] 部分

[book]
title = "我的书籍"
authors = ["作者姓名"]
language = "zh-cn"
description = "书籍描述"
src = "src"

[build] 部分

[build]
build-dir = "book"    # 输出目录
create-missing = true # 自动创建缺失的文件
use-default-preprocessors = true

输出配置

HTML 输出

[output.html]
theme = "light"                    # 默认主题
default-theme = "light"            # 默认主题
preferred-dark-theme = "navy"      # 暗黑主题
curly-quotes = true               # 智能引号
mathjax-support = false           # MathJax 支持
copy-fonts = true                 # 复制字体文件
google-analytics = "UA-XXXXXX"    # Google Analytics
additional-css = ["theme/custom.css"]  # 自定义CSS
additional-js = ["theme/custom.js"]    # 自定义JS

Git 集成

[output.html]
git-repository-url = "https://github.com/user/repo"
git-repository-icon = "fa-github"
edit-url-template = "https://github.com/user/repo/edit/main/src/{path}"

预处理器

链接检查

[preprocessor.links]
# 启用链接检查

索引

[preprocessor.index]
# 生成索引页面

自定义主题

可以通过以下方式自定义主题：

创建 theme 目录
添加自定义 CSS 和 JS 文件
修改 HTML 模板

目录结构

theme/
├── index.hbs          # 主页模板
├── css/
│   └── variables.css  # CSS 变量
└── js/
    └── custom.js      # 自定义脚本

最佳实践

以下是使用 mdBook 的一些最佳实践建议。

文档组织

目录结构

保持清晰的目录结构：

src/
├── SUMMARY.md
├── introduction.md
├── tutorials/
│   ├── basic.md
│   └── advanced.md
├── reference/
│   ├── api.md
│   └── config.md
└── assets/
    ├── images/
    └── videos/

命名约定

使用小写字母和连字符：getting-started.md
避免特殊字符和空格
保持文件名简洁且描述性强

内容编写

Markdown 最佳实践

使用清晰的标题层次

# 一级标题
## 二级标题
### 三级标题

合理使用列表
- 使用无序列表表示不相关的项目
- 使用有序列表表示步骤或优先级
代码块格式化
```
\`\`\`语言名称
代码内容
\`\`\`
```

图片和媒体

将图片存放在专门的目录中
使用相对路径引用图片
提供替代文本（alt text）

![描述文字](./images/screenshot.png)

维护和更新

版本控制

使用 Git 进行版本控制
编写清晰的提交信息
定期备份重要内容

持续集成

设置 GitHub Actions 自动构建和部署：

name: Deploy mdBook
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup mdBook
      uses: peaceiris/actions-mdbook@v1
    - name: Build
      run: mdbook build
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./book

性能优化

图片优化

压缩图片以减少文件大小
使用适当的图片格式（WebP、PNG、JPG）
提供不同分辨率的图片版本

内容优化

避免过长的页面
合理分割内容
使用目录和索引提高导航性

可访问性

提供清晰的标题结构
使用语义化的 Markdown
确保颜色对比度足够
添加适当的替代文本

常见问题

这里收集了使用 mdBook 时的常见问题和解决方案。

安装问题

Q: 无法安装 mdBook

A: 确保您已安装 Rust 和 Cargo：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
cargo install mdbook

Q: mdbook 命令未找到

A: 确保 Cargo 的 bin 目录在您的 PATH 中：

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

构建问题

Q: 构建失败，提示链接错误

A: 检查 SUMMARY.md 中的链接是否正确，确保所有引用的文件都存在。

Q: 图片无法显示

检查图片路径是否正确
确保使用相对路径
验证图片文件是否存在于 src 目录中

部署问题

Q: GitHub Pages 显示 404 错误

确保构建输出目录设置正确
检查 GitHub Pages 设置中的源分支
确认 index.html 文件存在于根目录

Q: 样式丢失或显示异常

检查基础 URL 设置
确保所有 CSS 和 JS 文件都被正确复制
检查浏览器控制台是否有错误信息

内容问题

Q: 数学公式不显示

A: 在 book.toml 中启用 MathJax 支持：

[output.html]
mathjax-support = true

Q: 代码高亮不工作

A: 确保代码块指定了正确的语言：

\`\`\`rust
fn main() {
    println!("Hello, world!");
}
\`\`\`

Q: 中文字符显示异常

A: 确保文件以 UTF-8 编码保存，并在 book.toml 中设置正确的语言：

[book]
language = "zh-cn"

自定义问题

Q: 如何修改主题颜色

A: 创建自定义 CSS 文件并在配置中引用：

[output.html]
additional-css = ["theme/custom.css"]

Q: 如何添加自定义 JavaScript

A: 类似于 CSS，添加 JS 文件：

[output.html]
additional-js = ["theme/custom.js"]

Keyboard shortcuts

我的文档网站