Add footer flexibility & markdown for custom components (#1502)

r-lib · Feb 19, 2021 · 1ca1669 · 1ca1669
1 parent d49c3e8
commit 1ca1669
Show file tree

Hide file tree

Showing 14 changed files with 277 additions and 50 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -1,5 +1,9 @@
 # pkgdown (development version)
 
+* Make footer specification more flexible: users can now
+    * change the placement of elements on the left and right
+    * add text to the left and right (or even remove/replace default text)
+  (#1502)
 * pkgdown now recognizes GitLab URLs to the source repository and adds the corresponding icon
   to the navbar (#1493). 
 
@@ -18,10 +22,10 @@ right below the opening `<body>` tag; and before the closing tag `</body>` (#148
 
 * Make sidebar specification more flexible: users can now
     * change the order of sidebar elements
+    * add custom sidebar sections (title, text that can be Markdown or HTML)
     * add a table of contents for the README
-    * add custom sidebar sections (title, text that has to be HTML)
-    * completely suppress the navbar (even "Dev status")
-    * provide their own HTML for the navbar. (#1443, #1488)
+    * completely suppress the sidebar (even "Dev status")
+    * provide their own HTML for the navbar. (#1443, #1488, #1502)
 
 
 * Protect the rules drawn by the CLI (as for example, in `build_site()`) against

diff --git a/R/build-home-index.R b/R/build-home-index.R
@@ -101,26 +101,12 @@ data_home_sidebar <- function(pkg = ".") {
       set_names(names(components))
   )
 
-  missing <- setdiff(sidebar_structure, names(sidebar_components))
-
-  if (length(missing) > 0) {
-    missing_components <- lapply(
-      missing, append,
-      c("home", "sidebar", "components"),
-      after = 0
-    )
-    missing_fields <- pkgdown_fields(pkg = pkg, fields = missing_components)
-
-    abort(
-      sprintf(
-        "Can't find component%s %s.",
-        if (length(missing) > 1) "s" else "",
-        paste0(
-          missing_fields, collapse = " nor "
-        )
-      )
-    )
-  }
+  check_components(
+    needed = sidebar_structure,
+    present = names(sidebar_components),
+    where = c("home", "sidebar", "components"),
+    pkg = pkg
+  )
 
   sidebar_final_components <- purrr::compact(
     sidebar_components[sidebar_structure]
@@ -136,20 +122,17 @@ default_sidebar_structure <- function() {
 
 data_home_component <- function(component, component_name, pkg) {
 
-  if (!all(c("title", "html") %in% names(component))) {
-    abort(
-      sprintf(
-        "Can't find %s for the component %s",
-        paste0(
-          c("title", "html")[!c("title", "html") %in% names(component)],
-          collapse = " nor "
-          ),
-        pkgdown_field(pkg = pkg, "home", "sidebar", "components", component_name)
-        )
-      )
-  }
+  check_components(
+    needed = c("title", "text"),
+    present = names(component),
+    where = c("home", "sidebar", "components", component_name),
+    pkg = pkg
+  )
 
-  sidebar_section(component$title, bullets = component$html)
+  sidebar_section(
+    component$title,
+    bullets = markdown_text2(component$text, pkg = pkg)
+  )
 }
 
 data_home_sidebar_links <- function(pkg = ".") {

diff --git a/R/build-home.R b/R/build-home.R
@@ -126,8 +126,9 @@
 #' `authors`, `dev` (badges); you can add a README table of contents `toc`,
 #' you can add custom components.
 #' The example below creates a sidebar whose only components will be the
-#' authors section, a custom section, a table of contents for the README,
+#' authors section, a custom section, a table of contents for the README
 #' and a Dev Status section if there are badges.
+#' The `text` will be treated as Markdown.
 #'
 #' ```
 #' home:
@@ -136,7 +137,7 @@
 #'     components:
 #'       custom:
 #'         title: Funding
-#'         html: We are grateful for funding!
+#'         text: We are *grateful* for funding!
 #' ```
 #'
 #' You can provide a ready-made sidebar HTML:

diff --git a/R/build.r b/R/build.r
@@ -310,6 +310,29 @@
 #'    deploy:
 #'      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.
+#'
+#' ```
+#' 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

diff --git a/R/markdown.R b/R/markdown.R
@@ -69,3 +69,14 @@ markdown_text <- function(text, pkg = pkg, ...) {
   write_lines(text, path = tmp)
   markdown(tmp, ..., pkg = pkg)
 }
+
+
+markdown_text2 <- function(text, pkg, ...) {
+  html <- markdown_text(text, pkg = pkg, ...)
+  html %>%
+    xml2::read_html() %>%
+    xml2::xml_child() %>% # body
+    xml2::xml_children() %>% # p
+    as.character() %>%
+    paste(collapse = "")
+}
diff --git a/R/render.r b/R/render.r
@@ -40,6 +40,8 @@ render_page <- function(pkg = ".", name, data, path = "", depth = NULL, quiet =
     data$site$root <- paste0(pkg$meta$url, "/")
   }
 
+  data$footer <- pkgdown_footer(data, pkg)
+
   # render template components
   pieces <- c(
     "head", "navbar", "header", "content", "docsearch", "footer",
@@ -301,3 +303,64 @@ check_made_by <- function(first) {
   if (length(first) == 0L) return(FALSE)
   grepl("<!-- Generated by pkgdown", first, fixed = TRUE)
 }
+
+pkgdown_footer <- function(data, pkg) {
+
+  footer_components <- list(
+    authors = footer_authors(data),
+    pkgdown = footer_pkgdown(data)
+  )
+
+  # footer left
+  left_structure <- pkg$meta$footer$left$structure %||% c("authors")
+
+  left_components <- modify_list(
+    footer_components,
+    pkg$meta$footer$left$components
+  )
+
+  check_components(
+    needed = left_structure,
+    present = names(left_components),
+    where = c("footer", "left", "components"),
+    pkg = pkg
+  )
+
+  left_final_components <- markdown_text2(
+    paste0(left_components[left_structure], collapse = " "),
+    pkg = pkg
+  )
+
+  # footer right
+  right_structure <- pkg$meta$footer$right$structure %||% c("pkgdown")
+
+  right_components <- modify_list(
+    footer_components,
+    pkg$meta$footer$right$components
+  )
+
+  check_components(
+    needed = right_structure,
+    present = names(right_components),
+    where = c("footer", "right", "components"),
+    pkg = pkg
+  )
+
+  right_final_components <- markdown_text2(
+    paste0(right_components[right_structure], collapse = " "),
+    pkg = pkg
+  )
+
+  list(left = left_final_components, right = right_final_components)
+}
+
+footer_authors <- function(data) {
+  paste0("Developed by ", data$package$authors, ".")
+}
+
+footer_pkgdown <- function(data) {
+  paste0(
+    'Site built with <a href="https://pkgdown.r-lib.org/">pkgdown</a> ',
+    data$pkgdown$version, "."
+  )
+}
diff --git a/R/utils.r b/R/utils.r
@@ -130,6 +130,29 @@ pkgdown_fields <- function(pkg, fields) {
   pkgdown_field(pkg, fields)
 }
 
+check_components <- function(needed, present, where, pkg) {
+  missing <- setdiff(needed, present)
+
+  if (length(missing) == 0) {
+    return()
+  }
+
+  missing_components <- lapply(
+      missing, append,
+      where,
+      after = 0
+    )
+    missing_fields <- pkgdown_fields(pkg = pkg, fields = missing_components)
+
+    abort(
+      paste0(
+        "Can't find component", if (length(missing) > 1) "s", " ",
+        paste0(missing_fields, collapse = " or "),
+        "."
+      )
+    )
+}
+
 #' @export
 print.print_yaml <- function(x, ...) {
   cat(yaml::as.yaml(x), "\n", sep = "")
@@ -162,3 +185,10 @@ show_xml <- function(x) {
 isFALSE <- function(x) {
   is.logical(x) && length(x) == 1L && !is.na(x) && !x
 }
+
+modify_list <- function(x, y) {
+  if (is.null(y)) {
+    return(x)
+  }
+  utils::modifyList(x, y)
+}
diff --git a/inst/templates/BS3/footer.html b/inst/templates/BS3/footer.html
@@ -1,7 +1,9 @@
+{{#footer}}
 <div class="copyright">
-  <p>{{#package}}Developed by {{{authors}}}.{{/package}}</p>
+  <p>{{#left}}{{{.}}}{{/left}}</p>
 </div>
 
 <div class="pkgdown">
-  <p>Site built with <a href="https://pkgdown.r-lib.org/">pkgdown</a> {{#pkgdown}}{{version}}{{/pkgdown}}.</p>
+  <p>{{#right}}{{{.}}}{{/right}}</p>
 </div>
+{{/footer}}
diff --git a/man/build_home.Rd b/man/build_home.Rd
diff --git a/man/build_site.Rd b/man/build_site.Rd
diff --git a/tests/testthat/_snaps/data_home_sidebar.md b/tests/testthat/_snaps/data_home_sidebar.md
@@ -40,7 +40,7 @@
       {html_node}
       <div class="fancy-section">
       [1] <h2 data-toc-skip>Fancy section</h2>
-      [2] <ul class="list-unstyled">\n<li>How cool is pkgdown?!</li>\n</ul>
+      [2] <ul class="list-unstyled">\n<li><p>How <em>cool</em> is pkgdown?!</p></li ...
 
 # data_home_sidebar() can add a README
 
@@ -62,9 +62,9 @@
 
 ---
 
-    Can't find title for the component home.sidebar.components.fancy in '_pkgdown.yml'
+    Can't find component home.sidebar.components.fancy.title in '_pkgdown.yml'.
 
 ---
 
-    Can't find title nor html for the component home.sidebar.components.fancy in '_pkgdown.yml'
+    Can't find components home.sidebar.components.fancy.title, home.sidebar.components.fancy.text in '_pkgdown.yml'.
 
diff --git a/tests/testthat/_snaps/pkgdown_footer.md b/tests/testthat/_snaps/pkgdown_footer.md
@@ -0,0 +1,44 @@
+# pkgdown_footer() works by default
+
+    Code
+      pkgdown_footer(data, pkg)
+    Output
+      $left
+      [1] "<p>Developed by bla.</p>"
+      
+      $right
+      [1] "<p>Site built with <a href=\"https://pkgdown.r-lib.org/\" class=\"external-link\">pkgdown</a> 42.</p>"
+      
+
+# pkgdown_footer() can use custom components
+
+    Code
+      pkgdown_footer(data, pkg)
+    Output
+      $left
+      [1] "<p>Developed by bla. <strong><em>Wow</em></strong></p>"
+      
+      $right
+      [1] "<p>Site built with <a href=\"https://pkgdown.r-lib.org/\" class=\"external-link\">pkgdown</a> 42.</p>"
+      
+
+---
+
+    Code
+      pkgdown_footer(data, pkg)
+    Output
+      $left
+      [1] "<p><strong><em>Wow</em></strong></p>"
+      
+      $right
+      [1] "<p>Site built with <a href=\"https://pkgdown.r-lib.org/\" class=\"external-link\">pkgdown</a> 42.</p>"
+      
+
+# pkgdown_footer() throws informative error messages
+
+    Can't find component footer.left.components.pof in '_pkgdown.yml'.
+
+---
+
+    Can't find component footer.right.components.bof in '_pkgdown.yml'.
+