英文:

r markdown add executive summary before TOC and knit to MS Word

问题

我有一个自动化报告，我正在使用R Markdown创建，并将其编译成Microsoft Word文档。在报告的开头，有一个执行摘要，其中包括一些内联代码引用计算出的数字。执行摘要显示在有颜色的背景上，我通过在参考文档中创建自定义样式来实现。

目前，目录总是打印在文档的开头，但我希望它出现在执行摘要之后。我仍然希望它包括通常的内容格式（编号标题和页码），因为有些人可能会查看打印文档（纸质文档），因此超链接并不总是足够的。

我已经寻找了解决方案，但似乎没有一个完全适合我的情况。

例如，render_toc() 函数在文档的任何位置以超链接列表的形式打印内容，但它不编号标题，也不打印页码。

我还看到了latex的\tableofcontents标签，但这对于Microsoft Word输出不起作用。

我找到的唯一其他可能的解决方案是在我的YAML头部中使用参数include-before，但我找到的唯一示例都在YAML头部中显示了实际文本（例如见此处），但这对我的情况不起作用，因为它是一个具有大量内联代码并且需要出现在自定义CSS样式着色背景上的复杂摘要。

有人有任何建议吗？

以下是一个小而（非常）简化的示例 - 我希望文档标题和执行摘要位于第一页，然后目录应该在第2页的分页符之后开始，然后其余部分应在目录之后：

---
title: "My report"
toc-title: "Report contents"
output: 
  officedown::rdocx_document:
    reference_docx: "templates/wordtemplate.docx"
    toc: TRUE
    toc_depth: 3
---

```{r setup, include=FALSE, purl=FALSE}

# 设置块选项：
knitr::opts_chunk$set(echo = FALSE, 
                      message = FALSE, 
                      warning = FALSE, 
                      eval = TRUE,
                      ft.align = "left",
                      fig.width = 10,
                      out.width = "100%")

# 示例数据：
df <- data.frame(id = c(1,2,3), fruit = c("apple", "orange", "apple"))

:::{custom-style="Colour_background"}

执行摘要

有r nrow(df)人回答了调查。

:::

\pagebreak

引言

目标

研究目标

背景

研究背景

方法

一些方法文本

结果

一些结果文本

<details>
<summary>英文:</summary>

I have an automated report which I am creating in R markdown and knitting to Microsoft Word.  At the start of the report, there is an executive summary which includes some inline code referencing calculated figures.  The executive summary is displayed on a coloured background, which I achieved by creating a custom style in the reference document.

Currently, the table of contents is always printed at the beginning of the document, however I would like it to appear after the executive summary.  I would still like it to include the usual contents formatting (numbered headings and page numbers) as some people may be looking at the printed document (hard copy) so hyperlinks will not always be sufficient.

I&#39;ve had a look for solutions, but none of them quite seem to fit my scenario.  

For example, the [`render_toc()` function here](https://www.garrickadenbuie.com/blog/add-a-generated-table-of-contents-anywhere-in-rmarkdown/) prints the contents as a list of hyperlinks anywhere in the document, but it doesn&#39;t number headings and also doesn&#39;t print the page numbers.

I&#39;ve also seen the latex `\tableofcontents` tag but this doesn&#39;t work for a Microsoft word output.   

The only other potential solution I could find was to use the parameter `include-before` in my YAML header - but the only examples I can find of this show the actual text in the YAML header (for example [see here](https://stackoverflow.com/questions/25591517/pandoc-inserting-pages-before-generated-table-of-contents)), which won&#39;t work for my case as it is a complex summary that has a lot of inline code and needs to appear on the custom css style coloured background. 

Does anyone have any suggestions?

Here is a small and (very) simplified example - I would expect the document title and executive summary to be on the first page, then the contents should start after the page break on page 2, then the remaining sections should be after the contents:


    ---
    title: &quot;My report&quot;
    toc-title: &quot;Report contents&quot;
    output: 
      officedown::rdocx_document:
        reference_docx: &quot;templates/wordtemplate.docx&quot;
        toc: TRUE
        toc_depth: 3
    ---
    
    ```{r setup, include=FALSE, purl=FALSE}
    
    # Set chunk options:
    knitr::opts_chunk$set(echo = FALSE, 
                          message = FALSE, 
                          warning = FALSE, 
                          eval = TRUE,
                          ft.align = &quot;left&quot;,
                          fig.width = 10,
                          out.width = &quot;100%&quot;)
    
    ```
    
    ```{r data}
    
    # Example data:
    df &lt;- data.frame(id = c(1,2,3), fruit = c(&quot;apple&quot;, &quot;orange&quot;, &quot;apple&quot;))
    
    ```
    
    :::{custom-style=&quot;Colour_background&quot;}
    
    &lt;br&gt;
    
    # Executive summary
    
    There were `r nrow(df)` people who responded to the survey.
    
    &lt;br&gt;
    
    :::
    
    \pagebreak
    
    # Introduction
    
    ## Objectives
    
    Objectives of study
    
    ## Background
    
    Background to study
    
    # Methods
    
    Some methods text
    
    # Results
    
    Some results text






</details>


# 答案1
**得分**: 2

我找到了一个答案 - 在这里放置与相关的S/O帖子的链接，因为我之前找不到它。

如果有其他人在将R标记转换为Microsoft Word时遇到类似的问题，可以通过同时使用`officedown`和`officer`包来解决许多这些问题。

首先要做的是在YAML头部中删除任何关于目录的提及：

```yaml
---
title: "我的报告"
output: 
  officedown::rdocx_document:
    reference_docx: "templates/wordtemplate.docx"
---

然后可以在R标记中的任何位置使用officer::block_toc()函数插入目录。请注意，此函数不会自动为目录添加标题。

请注意，如果在样式TOC标题时使用井号 #，并且包括了您设置为在TOC中显示的级别中的井号数，TOC还将包括自己的标题。要解决此问题并阻止TOC标题出现在TOC中，有两个选项：

1. 使用更多的井号（例如，如果TOC级别= 3，请使用4个井号）
2. 创建一个自定义文本样式，并将其应用于TOC标题

如果选择选项1，您可能会希望修改级别4标题的样式（否则，字体将相对于其他标题而言相当小）。这可以通过更改参考文档中的级别4标题的样式来完成，或者通过使用 officer 更新级别4标题的样式。

我发现不碰预先样式化的级别标题，选择选项2 并创建自己的自定义文本样式会更清晰。可以使用officer::fp_text()完成此操作，并将其应用于任何不希望包括在TOC中的部分标题：

```{r nontoc_headerstyle}
# 检查是否安装了pacman，如果没有则安装：
if (!require("pacman")) install.packages("pacman")

# 加载所需的库：
pacman::p_load(officer, officedown)

# 为不应出现在TOC中的部分标题创建一个样式：
nontoc_header <- officer::fp_text(
  color = "darkblue", 
  font.size = 16, 
  bold = TRUE,
  font.family = "Calibri"
)

然后在R标记正文文本中添加TOC标题，以显示TOC的位置（例如，在分页后），并使用新创建的自定义文本样式进行格式化：

```r
\newpage

`r ftext("报告目录", prop = nontoc_header)`

最后，在其自己的代码块中使用officer::block_toc()函数（并包括您想要的任何修改，例如更改TOC深度）：

```{r create_toc}
# 插入目录：
officer::block_toc(level = 3)

\newpage

请注意，在输出为Microsoft Word时，使用`pandoc`标签`{.unlisted .unnumbered}` 从TOC中抑制特定部分标题不起作用，这是因为MS Word构建TOC的方式（参见[此处](https://github.com/davidgohel/officedown/issues/111) 和 [此处](https://pandoc.org/MANUAL.html#extension-header_attributes)）。

<details>
<summary>英文:</summary>

I found an answer - putting the link to the relevant S/O post [here](https://stackoverflow.com/questions/61104292/how-can-i-separate-the-title-page-from-the-table-of-contents-in-a-rmarkdown-word), as I was unable to find it earlier. 

In case anyone else is struggling with similar issues knitting R markdown to Microsoft Word, a lot of these challenges are solved by using the `officedown` and `officer` packages together.

The first thing to do is remove any mention of the TOC in the YAML header:

---

title: "My report"
output:
officedown::rdocx_document:
reference_docx: "templates/wordtemplate.docx"

The table of contents can then be dropped anywhere in the r markdown using the `officer::block_toc()` function.  Note that this function does not automatically give the table of contents a title.  

Note that if using the hash symbol `#` to style the TOC title and the number of hashes is included in the levels that you have set to be displayed in the TOC, the TOC will also include its own title.  To work around this issue and supress the TOC title from itself appearing in the TOC, there are two options: 

 1. Use more hashes (for example if TOC level = 3, use 4 hashes)
 2. Create a custom text style and apply that to the TOC title instead

If using option 1, you would probably want to modify the style of the level 4 header (otherwise the font will be quite small relative to the other headers). This could be done by changing the style of header level 4 in the reference_docx or alternatively by updating the style of level 4 headers with `officer`. 

I found it cleaner not to touch the pre-styled level headers and go with option 2 to create my own custom text style.  This can be done with `officer::fp_text()` and applied to any section headers that I don't want to include in the TOC:

# Check if pacman is installed, install if not:
if (!require("pacman")) install.packages("pacman")

# Load required libraries:
pacman::p_load(officer, officedown)

# Create a style for section headers that should not appear in the TOC:
nontoc_header <- officer::fp_text(
  color = "darkblue", 
  font.size = 16, 
  bold = TRUE,
  font.family = "Calibri"
)

Then add the TOC title in the R markdown body text where you wish the TOC to appear (e.g. after a page break) and format it using the newly created custom text style:

```
\newpage

`r ftext("Report contents", prop = nontoc_header)`
```

Finally, use the `officer::bloc_toc()` function in its own code chunk (and include any modifications you want, e.g. change the toc depth):

    ```{r create_toc}
    # Insert the table of contents:    
    officer::block_toc(level = 3)
    ```
    \newpage

Note that suppressing specific section headers from the TOC with the `pandoc` tags `{.unlisted .unnumbered}` does not work if the output is Microsoft Word, due to the way MS Word constructs TOCs (see [here](https://github.com/davidgohel/officedown/issues/111) and [here](https://pandoc.org/MANUAL.html#extension-header_attributes)).

</details>