1 HTML output

Currently we have provided a number of different styles for HTML output:

the GitBook style (Section 1.1)
the three-column Bootstrap style (bs4_book) (Section 1.2)
the default Bootstrap style (Section 1.3)
the Tufte style (Section 1.4)

1.1 Gitbook

1.1.1 创建Gitbook

采用Rstudio创建 File > New Project > New Directory > Book project using bookdown
采用函数创建 bookdown::create_gitbook()

1.1.2 Gitbook基本参数

gitbook(fig_caption = TRUE, number_sections = TRUE,
        self_contained = FALSE, anchor_sections = TRUE,
        lib_dir = "libs", global_numbering = !number_sections,
        pandoc_args = NULL, extra_dependencies = list(),..., 
        template = "default", 
        split_by = c("chapter","chapter+number", "section", "section+number","rmd", "none"), 
        split_bib = TRUE, config = list(), 
        table_css = TRUE, code_folding = c("none", "show","hide"))

大部分的参数是直接传递给rmarkdown::html_document()的，例如fig_caption
fig_caption=TRUE的好处在于，便于解释图片且LaTeX输出时确保图片是悬浮的
图片的编号取决于number_sections，如果为TRUE，则图编号为X.i，X为章节编号
css参数提供引用格式样式
html_document()的一些参数已经硬编码在gitbook()中，你不能改变它们:
- toc = TRUE(必须有一个目录)
- theme = NULL(不使用任何Bootstrap主题)
- template(存在一个内部的gitbook模板)
如果设置self_contained = TRUE，文件大小会非常大，因为需要的内容会嵌入html文件中

1.1.3 Gitbook三个特有的参数

除了html_document()的参数，gitbook()有三个自己的参数

split_by指定如何将HTML输出分割为多个页面
- rmd:使用输入rmd文件的基本文件名来创建HTML文件名，例如，为chapter3.Rmd生成chapter3.html。
- none:不拆分HTML文件(书将是一个单独的HTML文件)。
- chapter:按一级标题分割文件。
- section:按二级头文件分割文件。
- chapter+number:类似于capter和sector节，但文件将被编号。

# An Introduction {#introduction}
默认的名称为 `an-introduction`, 但我们把它改为`introduction`.

split_bib 默认情况下，参考书目是分开的，相关的引用条目放在每个页面的底部。可以使用split_bib = FALSE 禁用该功能，在这种情况下，所有引用都放在一个单独的页面上
config

#控制目录格式
bookdown::gitbook:
  config:
    toc:#toc选项控制目录(toc)的格式
      collapse: subsection
#折叠一些项：subsection, section, none (or null).
      scroll_highlight: true
#当你滚动书体时，是否启用TOC项目的高亮显示(默认情况下该功能是启用的)
      before: null
      after: null
#在toc前后添加一些句子

#工具条位置及文本显示设置
bookdown::gitbook:
  config: 
#GitBook样式在每个页面的顶部都有一个工具栏，允许您动态更改图书设置。
    toolbar:
#设置工具栏位置 position
      position: fixed#fixed保持toolbar永远在页面顶部，static随滑动消失

#设置显示样式 fontsettings   
    fontsettings:#预设文字样式，也可以后续通过toolbar修改
      theme: Sepia
      family: sans
      size: 2
      
# 信息('i')按钮，它列出了用于导航文档的键盘快捷键。此按钮可通过设置FALSE隐藏     
    info: true

#编辑、下载和分享功能
bookdown::gitbook:
  config:    
    toolbar:
#设置能否编辑 edit
    edit : null #控制是否允许编辑

#添加下载格式 download,null则不添加该选项  
    download: ["pdf", "epub", "mobi"]#提供下载选项格式
    #当download为null时，gitbook()将在 book output directory中查找PDF、EPUB和MOBI文件，并自动将它们添加到下载选项中。如果你只是想抑制下载按钮，使用download: false

#添加搜索按钮 search，FALSE则不添加该选项 
    search:
      engine: lunr # or fuse
      # options to control/tune search engine behavior (for
      # fuse.js, refer to https://fusejs.io/api/options.html)
      options: null

#添加分享按钮 sharing,设置为null则不显示
    sharing:
      facebook: true
      github: false
      twitter: true
      linkedin: false
      weibo: false
      instapaper: false
      vk: false
      whatsapp: false
      all: ['facebook', 'twitter', 'linkedin', 'weibo', 'instapaper']

1.1.4 其他html设置

title: "An Awesome Book"
author: "John Smith"
description: "This book introduces the ABC theory, and ..."
#要写在HTML头部 content attribute of the tag <meta name="description"content="">(如果缺少，将使用书名)。
#这对于搜索引擎优化(SEO)非常有用。

url: 'https\://bookdown.org/john/awesome/'
#这本书的网址

github-repo: "john/awesome"
#表单书籍的GitHub存储库

cover-image: "images/cover.png"
#指向书籍封面图像的路径

apple-touch-icon: "touch-icon.png"
#图标的路径(例如，PNG图像)。这仅适用于iOS:当网站添加到主屏幕时，链接由这个图标表示。

apple-touch-icon-size: 120
#图标的大小(默认为152 x 152像素)。

favicon: "favicon.ico"
#通往“收藏图标”的路径。通常，此图标显示在浏览器的地址栏中，如果浏览器支持选项卡，则显示在选项卡的页面标题前面。

1.2 bs4_book

一个bs4_book的例子:Mastering Shiny

1.2.1 创建bs4_book

R studio: File > New Project > New Directory > Book project using bookdown > select bs4_book
函数：bookdown::create_bs4_book()
这种风格是为每页只有一章的书籍设计的。这意味着每个章节都是一个. rmd文件，而每个. rmd文件可以包含一个章节。

#   A chapter

##  A section

### A subsection

1.2.2 设置样式

设置链接颜色 theme:primary

bookdown::bs4_book:
  theme:
    primary: "#0d6efd"

字体设置,通过google:调用sass::font_google()设置字体样式

bookdown::bs4_book:
  theme:
    primary: "#0d6efd"   
    base_font: 
      google: Sen
    heading_font:
      google:
        family: Bitter
        wght: 200
    code_font:
      google: 
        # arguments to sass::font_google() 
        family: DM Mono
        local: false

1.2.3 突出显示单元

::::{types}content:::,其中types包括
- .rmdnote注释
- .rmdcaution提醒
- .rmdimportant重要
- .rmdtip提示
- .rmdwarning警告

::: {.rmdnote}
The `bs4_book` style also includes an `.rmdnote` callout block
like this one.
:::

可以对上述单元分别设置颜色

bookdown::bs4_book:
  theme:
    primary: "#0d6efd"   # default .rmdnote = blue
    danger:  "#dc3545"   # default .rmdcaution = red
    success: "#198754"   # default .rmdimportant = green
    info:    "#0dcaf0"   # default .rmdtip = cyan
    warning: "#ffc107"   # default .rmdwarning = yellow

1.2.4 设置脚注位置

bs4_book使任何脚注在悬停时内联显示，而不是在页面底部显示链接项。你可以设置footnotes_inline = FALSE来选择退出这种行为，并将脚注保留在底部。

bookdown::bs4_book:
  footnotes_inline: false

1.2.5 设置引用

bs4_book在默认情况下使脚注在单击时内联显示。要做到这一点，可以下载一个脚注风格的CSL文件。

例如，下载chicago-fullnote-bibliography.csl，然后将此添加到index.Rmd。

bibliography: refs.bib
csl: chicago-fullnote-bibliography.csl

如果不想在书的最后显示引用，在index.Rmd中添加

suppress-bibliography: true

和gitbook一样，在YAML中设置split_bib控制引用在每章之后

bookdown::bs4_book:
  split_bib: true

1.2.6 设置库

为你的书指定一个源存储库，让你的读者可以选择轻松地查看每章的源文件或编辑。

bookdown::bs4_book:
  repo:
    base: https://github.com/hadley/ggplot2-book
    branch: main
    subdir: book

1.3 default Bootstrap style

R markdown的默认格式：html_document()
bookdown基于html_document()的格式：html_book()
更普遍的章节格式：html_chapter()

html_chapters(toc = TRUE, number_sections = TRUE, fig_caption = TRUE,
  lib_dir = "libs", template = bookdown_file("templates/default.html"),
  global_numbering = !number_sections, pandoc_args = NULL,
  ..., base_format = rmarkdown::html_document, split_bib = TRUE,
  page_builder = build_chapter, split_by = c("section+number",
    "section", "chapter+number", "chapter", "rmd", "none"))

1.4 Tufte style

提供tufte_html_book()格式：一个例子

2 Other format

Other format includes

LaTeX/PDF (Section 2.1)
Ebooks (Section 2.2)
Single document (Section 2.3)

2.1 LaTeX/PDF format

bookdown::pdf_book()

pdf_book(toc = TRUE, number_sections = TRUE, fig_caption = TRUE,
  pandoc_args = NULL, ..., base_format = rmarkdown::pdf_document,
  toc_unnumbered = TRUE, toc_appendix = FALSE, toc_bib = FALSE,
  quote_footer = NULL, highlight_bw = FALSE)

2.2 E-books

目前bookdown提供两种电子书格式，EPUB和MOBI。这些格式的书籍可以在智能手机、平板电脑或Kindle等特殊电子阅读器上阅读。
bookdown::epub_book()

epub_book(fig_width = 5, fig_height = 4, dev = "png",
  fig_caption = TRUE, number_sections = TRUE, toc = FALSE,
  toc_depth = 3, stylesheet = NULL, cover_image = NULL,
  metadata = NULL, chapter_level = 1, epub_version = c("epub3",
    "epub", "epub2"), md_extensions = NULL, global_numbering = !number_sections,
  pandoc_args = NULL, template = "default")

2.3 Sigle document

rmarkdown::render()不具备bookdown的自动编号、交叉引用功能
采用bookdown的文件格式生成单一文件，并且保留这些功能
- html_document2()
- tufte_html2()
- pdf_document2()
- word_document2()
- tufte_handout2()
- tufte_book2()

output:
  bookdown::html_document2: default
  bookdown::pdf_document2:
    keep_tex: true
  bookdown::word_document2:
    toc: true

可以修改base_format来设置基于的格式

output:
  bookdown::pdf_book:
    base_format: rticles::jss_article

Bookdown Output Format