rstudio · cpsievert · Apr 14, 2023 · Apr 5, 2023 · Apr 7, 2023 · Apr 11, 2023
diff --git a/.gitignore b/.gitignore
@@ -19,10 +19,6 @@ inst/yarn.lock
 
 inst/rmarkdown/templates/*/skeleton/skeleton.html
 
-vignettes/navbar-global
-vignettes/navbar-global-fillable
-vignettes/navbar-local-scroll
-vignettes/navbar-local-fill
-vignettes/page-scroll
-vignettes/page-fill
-vignettes/page-fill-double
+vignettes/*.html
+# rendered examples that appear in iframes
+vignettes/examples
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -90,13 +90,16 @@ Config/Needs/website:
     crosstalk,
     dplyr,
     DT,
+    ggplot2,
     glue,
     htmlwidgets,
     leaflet,
+    lorem,
     plotly,
     purrr,
     rprojroot,
     rstudio/htmltools,
+    scales,
     stringr,
     tidyr
 Config/Needs/deploy:

diff --git a/NEWS.md b/NEWS.md
@@ -45,7 +45,7 @@ Although `{bslib}` is still maturing, and will continue to receiving new UI feat
 
   * https://rstudio.github.io/bslib/articles/cards.html 
   * https://rstudio.github.io/bslib/articles/value-boxes.html 
-  * https://rstudio.github.io/bslib/articles/layouts.html 
+  * https://rstudio.github.io/bslib/articles/column-layout.html
 
 # bslib 0.4.1
 

diff --git a/README.Rmd b/README.Rmd
@@ -22,14 +22,14 @@ library(bslib)
 
 # bslib
 
-The `bslib` R package provides tools for customizing [Bootstrap themes](https://getbootstrap.com/docs/4.6/getting-started/theming/) directly from R, making it much easier to customize the appearance of [Shiny](https://shiny.rstudio.com/) apps & [R Markdown](https://rmarkdown.rstudio.com/) documents. `bslib`'s primary goals are:
+The `bslib` R package provides a modern UI toolkit for [Shiny](https://shiny.rstudio.com/) and [R Markdown](https://rmarkdown.rstudio.com/) based on [Bootstrap](https://getbootstrap.com/). `bslib`'s primary goals are:
 
+* Provide modern UI components, such as [cards](https://rstudio.github.io/bslib/articles/cards.html), [sidebars](https://rstudio.github.io/bslib/articles/sidebars.html), [value boxes](https://rstudio.github.io/bslib/articles/value-boxes.html), [layouts](https://rstudio.github.io/bslib/articles/column-layout.html), and more.
 * Make [custom theming](https://rstudio.github.io/bslib/articles/bslib.html#custom) as easy as possible.
   * Custom themes may even be created interactively in [real-time](https://rstudio.github.io/bslib/articles/bslib.html#real-time).
 * Also provide easy access to pre-packaged [Bootswatch themes](https://rstudio.github.io/bslib/articles/bslib.html#bootswatch).
-* Make [upgrading from Bootstrap 3 to 4 (and beyond)](https://rstudio.github.io/bslib/articles/bslib.html#versions) as seamless as possible.
-  * Shiny and R Markdown default to Bootstrap 3 and will continue to do so to avoid breaking legacy code.
-* Provide useful wrappers around modern Bootstrap (and CSS) components, such as [cards](https://rstudio.github.io/bslib/articles/cards.html), [value boxes](https://rstudio.github.io/bslib/articles/value-boxes.html), [layouts](https://rstudio.github.io/bslib/articles/layouts.html), and more.
+* Make it seamless to use any version of [Bootstrap](https://rstudio.github.io/bslib/articles/bslib.html#versions).
+  * Shiny and R Markdown currently default to Bootstrap 3 and may continue to do so to avoid breaking legacy code.
 * Serve as a general foundation for Shiny and R Markdown extension packages.
   * Extensions such as [`flexdashboard`](https://flexdashboard-pkg.netlify.app/articles/theme.html), [`pkgdown`](https://pkgdown.r-lib.org/dev/articles/customise.html), and [`bookdown`](https://pkgs.rstudio.com/bookdown/reference/bs4_book.html) already fully support [`bslib`'s custom theming capabilities](https://rstudio.github.io/bslib/articles/bslib.html#custom).
 
@@ -55,19 +55,32 @@ install.packages("rmarkdown")
 
 ## Basic usage {#usage}
 
-`bslib` is designed for use with any Shiny or R Markdown project that uses Bootstrap. In most cases, you can identify a project that uses Bootstrap when the relevant page constructor has a `theme` parameter. For example, most Shiny page layout functions (e.g., `shiny::navbarPage()`) and some popular R Markdown formats (e.g., `rmarkdown::html_document`) all have a `theme` parameter.
+### Shiny
 
-To use `bslib` in Shiny, provide a `bs_theme()` _object_ to the `theme` parameter; and in R Markdown, provide `bs_theme()` _parameters_ to `theme`. For example, here's a way to upgrade Shiny (left) and R Markdown (right) from Bootstrap 3 to 5:
+To get started using `bslib` in Shiny, use one of its `page_*()` functions. These drop-in replacements for `shiny::*Page()` updates the page to use the latest supported version Bootstrap. 
+
+```r
+ui <- page_fluid(
+  h2("Hello world")
+)
+shinyApp(ui, function(...) {})
+```
+
+In production, it's recommended to pin the version of Bootstrap (currently 5) via `bs_theme()`. As you'll learn in [getting started](https://rstudio.github.io/bslib/articles/bslib.html), `bs_theme()` also makes it easy to theme the app by customizing (and/or adding to) Bootstrap CSS. 
 
-<div class="usage">
 ```r
 library(shiny)
-ui <- navbarPage(
+ui <- page_fixed(
   theme = bs_theme(version = 5),
-  ...
+  h2("Hello world")
 )
 shinyApp(ui, function(...) {})
 ```
+
+### R Markdown
+
+To get started using `bslib` in R Markdown (and compatible extensions like [`flexdashboard`](https://flexdashboard-pkg.netlify.app/articles/theme.html)), provide `bs_theme()` parameters to the `theme` parameter of the output format. For example, here's how to use "stock" Bootstrap 5 with `rmarkdown::html_document`:
+
 ```r
 ---
 output:
@@ -76,16 +89,18 @@ output:
       version: 5
 ---
 ```
-</div>
-
-See the [Get Started](https://rstudio.github.io/bslib/articles/bslib.html) article to learn more about Bootstrap versions, pre-packaged Bootswatch themes, (real-time) custom theming, and more.
 
-To get started more quickly, choose a relevant R Markdown template from inside RStudio by going to File -> New File -> R Markdown -> From Template:
+`bslib` also provides some R Markdown templates that can be accessed from RStudio by going to File -> New File -> R Markdown -> From Template:
 
 ```{r, echo = FALSE, out.width="60%"}
 knitr::include_graphics("man/figures/rstudio-templates.png")
 ```
 
+### pkgdown
+
+`{pkgdown}` has its way of using `bslib`, see <https://pkgdown.r-lib.org/articles/customise.html>
+
+
 ## Getting help
 
 There are two main places to get help with `bslib`:

diff --git a/README.md b/README.md
@@ -12,31 +12,29 @@ status](https://github.com/rstudio/bslib/actions/workflows/R-CMD-check.yaml/badg
 
 # bslib
 
-The `bslib` R package provides tools for customizing [Bootstrap
-themes](https://getbootstrap.com/docs/4.6/getting-started/theming/)
-directly from R, making it much easier to customize the appearance of
-[Shiny](https://shiny.rstudio.com/) apps & [R
-Markdown](https://rmarkdown.rstudio.com/) documents. `bslib`’s primary
-goals are:
-
+The `bslib` R package provides a modern UI toolkit for
+[Shiny](https://shiny.rstudio.com/) and [R
+Markdown](https://rmarkdown.rstudio.com/) based on
+[Bootstrap](https://getbootstrap.com/). `bslib`’s primary goals are:
+
+  - Provide modern UI components, such as
+    [cards](https://rstudio.github.io/bslib/articles/cards.html),
+    [sidebars](https://rstudio.github.io/bslib/articles/sidebars.html),
+    [value
+    boxes](https://rstudio.github.io/bslib/articles/value-boxes.html),
+    [layouts](https://rstudio.github.io/bslib/articles/column-layout.html),
+    and more.
   - Make [custom
     theming](https://rstudio.github.io/bslib/articles/bslib.html#custom)
     as easy as possible.
       - Custom themes may even be created interactively in
         [real-time](https://rstudio.github.io/bslib/articles/bslib.html#real-time).
   - Also provide easy access to pre-packaged [Bootswatch
     themes](https://rstudio.github.io/bslib/articles/bslib.html#bootswatch).
-  - Make [upgrading from Bootstrap 3 to 4 (and
-    beyond)](https://rstudio.github.io/bslib/articles/bslib.html#versions)
-    as seamless as possible.
-      - Shiny and R Markdown default to Bootstrap 3 and will continue to
-        do so to avoid breaking legacy code.
-  - Provide useful wrappers around modern Bootstrap (and CSS)
-    components, such as
-    [cards](https://rstudio.github.io/bslib/articles/cards.html), [value
-    boxes](https://rstudio.github.io/bslib/articles/value-boxes.html),
-    [layouts](https://rstudio.github.io/bslib/articles/layouts.html),
-    and more.
+  - Make it seamless to use any version of
+    [Bootstrap](https://rstudio.github.io/bslib/articles/bslib.html#versions).
+      - Shiny and R Markdown currently default to Bootstrap 3 and may
+        continue to do so to avoid breaking legacy code.
   - Serve as a general foundation for Shiny and R Markdown extension
     packages.
       - Extensions such as
@@ -69,29 +67,43 @@ install.packages("rmarkdown")
 
 ## Basic usage
 
-`bslib` is designed for use with any Shiny or R Markdown project that
-uses Bootstrap. In most cases, you can identify a project that uses
-Bootstrap when the relevant page constructor has a `theme` parameter.
-For example, most Shiny page layout functions (e.g.,
-`shiny::navbarPage()`) and some popular R Markdown formats (e.g.,
-`rmarkdown::html_document`) all have a `theme` parameter.
+### Shiny
+
+To get started using `bslib` in Shiny, use one of its `page_*()`
+functions. These drop-in replacements for `shiny::*Page()` updates the
+page to use the latest supported version Bootstrap.
 
-To use `bslib` in Shiny, provide a `bs_theme()` *object* to the `theme`
-parameter; and in R Markdown, provide `bs_theme()` *parameters* to
-`theme`. For example, here’s a way to upgrade Shiny (left) and R
-Markdown (right) from Bootstrap 3 to 5:
+``` r
+ui <- page_fluid(
+  h2("Hello world")
+)
+shinyApp(ui, function(...) {})
+```
 
-<div class="usage">
+In production, it’s recommended to pin the version of Bootstrap
+(currently 5) via `bs_theme()`. As you’ll learn in [getting
+started](https://rstudio.github.io/bslib/articles/bslib.html),
+`bs_theme()` also makes it easy to theme the app by customizing (and/or
+adding to) Bootstrap CSS.
 
 ``` r
 library(shiny)
-ui <- navbarPage(
+ui <- page_fixed(
   theme = bs_theme(version = 5),
-  ...
+  h2("Hello world")
 )
 shinyApp(ui, function(...) {})
 ```
 
+### R Markdown
+
+To get started using `bslib` in R Markdown (and compatible extensions
+like
+[`flexdashboard`](https://flexdashboard-pkg.netlify.app/articles/theme.html)),
+provide `bs_theme()` parameters to the `theme` parameter of the output
+format. For example, here’s how to use “stock” Bootstrap 5 with
+`rmarkdown::html_document`:
+
 ``` r
 ---
 output:
@@ -101,19 +113,17 @@ output:
 ---
 ```
 
-</div>
-
-See the [Get
-Started](https://rstudio.github.io/bslib/articles/bslib.html) article to
-learn more about Bootstrap versions, pre-packaged Bootswatch themes,
-(real-time) custom theming, and more.
-
-To get started more quickly, choose a relevant R Markdown template from
-inside RStudio by going to File -\> New File -\> R Markdown -\> From
+`bslib` also provides some R Markdown templates that can be accessed
+from RStudio by going to File -\> New File -\> R Markdown -\> From
 Template:
 
 <img src="man/figures/rstudio-templates.png" width="60%" style="display: block; margin: auto;" />
 
+### pkgdown
+
+`{pkgdown}` has its way of using `bslib`, see
+<https://pkgdown.r-lib.org/articles/customise.html>
+
 ## Getting help
 
 There are two main places to get help with `bslib`:

diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -10,7 +10,7 @@ template:
   bslib:
     info: "#E6F2FD"
     base_font:
-      google: "Atkinson Hyperlegible"
+      google: {family: "Atkinson Hyperlegible", wght: [300, 400, 700], ital: [0, 1]}
     headings-color: "#206B72"
     link-color: "#216B73"
     link-decoration: underline var(--bs-info) dotted
@@ -24,29 +24,38 @@ navbar:
   bg: info
   type: light
   structure:
-    left:  [intro, articles, integration]
+    left:  [intro, theming, components, layouts]
     right: [reference, news, github]
   components:
     home: ~
-    articles:
-      text: Articles
+    theming:
+      text: Theming
       menu:
-        #- text: Why Sass over CSS?
-        #  href: articles/why-sass.html
-        - text: Cards
-          href: articles/cards.html
-        - text: Value Boxes
-          href: articles/value-boxes.html
-        - text: Sidebars
-          href: articles/sidebars.html
-        - text: Layouts
-          href: articles/layouts.html
         - text: Theming variables
           href: articles/bs5-variables.html
         - text: Utility Classes
           href: articles/utility-classes.html
         - text: Custom components
           href: articles/custom-components.html
+    components:
+      text: Components
+      menu:
+        - text: Cards
+          href: articles/cards.html
+        - text: Sidebars
+          href: articles/sidebars.html
+        - text: Value Boxes
+          href: articles/value-boxes.html
+    layouts:
+      text: Layouts
+      menu:
+        - text: Column-based layout
+          href: articles/column-layout.html
+        - text: Filling layouts
+          href: articles/filling.html
+        - text: Multi page/tab
+          href: https://rstudio.github.io/bslib/reference/navs.html#details
+
     reference:
       text: Reference
       href: reference/index.html
@@ -131,3 +140,10 @@ reference:
     - theme_bootswatch
     - bootswatch_themes
     - version_default
+
+
+  redirects:
+    - ["articles/cards.html#fixed-sizing", "articles/cards.html#scrolling-contents"]
+    - ["articles/cards.html#responsive-sizing", "articles/cards.html#filling-contents"]
+    - ["articles/cards.html#fixed-responsive-sizing", "articles/cards.html#scrolling-filling"]
+    - ["articles/cards.html#dynamic-rendering-shiny", "articles/cards.html#shiny"]
diff --git a/pkgdown/extra.css b/pkgdown/extra.css
@@ -23,3 +23,68 @@ a:focus, a:hover {
 table.dataTable.table-bordered {
   border-collapse: collapse !important;
 }
+
+main h2 {
+  margin-top: 1lh;
+}
+
+.html-widget {
+  margin-bottom: 0;
+}
+
+/* ---- Callouts ---- */
+.callout {
+  position: relative;
+  border: 1px solid gray;
+  padding: 1rem;
+  margin: 1rem 0;
+  border-radius: var(--bs-border-radius);
+}
+
+.callout > :last-child {
+  margin-bottom: 0;
+}
+
+.callout > h3 {
+  position: relative;
+  margin: -1rem;
+  margin-bottom: 10px;
+  padding: 1rem;
+  font-size: 1.5rem;
+  border-top-left-radius: inherit;
+  border-top-right-radius: inherit;
+}
+
+.callout > h3 > .anchor {
+  display: none;
+}
+
+.callout.callout-warning {
+  border-color: gold
+}
+
+.callout.callout-warning > h3 {
+  color: #473D00;
+  background-color: hsl(51 100% 94% / 1);
+}
+
+.callout.callout-warning > h3:before {
+  /* https://icons.getbootstrap.com/icons/exclamation-diamond-fill/ */
+  content: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16px' height='16px' fill='%23473D00' class='bi bi-exclamation-diamond-fill' viewBox='0 0 16 16'%3E%3Cpath d='M9.05.435c-.58-.58-1.52-.58-2.1 0L.436 6.95c-.58.58-.58 1.519 0 2.098l6.516 6.516c.58.58 1.519.58 2.098 0l6.516-6.516c.58-.58.58-1.519 0-2.098L9.05.435zM8 4c.535 0 .954.462.9.995l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 4.995A.905.905 0 0 1 8 4zm.002 6a1 1 0 1 1 0 2 1 1 0 0 1 0-2z'/%3E%3C/svg%3E");
+  margin-right: 4px
+}
+
+.callout.callout-note {
+  border-color: #bdccdc;
+}
+
+.callout.callout-note > h3 {
+  color: #373a3c;
+  background-color: #e9f2fc;
+}
+
+.callout.callout-note > h3:before {
+  /* https://icons.getbootstrap.com/icons/info-circle/ */
+  content: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16px' height='16px' fill='%232780e3' class='bi bi-exclamation-diamond-fill' viewBox='0 0 16 16'%3E%3Cpath d='M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16zm.93-9.412-1 4.705c-.07.34.029.533.304.533.194 0 .487-.07.686-.246l-.088.416c-.287.346-.92.598-1.465.598-.703 0-1.002-.422-.808-1.319l.738-3.468c.064-.293.006-.399-.287-.47l-.451-.081.082-.381 2.29-.287zM8 5.5a1 1 0 1 1 0-2 1 1 0 0 1 0 2z'/%3E%3C/svg%3E");
+  margin-right: 4px
+}