Add Bootstrap 4 support

[cpsievert]

This PR has been merged. If you want to test this feature, please install the dev version of rmarkdown:

remotes::install_github('rstudio/rmarkdown')

---

This PR allows the theme parameter of html_document() (and html_document_base()) to understand bslib::bs_theme() objects, meaning that you can opt-in to Bootstrap 4 this way (Closes #1260):

html_document:
  theme: !expr bslib::bs_theme(version = 4)

Moreover, if theme is a list of values, those values are now implicitly supplied to bs_theme(), meaning this an equivalent way to opt-into Bootstrap 4.

html_document:
  theme: 
    version: 4

Note that, with bs_theme(), you can use any Bootswatch 4 (or 3) theme:

html_document:
  theme: 
    version: 4
    bootswatch: minty

Or, implement your own custom theme (this one inspired by Material's dark mode suggestions).

html_document:
  theme: 
      bg: "#121212"
      fg: "#E4E4E4"
      primary: "#EA80FC"
      secondary: "#00DAC6"
      base_font: !expr bslib::font_google("Open Sans")
      heading_font: !expr bslib::font_google("Proza Libre")
      code_font: !expr bslib::font_google("Fira Code")
      code-color: "#00DAC6"

This PR also adds integration with bslib::bs_themer() allowing runtime: shiny documents to be interactively themed.

---
runtime: shiny
output:
  html_document:
    theme: 
      version: 4
---

```{r}
bslib::bs_themer()
```

Lastly, if you want to supply custom Sass rules that utilize the underlying theme's Sass, you can now supply .scss/.sass files to the css parameter and those Sass files will be compiled with the theme. For example, say you want to define a new class that extends a group of BS4 utility classes to add padding and border around tabsets:

.with-border {
  @extend .p-3; @extend .border; @extend .border-top-0; @extend .rounded-bottom;
}

---
output:
  html_document:
    theme: 
      version: 4
    css: with-border.scss
---

# Tabs! {.tabset}

## Summary {.with-border}

Here is a summary table.

```{r}
summary(cars)
```

## Plot {.with-border}

Here is a plot:

```{r echo=FALSE}
plot(pressure)
```

[cpsievert]

Thanks for the great feedback @cderv, 7982cb6 should address the Suggestion issue. It also centralizes theme value checking and adds some new additional error messages if the theme value is something we don't support.

As for html_dependency_bootstrap()'s type safety -- I agree that ideally we should always return a list of dependencies, but I'm pretty concerned about the implications for existing code -- there are about 10-15 packages on CRAN that would need to be updated and probably lots of non-CRAN projects that would break. @yihui, do you feel this is a breaking change worth taking on?

[cderv]

That is what I thought about the breaking change. This is the type of things we would like to change (fix) but we can't really as it comes with a cost. 😞

Last thing I feel is missing is that this PR won't help improve code coverage 😅
Some of the helper could benefit some simple test. rmarkdown is not the package with the more unit test but I hope to improve that soon. So no need to rush, I can do it later. I believe you have tested this PR with a lot of examples throughout the year of work on this one.

Thanks for the work on this, this is a great feature !

[cpsievert]

Thanks! Keep in mind that I'll be giving our QA team a handful of examples to do manual testing with, and I'll likely also be adding some automated tests to https://github.com/rstudio/shinycoreci-apps

[cderv]

Oh nice! I was not aware of (forgot 🙄 ) that! That is great !

[yihui]

Thanks! It looks good to me overall! I just hope bslib could get on CRAN soon.

do you feel this is a breaking change worth taking on?

No, let's just keep the current behavior of html_dependency_bootstrap(). We could export bootstrap_dependencies() if any other package authors want to use a function that always returns a list of dependencies. If we are going to export it, I'd probably rename it to something like html_dependency_bstheme() for consistency with other html_dependency_*() functions.

[cpsievert]

I just hope bslib could get on CRAN soon.

Don't we all 😅.

We could export bootstrap_dependencies() if any other package authors want to use a function that always returns a list of dependencies.

It seems a better (near-term) option would be to label html_dependency_bootstrap() as superseded and point to bslib::bs_theme_dependencies(), but it seems fine to do nothing for now until the sass/bslib stack matures more. In the longer term, we could also consider completely replacing html_dependency_bootstrap() with bslib::bs_theme_dependencies() (and remove the Bootstrap asset files from rmarkdown)

[cpsievert]

Also, are y'all totally against bumping to 2.7.0 to signify this fairly significant feature (I've been using 2.7.0 to signal messages in {thematic} and {bslib})?

[yihui]

In the longer term, we could also consider completely replacing html_dependency_bootstrap() with bslib::bs_theme_dependencies() (and remove the Bootstrap asset files from rmarkdown)

That sounds good to me.

Also, are y'all totally against bumping to 2.7.0 to signify this fairly significant feature

The next CRAN release will be v2.7. We bump z in x.y.z when we introduce changes in the dev version, and bump y (or x for really significant changes) when making CRAN releases.

[cpsievert]

Ah, ok, I changed the version to 2.6.6, feel free to merge (I can't)

[cderv]

@cpsievert was this change necessary for bslib and bootstrap 4 supports ?

Asking because it changes some layout for some custom format based on html_document().
For example: Bioconductor/BiocStyle#86 (see both doc examples paragraph width)

it is a small difference but I am wondering if this could impact other custom formats. So asking for your knowledge on this row vs row-fluid.

Thanks.

[cpsievert]

.row-fluid is a Bootstrap 2 class that changed to .row in Bootstrap 3 https://getbootstrap.com/docs/3.4/migration/

[cderv]

Thanks. I understand now.
This means that about the paragraph width change, this is because html_document was using an old class and no bootstrap CSS was used. Switching to BS3 row-fluid class makes this CSS rule to apply

.row {
    margin-right: -15px;
    margin-left: -15px;
}

this lead to a change in style for all html_document output.

A side effect of this PR. Glad I know about that now. I may document that in NEWS maybe.