Add customization docs

NEWS.md

@@ -1,5 +1,7 @@
 # pkgdown (development version)
 
+* New "Customize your pkgdown website" vignette (#1573).
+
 * Added extension points to make HTML widgets (and RGL in particular) work
   in rendered examples (@dmurdoch).
 
@@ -12,6 +14,7 @@
   `override` parameter of `build_site()`. (#1499)
 
 * pkgdown now contains templates using Bootstrap 4 (with help from @jayhesselberth).
+   * Biggest differences with the Bootstrap 3 templates and assets: bigger default font size; darker links; the active item in tables of contents is highlighted by a grey background and bold font instead of a left border; in the changelog the release date is a sub-title under the version name.
    * Easy customisation of colours and fonts with bslib
    * Thoughtful typography to make the contents as easy as possible to read, regardless of the size of your device.
    * R syntax highlighting and autolinking by downlit is now paired with an [accessible colour scheme designed by Alison Hill](https://apreshill.github.io/rmda11y/arrow.html).

R/build.r

@@ -110,71 +110,8 @@
 #' `version_tooltip`.
 #'
 #' @section YAML config - navbar:
-#'
-#' By default, the top navigation bar (the "navbar") will contain links to:
-#'
-#' * "Get Started", if you have an article with the same name as the package
-#'   (e.g., `vignettes/pkgdown.Rmd`).
-#' * Reference
-#' * Articles (i.e., vignettes, if present).
-#' * News (if present).
-#' * An icon linking to the source repository (currently only GitHub and GitLab are supported)
-#'
-#' You can override (and even remove) these defaults with the  `navbar` field.
-#' It has two primary
-#' components: `structure` and `components`. These components interact in
-#' a somewhat complicated way, but the complexity allows you to make minor
-#' tweaks to part of the navbar while relying on pkgdown to automatically
-#' generate the rest.
-#'
-#' The `structure` defines the layout of the navbar, i.e. the order
-#' of the components, and whether they're right aligned or left aligned.
-#' You can use this component to change the order of the default components,
-#' remove some default components and add your own components.
-#'
-#' ```
-#' navbar:
-#'   structure:
-#'     left:  [intro, reference, articles, tutorials, news]
-#'     right: [github]
-#' ````
-#'
-#' The `components` describes the appearance of each element in the navbar.
-#' It uses the same
-#' syntax as [RMarkdown](https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html#site-navigation).
-#' The following YAML snippet illustrates some of the most important features.
-#'
-#' ```
-#' navbar:
-#'   components:
-#'     articles:
-#'      text: Articles
-#'      menu:
-#'      - text: Category A
-#'      - text: Title A1
-#'        href: articles/a1.html
-#'      - text: Title A2
-#'        href: articles/a2.html
-#'      - text: -------
-#'      - text: "Category B"
-#'      - text: Title B1
-#'        menu:
-#'        - text: "Sub-category B11"
-#'          href: articles/b11.html
-#'      twitter:
-#'        icon: "fab fa-twitter fa-lg"
-#'        href: https://twitter.com/hadleywickham
+#' ```{r child="man/rmd-fragments/navbar-configuration.Rmd"}
 #' ```
-#'
-#' Components can contain sub-`menu`s with headings (indicated by missing
-#' `href`) and separators (indicated by a bunch of `-`). You can also use
-#' `icon`s from [fontawesome](https://fontawesome.com/icons?d=gallery).
-#'
-#' This yaml would override the default "articles" component,
-#' and add a new "twitter" component. Unless you explicitly mention new
-#' components in the `structure` they'll be added to the far right of the
-#' left menu.
-#'
 #' @section YAML config - search:
 #' You can use [docsearch](https://community.algolia.com/docsearch/) by algolia
 #' to add search to your site.
@@ -205,8 +142,7 @@
 #'     bootswatch: cerulean
 #' ```
 #'
-#' See a complete list of themes and preview how they look at
-#' <https://gallery.shinyapps.io/117-shinythemes/>:
+#'  Refer to `vignette("customization", package = "pkgdown")`.
 #'
 #' Optionally provide the `ganalytics` template parameter to enable
 #' [Google Analytics](https://marketingplatform.google.com/about/analytics/).
@@ -323,29 +259,8 @@
 #'      install_metadata: true
 #'    ```
 #' @section YAML config - footer:
-#' By default, the footer is automatically populated with:
-#' * the names of the
-#' [authors `authors`](https://pkgdown.r-lib.org/reference/build_home.html#yaml-config-authors),
-#' on the left;
-#' * a reference to pkgdown `pkgdown`, on the right.
-#'
-#' The example below puts the authors information on the right together with
-#' a legal disclaimer, and puts pkgdown on the left.
-#' Unlike for the navbar or sidebar, components of the footer left/right are
-#' just pasted together into a string.
-#' If you want to use paragraphs, you need to use either HTML;
-#' or a YAML pipe and to start the components with two empty lines.
-#'
+#' ```{r child="man/rmd-fragments/footer-configuration.Rmd"}
 #' ```
-#' footer:
-#'   left:
-#'     structure: [pkgdown]
-#'   right:
-#'     structure: [authors, legal]
-#'     components:
-#'       legal: Provided without ***any warranty***.
-#' ```
-#'
 #' @section Options:
 #' Users with limited internet connectivity can disable CRAN checks by setting
 #' `options(pkgdown.internet = FALSE)`. This will also disable some features

R/utils.r

@@ -193,3 +193,7 @@ modify_list <- function(x, y) {
 
   utils::modifyList(x, y)
 }
+
+code_commas <- function(x) {
+  paste0("`", x, "`", collapse = ", ")
+}

man/rmd-fragments/footer-configuration.Rmd

@@ -0,0 +1,17 @@
+By default, the footer is automatically populated with:
+
+-   The names of the [authors `authors`](https://pkgdown.r-lib.org/reference/build_home.html#yaml-config-authors), on the left.
+-   A reference to pkgdown `pkgdown`, on the right.
+
+The example below puts the authors information on the right together with a legal disclaimer, and puts pkgdown on the left.
+
+    footer:
+     left:
+       structure: [pkgdown]
+     right:
+       structure: [authors, legal]
+       components:
+         legal: Provided without ***any warranty***.
+
+Like the navbar and side, you can control both the structure and the components.
+Unlike the navbar or sidebar, the components of the footer are just pasted together into a string that converted to HTML and insert in the document.