rstudio/bookdown · 上手攻略

  • 仓库：rstudio/bookdown
  • 链接：https://github.com/rstudio/bookdown
  • 分类：academic-writing / 学术与技术写作工具
  • 作者：spark
  • 更新：2026-08-13

是什么

rstudio/bookdown 是 RStudio/Posit 出品的开源 R 包(GPL-3),作者以 Yihui Xie 为主。核心目标:用 R Markdown(.Rmd) 作为单一源文件,一键产出印刷级图书、技术报告、长文章、教程,输出格式覆盖 HTML(分章节的 gitbook / bs4_book)、PDF(LaTeX)、EPUB、Word。

它不是另一个 Markdown 编辑器,而是"扩展 Pandoc 的 R Markdown 风味":在标准 Markdown 语法基础上,额外支持 # (PART) 分部、{#label} 交叉引用、{bookdown} 跨章节图表/公式自动编号、HTML widgets/Shiny 嵌入、LaTeX 定理与证明环境、CSL 文献引用、多语言代码块(R / Python / SQL / C++ 同文档共存)。

解决什么问题

学术/技术写作长期几个老大难:

  1. 多输出格式重复维护:同一份教材要 HTML 在线版 + PDF 印刷版 + EPUB Kindle 版,LaTeX 单独管 PDF、Markdown 单独管 HTML,改一处要改三遍。bookdown 一份 .Rmd 出多格式。
  2. 图表/公式/参考文献跨章节编号:纯 Markdown 不会自动续编号,LaTeX 写起来繁琐。bookdown 自动处理,引用用 \@ref(fig:label) \@ref(eq:label)。
  3. 代码运行结果与文档脱节:R/Python 代码块输出可以内嵌到文档里(echo=FALSE 跑代码但只显示结果),随数据更新重渲染即可。
  4. 学习曲线 vs LaTeX:LaTeX 上手成本高,Markdown 易学,但纯 Markdown 又撑不起"章/节/定理/索引"。bookdown 把两者缝起来。

快速安装

从 CRAN(推荐,稳定版):

install.packages("bookdown")

从 GitHub 开发版(用 pak 包):

# install.packages("pak")
pak::pak("rstudio/bookdown")

第一次写新书的捷径(RStudio IDE):File > New Project > New Directory > Book project using bookdown,会自动生成一个最小可跑示例(含 index.Rmd、_bookdown.yml、_output.yml、几个章节 .Rmd、参考文献 .bib)。

最小可跑命令(命令行,R 会话内):

library(bookdown)
bookdown::render_book("index.Rmd")   # 默认按 _output.yml 配置产出多种格式
bookdown::serve_book()               # 本地起 HTTP 服务,实时重渲染(开发期用)

非交互环境下可改用命令行 pandoc 路径(由 bookdown 内部生成),或用 bookdown::publish_book() 一键部署到 Posit Connect。

核心用法

1. 项目骨架(最小 4 文件)

my-book/
├── index.Rmd          # 第一章 YAML 头部 + 内容,bookdown 把它当入口
├── 01-intro.Rmd       # 章节文件名建议数字前缀保证顺序
├── 02-method.Rmd
├── 03-results.Rmd
├── _bookdown.yml      # 全局配置(输出格式/章节合并/书籍元数据)
├── _output.yml        # 各输出格式详细参数(theme、css、toc-depth…)
├── bibliography.bib   # 文献 BibTeX
└── preamble.tex       # 可选,LaTeX 导言区补充

2. YAML 头部(index.Rmd)

---
title: "我的书名"
author: "Anan"
date: "2026-08-13"
site: bookdown::bookdown_site
documentclass: book
bibliography: [bibliography.bib]
biblio-style: apalike
link-citations: yes
description: "一句话简介"
---

site: bookdown::bookdown_site 是关键钩子,告诉 RStudio/knitr 这是个 bookdown 工程。

3. 常用扩展语法

  • 分部:# (PART) 基础篇 {-} 用括号标记 part,自动产生封面页。
  • 章节无编号:# 致谢 {-} 或 # 前言 {.unnumbered}。
  • 跨章节图表自动编号:图用 \@ref(fig:myfig)、表用 \@ref(tab:mytable)、公式用 \@ref(eq:myeq),只要在 chunk 里给 fig.cap = "..." 或给标题 # 描述 {#myfig} 即可。
  • 定理环境(LaTeX/PDF 输出):{theorem, rmdfamily} 块自动渲染成编号定理。
  • 代码块多语言:
```{r}
x <- 1:5; mean(x)
```

```{python}
import numpy as np
print(np.mean([1,2,3,4,5]))
```
  • 文献引用:@xie2015 告诉你…(CSL 风格),末尾 References 由 Pandoc 自动生成。
  • HTML widget/Shiny 嵌入:
```{r, echo=FALSE}
library(leaflet)
leaflet() %>% addTiles() %>% addMarkers(lng=121.5, lat=31.2, popup="Shanghai")
```

4. 输出格式切换

_output.yml 例:

bookdown::gitbook:
  css: style.css
  config:
    toc:
      collapse: section
    download: ["pdf", "epub"]
bookdown::pdf_book:
  includes:
    in_header: preamble.tex
  latex_engine: xelatex   # 中文/日文/韩文必选 xelatex
  citation_package: biblatex
bookdown::epub_book:
  stylesheet: style.css
bookdown::word_document:
  toc: true

CLI 单独出某格式:

bookdown::render_book("index.Rmd", output_format = "bookdown::pdf_book")
bookdown::render_book("index.Rmd", output_format = "bookdown::gitbook")

5. 一键发布

bookdown::publish_book()              # 默认走 bookdown.org
bookdown::publish_book(account = "yourname")  # 推 Posit Connect

典型适用场景

  • 学术教材/讲义:同一份 .Rmd 出印刷 PDF + 网页版 gitbook + Kindle EPUB,章节自动续编号。
  • 技术公司内部文档:代码结果、图表、引用统一一处,数据更新 → 文档同步刷新。
  • 学位论文/长篇技术报告:定理、证明、公式、交叉引用齐全,PDF 走 LaTeX,审阅用 HTML。
  • 数据分析教程:跑 R/Python 代码块直接嵌入输出,读者"看到结果"+"复制命令"。
  • 多语言项目:中文/日文/CJK 用 latex_engine: xelatex + mainfont: 指定字体,公式照常渲染。

坑与注意

⚠️ Pandoc 版本敏感:gitbook TOC 与 Pandoc 3.2.1+ 有一段互动 issue(#1503),已被 bookdown 修复但仍建议固定 Pandoc 2.19+ 已知稳定组合。

⚠️ 中文 PDF 一定用 xelatex:pdflatex 对 CJK 支持差,务必把 latex_engine: xelatex 写进 _output.yml,并在 preamble.tex 配 \usepackage{xeCJK} + \setCJKmainfont{...}。

⚠️ bookdown.org 服务将下线:release 说明 "the bookdown.org server will be sunset soon in early 2026",官方推荐迁移到 connect.posit.cloud。若你项目还在用 publish_book() 默认账号,趁早改。

⚠️ HTML widget 在 PDF 输出里不会渲染:leaflet/DT/plotly 这类只能在 HTML 输出工作,PDF 里只会显示 placeholder 或代码块;要么分两版 _output.yml,要么用 fig.cap 截图兜底。

⚠️ 跨平台渲染差异:macOS/Linux/Windows 字体路径不同,中文 PDF 在不同机器重渲染可能字形不一致;建议在 README 明确"本项目 PDF 必须用 X 字体"或 CI 容器化。

⚠️ chunk cache:knitr 默认不缓存,大计算量章节可加 ```{r chunkname, cache=TRUE} 但缓存键变化时记得清 _bookdown_files/。

与同类对比

工具 单一源 多格式输出 代码内嵌 学术引用 学习曲线
bookdown (本仓库) ✅ Rmd ✅ HTML/PDF/EPUB/Word ✅ R/Py/SQL… ✅ Pandoc CSL 中
Quarto (下一代) ✅ qmd ✅ + reveal.js/dashboards ✅ 多语言 ✅ CSL 中
LaTeX + Pandoc ✅ .tex/.md 灵活 ⚠️ 受限 ✅ BibTeX 高
Sphinx + reST ✅ .rst ✅ HTML/PDF/EPUB ✅ ✅ 中高
Hugo / Jekyll ✅ Markdown ✅ HTML(静态站) ❌ ⚠️ 低
Jupyter Book ✅ .ipynb/.md ✅ HTML/PDF ✅ ✅ 中

相较 Quarto(bookdown 的官方"继任者"),bookdown 仍更轻、与 RStudio IDE 集成最深、社区教程(中文/英文)累计最厚,适合不愿迁移的项目。

一句话推荐结论

如果你的写作素材里有 R/Python 数据分析、图表、公式、引用,又要同时输出网页 + PDF + EPUB,bookdown 是 R 生态里门槛最低、综合最优的长文档方案——install.packages("bookdown") + RStudio 模板起手,半天出第一本可发布的书。

原始 commit/PR/issue 链接:https://github.com/rstudio/bookdown (main 分支)。最近一次显著 release 修复了 #1522 (prepend_chapter_title() 多 <title> 报错) 和 Pandoc 3.2.1+ 的 gitbook TOC 兼容(#1503)。具体 commit SHA 与 release tag 以 GitHub Releases 页为准。