.unlisted and .unnumbered not excluding tagged headers from TOC

[AmyMikhail]

I have an r markdown document which is being knit to Microsoft Word. I need the table of contents to appear after the summary text, which I have achieved with adding officer::block_toc() in a chunk after the summary.

However, the problem is that the table of contents displays its own title (and that of the summary section) which I don't want. I understand the correct way to exclude a section header from the table of contents is to add the unlisted and unnumbered tags after the header to remove, e.g.: # Summary {.unlisted .unnumbered}. It seems that neither tag is working, even after updating R, RStudio and all the required packages to the latest versions. The output shows the table of contents including itself and the Summary section before it as numbered items.

Here is an example:

---
title: "Contents test"
author: "Amy Mikhail"
date: "2023-07-11"
lang: de-DE
output: 
  officedown::rdocx_document:
    reference_docx: "templates/vorlagendokument.docx"
---

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

# Set chunk options:
knitr::opts_chunk$set(echo = FALSE, 
                      message = FALSE, 
                      warning = FALSE, 
                      eval = TRUE,
                      ft.align = "left",
                      fig.width = 10,
                      out.width = "100%")

```


```{r example_data}

df <- data.frame(id = c(1,2,3), 
                 fruit = c("apple", "berry", "apple"))

```


# Summary {.unlisted .unnumbered}

Of the people invited to complete the survey, `r nrow(df)` people responded.

\newpage

# Table of contents {.unlisted .unnumbered}

```{r create_toc}

officer::block_toc()

```


\newpage


# Introduction

## Objectives

These are the objectives.

## Background

This is the background.

\newpage

# Methods

These are the methods.

\newpage

# Results

These are the results.

Here is what the TOC looks like when this is run - the first two items should have been excluded but they are still there:

2.	Table of contents
   1.	Summary........................................	0
   2.	Table of contents.........................	1
   3.	Introduction..................................	2
        3.1.	Objectives............................	2
        3.2.	Background.........................	2
   4.	Methods.........................................	3
   5.	Results.............................................	4

Here is my session info:

> xfun::session_info('bookdown')
R version 4.3.1 (2023-06-16 ucrt)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows 10 x64 (build 19045), RStudio 2023.6.1.524


Locale:
  LC_COLLATE=English_United Kingdom.utf8  LC_CTYPE=C                             
  LC_MONETARY=English_United Kingdom.utf8 LC_NUMERIC=C                           
  LC_TIME=English_United Kingdom.utf8    

time zone: Europe/London
tzcode source: internal

Package version:
  base64enc_0.1.3   bookdown_0.34     bslib_0.5.0       cachem_1.0.8      cli_3.6.1        
  digest_0.6.33     ellipsis_0.3.2    evaluate_0.21     fastmap_1.1.1     fontawesome_0.5.1
  fs_1.6.2          glue_1.6.2        graphics_4.3.1    grDevices_4.3.1   highr_0.10       
  htmltools_0.5.5   jquerylib_0.1.4   jsonlite_1.8.7    knitr_1.43        lifecycle_1.0.3  
  magrittr_2.0.3    memoise_2.0.1     methods_4.3.1     mime_0.12         R6_2.5.1         
  rappdirs_0.3.3    rlang_1.1.1       rmarkdown_2.23    sass_0.4.6        stats_4.3.1      
  stringi_1.7.12    stringr_1.5.0     tinytex_0.45      tools_4.3.1       utils_4.3.1      
  vctrs_0.6.3       xfun_0.39         yaml_2.3.7   

Checklist

When filing a bug report, please check the boxes below to confirm that you have provided us with the information we need. Have you:

• formatted your issue so it is easier for us to read?

• included a minimal, self-contained, and reproducible example?

• pasted the output from xfun::session_info('bookdown') in your issue?

• upgraded all your packages to their latest versions (including your versions of R, the RStudio IDE, and relevant R packages)?

• installed and tested your bug with the development version of the bookdown package using remotes::install_github("rstudio/bookdown") ?

-->

[AmyMikhail]

Also to add - I note this same issue occured in 2020 but was resolved - so something seems to have triggered it to occur again. For reference the 2020 issue is #894 .

[cderv]

First the issue you mentions is about a Pandoc version. The resolution has been done with a newer Pandoc. Do check your pandoc version (rmarkdown::pandoc_version()).

Also it relates to bookdown output. Your issue here is about officedown::rdocx_document - how does it related to bookdown ?

Just in case, here the reason it does not work with a bookdown::word_document2() or rmarkdown::word_document() : This .unlisted feature is a Pandoc feature, and it currently does not work for DOCX output. Mentions is in: https://pandoc.org/MANUAL.html#extension-header_attributes

If the unlisted class is present in addition to unnumbered, the heading will not be included in a table of contents. (Currently this feature is only implemented for certain formats: those based on LaTeX and HTML, PowerPoint, and RTF.)

However, why open an issue here and not in https://github.com/davidgohel/officedown/ ?

If you would have looked there you would see that this Pandoc limitation is also affecting officedown unfortunately

• Support {.unlisted .unnumbered} to exclude headings from table of contents davidgohel/officedown#111

[AmyMikhail]

@cderv I saw the mentions of the pandoc version issue, but I think mine is up to date (at least it is not the same version mentioned in the 2020 post):

> rmarkdown::pandoc_version()
[1] ‘3.1.1’

I posted the issue here because I am using both bookdown and officedown and I saw the same issue had been posted here a few years ago. But you are right, perhaps it would be better to post in officedown issues as people using officedown are knitting only to Microsoft products.

[cderv]

It is fine to post here if you have issue with bookdown too.

Note what I said above though: .unlisted is not supported by Pandoc DOCX output. This is why it is not working with bookdown nor officedown

[AmyMikhail]

@cderv yes, it seems that the problem is Microsoft Word itself does not have a facility to supress individual headers from the TOC. Instead I removed the hash tag from the TOC title, created a custom text format with officer::fp_text() and applied it to the TOC title with officer::ftext(). For MS Word this works, because the custom text format is not one of the levels automatically included in the TOC.

I've added the solution to a Stack Overflow post I had on how to change the location of the TOC here

I have not tested whether the tags work when knitting to .pdf or HTML - if they do, this issue can be closed.