Merge branch 'main' into favicon-update

NEWS.md

@@ -1,14 +1,16 @@
 # pkgdown (development version)
 
 * Links to favicons in page headers were updated to reflect changes to https://realfavicongenerator.net/ (#2804). Favicons should be re-generated by manually removing the `pkgdown/favicon` directory and then running `pkgdown::build_favicons()`.
+* The language of the site is set from the first `Language:` in the `DESCRIPTION` if it is available and no other language is specified (@jonthegeek, #2808).
 
 # pkgdown 2.1.1
 
-* Added keyboard shortcut, `/`, to focus search bar (#2423)
+* Added keyboard shortcut, `/`, to focus search bar (#2423).
 * The `BugReports` field can now be an email (@catalamarti, #2275).
 * New `clean_cache()` function removes the contents of the cache directory (#2718).
-* pkgdown now depends on R >= 4.0.0 (#2714)
-* Updated GitHub Actions advice and workflows around Quarto install (@tanho63, #2743)
+* pkgdown now depends on R >= 4.0.0 (#2714).
+* Updated GitHub Actions advice and workflows around Quarto install (@tanho63, #2743).
+* Support ANSI sequences in `index.md` (@krlmlr, #2787).
 
 # pkgdown 2.1.0
 

R/build-home.R

@@ -152,7 +152,7 @@
 #'
 #' ## Additional control via YAML
 #'
-#' You can control additinal aspects of the authors display via the `authors`
+#' You can control additional aspects of the authors display via the `authors`
 #' YAML field:
 #'
 #' * display of each author in the footer, sidebar and authors page,

R/build-quarto-articles.R

@@ -1,12 +1,5 @@
 build_quarto_articles <- function(pkg = ".", article = NULL, quiet = TRUE) {
   pkg <- as_pkgdown(pkg)
-  if (pkg$bs_version < 5) {
-    cli::cli_abort(c(
-      "Quarto articles require Bootstrap 5.",
-      "i" = "See details at {.url pkgdown.r-lib.org/articles/customise.html#getting-started}"),
-      call = NULL
-    )
-  }
 
   qmds <- pkg$vignettes[pkg$vignettes$type == "qmd", ]
   if (!is.null(article)) {
@@ -15,6 +8,13 @@ build_quarto_articles <- function(pkg = ".", article = NULL, quiet = TRUE) {
   if (nrow(qmds) == 0) {
     return()
   }
+  if (pkg$bs_version < 5) {
+    cli::cli_abort(c(
+      "Quarto articles require Bootstrap 5.",
+      "i" = "See details at {.url pkgdown.r-lib.org/articles/customise.html#getting-started}"),
+      call = NULL
+    )
+  }
   check_installed("quarto")
   if (quarto::quarto_version() < "1.5") {
     cli::cli_abort("Quarto articles require version 1.5 and above.", call = NULL)

R/build-reference-index.R

@@ -173,7 +173,10 @@ check_missing_topics <- function(rows, pkg, error_call = caller_env()) {
       pkg,
       c(
         "{sum(missing)} topic{?s} missing from index: {.val {pkg$topics$name[missing]}}.",
-        i = "Either use {.code @keywords internal} to drop from index, or"
+        i = paste(
+          "Either add to the reference index,",
+          "or use {.code @keywords internal} to drop from the index."
+        )
       ),
       call = error_call
     )

R/markdown.R

@@ -8,7 +8,7 @@ markdown_text <- function(pkg, text, ...) {
   markdown_path_html(pkg, md_path, ...)
 }
 
-markdown_text_inline <- function(pkg, 
+markdown_text_inline <- function(pkg,
                                  text,
                                  error_path,
                                  error_call = caller_env()) {
@@ -62,7 +62,7 @@ markdown_body <- function(pkg, path, strip_header = FALSE) {
 markdown_path_html <- function(pkg, path, strip_header = FALSE) {
   html_path <- withr::local_tempfile()
   convert_markdown_to_html(pkg, path, html_path)
-  xml <- xml2::read_html(html_path, encoding = "UTF-8")
+  xml <- read_html_keep_ansi(html_path)
   if (!inherits(xml, "xml_node")) {
     return(NULL)
   }

R/package.R

@@ -75,7 +75,7 @@ as_pkgdown <- function(pkg = ".", override = list()) {
   if (!is.null(pkg$meta$url)) {
     pkg$meta$url <- sub("/$", "", pkg$meta$url)
   }
-  
+
   pkg$development <- meta_development(pkg)
   pkg$prefix <- pkg$development$prefix
 
@@ -85,7 +85,7 @@ as_pkgdown <- function(pkg = ".", override = list()) {
     pkg$dst_path <- path(pkg$dst_path, pkg$development$destination)
   }
 
-  pkg$lang <- pkg$meta$lang %||% "en"
+  pkg$lang <- get_pkg_lang(pkg)
   pkg$install_metadata <- config_pluck_bool(pkg, "deploy.install_metadata", FALSE)
   pkg$figures <- meta_figures(pkg)
   pkg$repo <- package_repo(pkg)
@@ -106,6 +106,21 @@ read_desc <- function(path = ".") {
   desc::description$new(path)
 }
 
+get_pkg_lang <- function(pkg) {
+  if (!is.null(pkg$meta$lang)) {
+    return(pkg$meta$lang)
+  }
+
+  if (pkg$desc$has_fields("Language")) {
+    field <- pkg$desc$get_field("Language")
+    if (length(field) && nchar(field) > 0) {
+      return(regmatches(field, regexpr("[^,]+", field)))
+    }
+  }
+
+  return("en")
+}
+
 get_bootstrap_version <- function(pkg,
                                   template,
                                   template_package = NULL,
@@ -270,7 +285,7 @@ extract_lifecycle <- function(x) {
   fig <- extract_figure(desc)
 
   if (!is.null(fig) && length(fig) > 0 && length(fig[[1]]) > 0) {
-    path <- as.character(fig[[1]][[1]])  
+    path <- as.character(fig[[1]][[1]])
     if (grepl("lifecycle", path)) {
       name <- gsub("lifecycle-", "", path)
       name <- path_ext_remove(name)
@@ -351,12 +366,12 @@ article_metadata <- function(path) {
   if (path_ext(path) == "qmd") {
     inspect <- quarto::quarto_inspect(path)
     meta <- inspect$formats[[1]]$metadata
-  
+
     out <- list(
       title = meta$title %||% "UNKNOWN TITLE",
       desc = meta$description %||% NA_character_,
       ext = path_ext(inspect$formats[[1]]$pandoc$`output-file`) %||% "html"
-    )  
+    )
   } else {
     yaml <- rmarkdown::yaml_front_matter(path)
     out <- list(

R/render.R

@@ -163,7 +163,7 @@ check_open_graph <- function(pkg, og, file_path = NULL, call = caller_env()) {
   if (is.null(og)) {
     return()
   }
-  
+
   is_yaml <- is.null(file_path)
   base_path <- if (is_yaml) "template.opengraph" else "opengraph"
 
@@ -220,7 +220,7 @@ check_open_graph_list <- function(pkg,
   }
   not <- obj_type_friendly(x)
   config_abort(
-    pkg, 
+    pkg,
     "{.field {error_path}} must be a list, not {not}.",
     path = file_path,
     call = error_call
@@ -259,7 +259,7 @@ same_contents <- function(path, contents) {
 
   cur_contents <- paste0(read_lines(path), collapse = "\n")
   cur_hash <- digest::digest(cur_contents, serialize = FALSE)
-  
+
   identical(new_hash, cur_hash)
 }
 

R/tweak-page.R

@@ -51,7 +51,7 @@ tweak_rmarkdown_html <- function(html, input_path, pkg = list(bs_version = 3)) {
     img_src_real <- path_real(xml2::url_unescape(src[abs_src]))
     input_path_real <- path_real(xml2::url_unescape(input_path))
     img_rel_paths <- path_rel(path = img_src_real, start = input_path_real)
-    img_rel_paths <- xml2::url_escape(img_rel_paths)
+    img_rel_paths <- xml2::url_escape(img_rel_paths, reserved="/")
 
     purrr::walk2(
       .x = img_target_nodes,
@@ -96,14 +96,19 @@ tweak_useless_toc <- function(html) {
 
 # Update file on disk -----------------------------------------------------
 
-update_html <- function(path, tweak, ...) {
-
+read_html_keep_ansi <- function(path) {
   raw <- read_file(path)
   # Following the xml 1.0 spec, libxml2 drops low-bit ASCII characters
   # so we convert to \u2029, relying on downlit to convert back in
   # token_escape().
   raw <- gsub("\033", "\u2029", raw, fixed = TRUE)
-  html <- xml2::read_html(raw, encoding = "UTF-8")
+  # Use charToRaw() to always interpret as string,
+  # even for length 1 vectors
+  xml2::read_html(charToRaw(raw), encoding = "UTF-8")
+}
+
+update_html <- function(path, tweak, ...) {
+  html <- read_html_keep_ansi(path)
   tweak(html, ...)
 
   xml2::write_html(html, path, format = FALSE)

inst/BS5/assets/pkgdown.scss

@@ -3,15 +3,21 @@
 .row > main {
   // Ensure contents never become unreadably wide
   max-width: 50rem;
-
-  // And that we can break and hypenate very long words
-  overflow-wrap: break-word;
-  hyphens: auto;
 }
+
+// break and hypenate very long words on small screens
+@include media-breakpoint-down(md) {
+  .row > main {
+    overflow-wrap: break-word;
+    hyphens: auto;
+  }
+}
+
 // Put extra space between content and navbar
 @include media-breakpoint-only(xl) {
   .container .row { justify-content: space-evenly; }
 }
+
 // Boost font size and give big (but not infinite) margin on sidebar
 @include media-breakpoint-up(xxl) {
   body { font-size: 18px }

tests/testthat/_snaps/build-reference-index.md

@@ -57,7 +57,7 @@
     Condition
       Error:
       ! In _pkgdown.yml, 3 topics missing from index: "c", "e", and "?".
-      i Either use `@keywords internal` to drop from index, or
+      i Either add to the reference index, or use `@keywords internal` to drop from the index.
 
 # gives informative errors
 

tests/testthat/_snaps/check.md

@@ -26,7 +26,7 @@
       v Articles metadata ok.
       x Reference metadata not ok.
         In _pkgdown.yml, 1 topic missing from index: "?".
-        Either use `@keywords internal` to drop from index, or
+        Either add to the reference index, or use `@keywords internal` to drop from the index.
 
 # checks fails on first problem
 

tests/testthat/_snaps/init.md

@@ -13,18 +13,18 @@
       Updating deps/bootstrap-5.3.1/bootstrap.min.css
       Updating deps/bootstrap-toc-1.0.1/bootstrap-toc.min.js
       Updating deps/clipboard.js-2.0.11/clipboard.min.js
-      Updating deps/font-awesome-6.4.2/css/all.css
-      Updating deps/font-awesome-6.4.2/css/all.min.css
-      Updating deps/font-awesome-6.4.2/css/v4-shims.css
-      Updating deps/font-awesome-6.4.2/css/v4-shims.min.css
-      Updating deps/font-awesome-6.4.2/webfonts/fa-brands-400.ttf
-      Updating deps/font-awesome-6.4.2/webfonts/fa-brands-400.woff2
-      Updating deps/font-awesome-6.4.2/webfonts/fa-regular-400.ttf
-      Updating deps/font-awesome-6.4.2/webfonts/fa-regular-400.woff2
-      Updating deps/font-awesome-6.4.2/webfonts/fa-solid-900.ttf
-      Updating deps/font-awesome-6.4.2/webfonts/fa-solid-900.woff2
-      Updating deps/font-awesome-6.4.2/webfonts/fa-v4compatibility.ttf
-      Updating deps/font-awesome-6.4.2/webfonts/fa-v4compatibility.woff2
+      Updating deps/font-awesome-6.5.2/css/all.css
+      Updating deps/font-awesome-6.5.2/css/all.min.css
+      Updating deps/font-awesome-6.5.2/css/v4-shims.css
+      Updating deps/font-awesome-6.5.2/css/v4-shims.min.css
+      Updating deps/font-awesome-6.5.2/webfonts/fa-brands-400.ttf
+      Updating deps/font-awesome-6.5.2/webfonts/fa-brands-400.woff2
+      Updating deps/font-awesome-6.5.2/webfonts/fa-regular-400.ttf
+      Updating deps/font-awesome-6.5.2/webfonts/fa-regular-400.woff2
+      Updating deps/font-awesome-6.5.2/webfonts/fa-solid-900.ttf
+      Updating deps/font-awesome-6.5.2/webfonts/fa-solid-900.woff2
+      Updating deps/font-awesome-6.5.2/webfonts/fa-v4compatibility.ttf
+      Updating deps/font-awesome-6.5.2/webfonts/fa-v4compatibility.woff2
       Updating deps/headroom-0.11.0/headroom.min.js
       Updating deps/headroom-0.11.0/jQuery.headroom.min.js
       Updating deps/jquery-3.6.0/jquery-3.6.0.js

tests/testthat/_snaps/markdown.md

@@ -19,3 +19,12 @@
       Error in `config_math_rendering_()`:
       ! In _pkgdown.yml, template.math-rendering must be one of mathml, mathjax, and katex, not math.
 
+# preserves ANSI characters
+
+    Code
+      markdown_text(pkg, sprintf("prefer %s", cli::col_blue("a")))
+    Output
+      {html_document}
+      <html>
+      [1] <body><p>prefer \u2029[34ma\u2029[39m</p></body>
+

tests/testthat/assets/reference-language/one/DESCRIPTION

@@ -0,0 +1,7 @@
+Package: testpackage
+Version: 1.0.0
+Title: A test package
+Description: A test package
+Authors@R: person("Hadley Wickham")
+RoxygenNote: 7.3.1
+Language: fr

tests/testthat/assets/reference-language/two/DESCRIPTION

@@ -0,0 +1,7 @@
+Package: testpackage
+Version: 1.0.0
+Title: A test package
+Description: A test package
+Authors@R: person("Hadley Wickham")
+RoxygenNote: 7.3.1
+Language: en-US, fr

tests/testthat/test-build-home-index.R

@@ -156,7 +156,19 @@ test_that("cran_unquote works", {
 
 test_that("allow email in BugReports", {
   # currently desc throws a warning if BugReports is an email
-  pkg <- local_pkgdown_site(desc = list(BugReports = "[email protected]"))
+  pkg <- suppressWarnings(local_pkgdown_site(desc = list(BugReports = "[email protected]")))
   html <- xml2::read_html(data_home_sidebar(pkg))
   expect_snapshot(xpath_xml(html, ".//li/a"))
 })
+
+test_that("ANSI are handled", {
+  withr::local_options(cli.num_colors = 256)
+  pkg <- local_pkgdown_site()
+
+  pkg <- pkg_add_file(pkg, "index.md", sprintf("prefer %s", cli::col_blue("a")))
+  suppressMessages(build_home_index(pkg))
+
+  html <- xml2::read_html(path(pkg$dst_path, "index.html"))
+  readme_p <- xml2::xml_find_first(html, ".//main[@id='main']/p")
+  expect_equal(xml2::xml_text(readme_p), "prefer \u2029[34ma\u2029[39m")
+})

tests/testthat/test-markdown.R

@@ -63,3 +63,11 @@ test_that("validates math yaml", {
     config_math_rendering_(`math-rendering` = "math")
   })
 })
+
+test_that("preserves ANSI characters", {
+    withr::local_options(cli.num_colors = 256)
+    pkg <- local_pkgdown_site()
+    expect_snapshot(
+      markdown_text(pkg, sprintf("prefer %s", cli::col_blue("a")))
+    )
+})

tests/testthat/test-package.R

@@ -118,3 +118,32 @@ test_that("malformed figures fail gracefully", {
   expect_null(rd_lifecycle("{\\figure{deprecated.svg}}"))
   expect_null(rd_lifecycle("{\\figure{}}"))
 })
+
+# language ---------------------------------------------------------------------
+
+test_that("as_pkgdown sets language", {
+  # Default
+  pkg <- as_pkgdown(test_path("assets/reference"))
+  expect_equal(
+    pkg$lang,
+    "en"
+  )
+  # Single language specified in DESCRIPTION
+  pkg <- as_pkgdown(test_path("assets/reference-language/one"))
+  expect_equal(
+    pkg$lang,
+    "fr"
+  )
+  # Two languages specified in DESCRIPTION
+  pkg <- as_pkgdown(test_path("assets/reference-language/two"))
+  expect_equal(
+    pkg$lang,
+    "en-US"
+  )
+  # Language specified in _pkgdown.yml or override.
+  pkg <- as_pkgdown(test_path("assets/reference-language/two"), override = list(lang = "en-GB"))
+  expect_equal(
+    pkg$lang,
+    "en-GB"
+  )
+})