From 1ca166905f1b019ed4af9642617ea09fa2b8fc17 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Fri, 19 Feb 2021 18:15:38 +0100 Subject: [PATCH] Add footer flexibility & markdown for custom components (#1502) --- NEWS.md | 10 ++-- R/build-home-index.R | 49 ++++++----------- R/build-home.R | 5 +- R/build.r | 23 ++++++++ R/markdown.R | 11 ++++ R/render.r | 63 ++++++++++++++++++++++ R/utils.r | 30 +++++++++++ inst/templates/BS3/footer.html | 6 ++- man/build_home.Rd | 7 +-- man/build_site.Rd | 25 +++++++++ tests/testthat/_snaps/data_home_sidebar.md | 6 +-- tests/testthat/_snaps/pkgdown_footer.md | 44 +++++++++++++++ tests/testthat/test-data_home_sidebar.R | 8 +-- tests/testthat/test-pkgdown_footer.R | 40 ++++++++++++++ 14 files changed, 277 insertions(+), 50 deletions(-) create mode 100644 tests/testthat/_snaps/pkgdown_footer.md create mode 100644 tests/testthat/test-pkgdown_footer.R diff --git a/NEWS.md b/NEWS.md index 002e95fd7..336e7350b 100644 --- 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 `` tag; and before the closing tag `` (#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 index 257587461..74aadccab 100644 --- 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 index f52db04aa..93936e968 100644 --- 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 index 9e9a030ae..37c151270 100644 --- 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 index 24856a4ef..c8302f504 100644 --- 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 index 47bc24db2..a56e1c246 100644 --- 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("