How to add a page before table of contents with pagedown

[dgkeyes]

Following up on my Twitter ask, I'm posting here at the request of @rlesur.

I'm making a custom pagedown template and trying to add a page that shows up after the cover page, but before the table of contents. I appreciate help in making this happen!

[rlesur]

As Thomas Vroylandt indicates on Twitter, this is related to the Pandoc template you use.

In the default template of pagedown::html_paged(), there is an undocumented abstract field that we can use to achieve your goal. Here is an Rmd file which explains the CSS declarations you must add to turn the abstract in a title verso:

---
title: Including a title verso
subtitle: A quick and dirty solution
output:
  pagedown::html_paged:
    toc: true
    self_contained: false
    css:
      - default-fonts
      - default-page
      - default 
      - abstract-as-page.css
abstract: | 
  # Main idea
  
  The `html_paged` format possesses an `abstract` field which can be used
  to include some content.
  
  ## Is markdown allowed in the abstract?
  
  **Of course!**
---

# CSS rules

By default, the abstract appears on the title page.
But we can add some CSS rules to make it appear on a single page.

We have to declare a page break before the abstract and remove the title "Abstract":

```{cat, engine.opts = list(file = 'abstract-as-page.css')}
/* put the abstract on its own page */
div.abstract {
  page-break-before: always;
}

/* remove the h3 title "Abstract" */
h3.abstract {
  display: none;
}
```

```{css, code=readLines('abstract-as-page.css'), eval=FALSE}
```

# Pros and cons

## Pros

You can keep the default template of `pagedown::html_paged()`.

## Cons

This is as a hack of the default template.

This solution isn't clean but it works well.

The other solution is to use a custom Pandoc template (17.3 Custom Pandoc templates | R Markdown: The Definitive Guide). If you want to make your own Pandoc template, you must start with the {pagedown} default template which is located here: pagedown/inst/resources/html/paged.html at main · rstudio/pagedown · GitHub (otherwise you will lose some pagedown's features).