Merge branch 'main' into reference-title

DESCRIPTION

@@ -34,7 +34,7 @@ Imports:
     purrr (>= 1.0.0),
     ragg,
     rlang (>= 1.1.0),
-    rmarkdown (>= 1.1.9007),
+    rmarkdown (>= 2.26.2),
     tibble,
     whisker,
     withr (>= 2.4.3),
@@ -45,10 +45,12 @@ Suggests:
     diffviewer,
     evaluate,
     gert,
+    gt,
     htmltools,
     htmlwidgets,
     knitr,
     lifecycle,
+    magick,
     methods,
     openssl,
     pkgload (>= 1.0.2),
@@ -70,3 +72,5 @@ Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.1
 SystemRequirements: pandoc
+Remotes:  
+    rstudio/rmarkdown

NAMESPACE

@@ -89,6 +89,7 @@ S3method(as_html,tag_url)
 S3method(as_html,tag_var)
 S3method(as_html,tag_verb)
 S3method(pkgdown_print,default)
+S3method(pkgdown_print,gt_tbl)
 S3method(pkgdown_print,htmlwidget)
 S3method(print,pkgdown_xml)
 S3method(print,print_yaml)
@@ -116,6 +117,7 @@ export(build_favicons)
 export(build_home)
 export(build_home_index)
 export(build_news)
+export(build_redirects)
 export(build_reference)
 export(build_reference_index)
 export(build_search)

NEWS.md

@@ -1,6 +1,19 @@
 # pkgdown (development version)
 
 * The title for the "Reference" page is now "Package index" since this page might contain more than just function details (#2181).
+* `build_redirects()` now automatically adds redirects for topic 
+aliases. This matches the behaviour of `?` and will help keep links stable in the long term (#1876).
+* `build_redirects()` now reports which redirects it is generating.
+* The addin now runs `build_site()` instead of `build_site_external()`, which generally should be more reliable (#2252).
+* Anchors are displayed when they're the target of a link.
+* `build_reference()` adds anchors to arguments making it possible to link directly to an argument, if desired. A subtle visual treatment makes it easy to see which argument is targeted (#2228).
+* `build_redirects()` is now exported to make it easier to document (#2500).
+* `build_reference()` now automatically renders any tables created by gt (#2326).
+* `build_articles()` now drops a section called "internal". This allows you to have articles that either aren't indexed at all or are included manually elsewhere in the navbar (#2205).
+* `as.pkgdown()` will no longer prompt you to install a missing template package from CRAN, since these are almost always found in GitHub (#2076).
+* `init_site()` once again describes one copy per line, and now uses a better prefix when copying assets from pkgdown itself (#2445).
+* Very wide words are now automatically broken across lines and hyphenated (when possible) when they'd otherwise create a horizontal scrollbar on mobile (#1888).
+* The `repo.source.url` field no longer requires a trailing slash (#2017).
 * Anywhere you can use `_pkgdown.yml`, you can now use `_pkgdown.yaml` (#2244).
 * pkgdown no longer overrides the default selection colours. This improves accessibility for users who have set their own colours in their browser settings (#2139, @glin).
 * `build_article()` now escapes html characters in the title (#2286).

R/build-articles.R

@@ -19,7 +19,7 @@
 #' package, not the current source version. This makes iteration quicker when
 #' you are primarily working on the text of an article.
 #'
-#' @section Index and navbar:
+#' # Index and navbar
 #' You can control the articles index and navbar with a `articles` field in
 #' your `_pkgdown.yml`. If you use it, pkgdown will check that all articles
 #' are included, and will error if you have missed any.
@@ -77,7 +77,7 @@
 #' the navbar, it will link directly to the articles index instead of
 #' providing a drop-down.
 #'
-#' @section Get started:
+#' # Get started
 #' Note that a vignette with the same name as the package (e.g.,
 #' `vignettes/pkgdown.Rmd` or `vignettes/articles/pkgdown.Rmd`) automatically
 #' becomes a top-level "Get started" link, and will not appear in the articles
@@ -86,7 +86,14 @@
 #' (If your package name includes a `.`, e.g. `pack.down`, use a `-` in the
 #' vignette name, e.g. `pack-down.Rmd`.)
 #'
-#' @section External files:
+#' ## Missing topics
+#'
+#' pkgdown will warn if there are (non-internal) articles that aren't listed 
+#' in the articles index. You can suppress such warnings by listing the 
+#' affected articles in a section with `title: internal` (case sensitive); 
+#' this section will not be displayed on the index page.
+#'
+#' # External files
 #' pkgdown differs from base R in its handling of external files. When building
 #' vignettes, R assumes that vignettes are self-contained (a reasonable
 #' assumption when most vignettes were PDFs) and only copies files explicitly
@@ -107,7 +114,7 @@
 #' Note that you can not use the `fig.path` to change the output directory of
 #' generated figures as its default value is a strong assumption of rmarkdown.
 #'
-#' @section Embedding Shiny apps:
+#' # Embedding Shiny apps
 #' If you would like to embed a Shiny app into an article, the app will have
 #' to be hosted independently, (e.g. <https://www.shinyapps.io>). Then, you
 #' can embed the app into your article using an `<iframe>`, e.g.
@@ -116,7 +123,7 @@
 #' See <https://github.com/r-lib/pkgdown/issues/838#issuecomment-430473856> for
 #' some hints on how to customise the appearance with CSS.
 #'
-#' @section Output formats:
+#' # Output formats
 #' By default, pkgdown builds all articles using the
 #' [rmarkdown::html_document()] `output` format, ignoring whatever is set in
 #' your YAML metadata. This is necessary because pkgdown has to integrate the
@@ -148,15 +155,15 @@
 #'
 #' Additionally, htmlwidgets do not work when `as_is: true`.
 #'
-#' @inheritSection build_reference Figures
-#'
-#' @section Suppressing vignettes:
+#' # Suppressing vignettes
 #' If you want articles that are not vignettes, either put them in
 #' subdirectories or list in `.Rbuildignore`. An articles link will be
 #' automatically added to the default navbar if the vignettes directory is
 #' present: if you do not want this, you will need to customise the navbar. See
 #' [build_site()] details.
 #'
+#' @inheritSection build_reference Figures
+#'
 #' @inheritParams as_pkgdown
 #' @param quiet Set to `FALSE` to display output of knitr and
 #'   pandoc. This is useful when debugging.
@@ -395,6 +402,9 @@ data_articles_index <- function(pkg = ".") {
     )
   }
 
+  # Remove internal section after missing vignettes check
+  sections <- Filter(function(x) x$title != "internal", sections)
+
   print_yaml(list(
     pagetitle = tr_("Articles"),
     sections = sections

R/build-favicons.R

@@ -109,11 +109,12 @@ build_favicons <- function(pkg = ".", overwrite = FALSE) {
 copy_favicons <- function(pkg = ".") {
   pkg <- as_pkgdown(pkg)
 
-  favicons <- path(pkg$src_path, "pkgdown", "favicon")
-  if (!dir_exists(favicons))
-    return()
-
-  dir_copy_to(pkg, favicons, pkg$dst_path)
+  dir_copy_to(
+    src_dir = path(pkg$src_path, "pkgdown", "favicon"),
+    src_root = pkg$src_path,
+    dst_dir = pkg$dst_path,
+    dst_root = pkg$dst_path
+  )
 }
 
 has_favicons <- function(pkg = ".") {

R/build-home.R

@@ -68,12 +68,7 @@
 #' 
 #' [init_site()] will also automatically create a favicon set from your package logo.
 #' 
-#' ## YAML config - home
-#' 
-#' To tweak the home page, you need a section of the configuration file called 
-#' `home`.
-#' 
-#' ### Page title and description
+#' ## YAML config - title and description
 #' 
 #' By default, the page title and description are extracted automatically from
 #' the `Title` and `Description` fields `DESCRIPTION` (stripping single quotes
@@ -91,7 +86,8 @@
 #'     to your growing collection.
 #' ```
 #' 
-#' (Note the use of YAML's `>` i.e. "YAML pipes"; this is a convenient way of writing paragraphs of text.)
+#' (Note the use of YAML's `>` i.e. "YAML pipes"; this is a convenient way of 
+#' writing paragraphs of text.)
 #' 
 #' ## Dev badges
 #' 
@@ -154,17 +150,17 @@
 #'   )
 #' ```
 #' 
-#' ## YAML config - authors
+#' ## Additional control via YAML
 #' 
-#' You can tweak a few things via the `authors` YAML field:
+#' You can control additinal aspects of the authors display via the `authors` 
+#' YAML field:
 #' 
 #' * display of each author in the footer, sidebar and authors page,
 #' * which authors (by role) are displayed in the sidebar and footer,
 #' * text before authors in the footer, 
 #' * text before and after authors in the sidebar,
 #' * text before and after authors on the authors page.
 #' 
-#' 
 #' You can modify how each author's name is displayed by adding a subsection 
 #' for `authors`. Each entry in `authors` should be named the author's name 
 #' (matching `DESCRIPTION`) and can contain `href` and/or `html` fields:

R/build-logo.R

@@ -3,7 +3,12 @@ copy_logo <- function(pkg = ".") {
 
   logo_path <- find_logo(pkg$src_path)
   if (!is.null(logo_path)) {
-    file_copy_to(pkg, logo_path, from_dir = path_dir(logo_path))
+    file_copy_to(
+      src_paths = logo_path,
+      src_root = pkg$src_path,
+      dst_paths = path(pkg$dst_path, path_file(logo_path)),
+      dst_root = pkg$dst_path
+    )
   }
 }
 

R/build-news.R

@@ -38,7 +38,7 @@
 #' be added to the heading (see below for how to suppress); if not
 #' available on CRAN, "Unreleased" will be added.
 #'
-#' @section YAML config:
+#' # YAML config
 #'
 #' To automatically link to release announcements, include a `releases`
 #' section.

R/build-redirects.R

@@ -1,12 +1,42 @@
+#' Build redirects
+#' 
+#' @description
+#' If you change the structure of your documentation (by renaming vignettes or 
+#' help topics) you can setup redirects from the old content to the new content.
+#' One or several now-absent pages can be redirected to a new page (or to a new 
+#' section of a new page). This works by creating a html page that performs a 
+#' "meta refresh", which isn't the best way of doing a redirect but works 
+#' everywhere that you might deploy your site.
+#' 
+#' The syntax is the following, with old paths on the left, and new paths or 
+#' URLs on the right.
+#' 
+#' ```yaml
+#' redirects:
+#'   - ["articles/old-vignette-name.html", "articles/new-vignette-name.html"]
+#'   - ["articles/another-old-vignette-name.html", "articles/new-vignette-name.html"]
+#'   - ["articles/yet-another-old-vignette-name.html", "https://pkgdown.r-lib.org/dev"]
+#' ```
+#' 
+#' If for some reason you choose to redirect an existing page make sure to 
+#' exclude it from the search index, see `?build_search`.
+#'
+#' @inheritParams as_pkgdown
+#' @export
 build_redirects <- function(pkg = ".",
                             override = list()) {
   pkg <- section_init(pkg, depth = 1L, override = override)
 
   redirects <- c(
+    reference_redirects(pkg),
     article_redirects(pkg),
     pkg$meta$redirects
   )
 
+  # Ensure user redirects override automatic ones
+  from <- purrr::map_chr(redirects, 1)
+  redirects <- redirects[!duplicated(from)]
+
   if (is.null(redirects)) {
     return(invisible())
   }
@@ -48,6 +78,10 @@ build_redirect <- function(entry, index, pkg) {
   url <- sprintf("%s/%s%s", pkg$meta$url, pkg$prefix, new)
   lines <- whisker::whisker.render(template, list(url = url))
   dir_create(path_dir(old))
+
+  if (!file_exists(old)) {
+    cli::cli_inform("Adding redirect from {entry[1]} to {entry[2]}.")
+  }
   write_lines(lines, old)
 }
 
@@ -64,3 +98,25 @@ article_redirects <- function(pkg) {
   articles <- pkg$vignettes$file_out[is_vig_in_articles]
   purrr::map(articles, ~ paste0(c("articles/", ""), .x))
 }
+
+reference_redirects <- function(pkg) {
+  if (is.null(pkg$meta$url)) {
+    return(NULL)
+  }
+
+  aliases <- unname(pkg$topics$alias)
+  aliases <- purrr::map2(aliases, pkg$topics$name, setdiff)
+  names(aliases) <- pkg$topics$file_out
+
+  redirects <- invert_index(aliases)
+  if (length(redirects) == 0) {
+    return(list())
+  }
+
+  names(redirects) <- paste0(names(redirects), ".html")
+
+  # Ensure we don't override an existing file
+  redirects <- redirects[setdiff(names(redirects), pkg$topics$file_out)]
+
+  unname(purrr::imap(redirects, function(to, from) paste0("reference/", c(from, to))))
+}

R/build-reference.R

@@ -4,7 +4,7 @@
 #' alphabetical order. To override this, provide a `reference` section in your
 #' `_pkgdown.yml` as described below.
 #'
-#' @section Reference index:
+#' # Reference index
 #' To tweak the index page, add a section called `reference` to `_pkgdown.yml`.
 #' It can contain three different types of element:
 #'
@@ -104,12 +104,12 @@
 #' either 30x30 (for regular display) or 60x60 (if you want retina display).
 #' Icons are matched to topics by aliases.
 #'
-#' ## Examples
+#' # Examples
 #'
 #' If you need to run extra code before or after all examples are run, you
 #' can create `pkgdown/pre-reference.R` and `pkgdown/post-reference.R`.
 #'
-#' @section Figures:
+#' # Figures
 #'
 #' You can control the default rendering of figures by specifying the `figures`
 #' field in `_pkgdown.yml`. The default settings are equivalent to:
@@ -207,11 +207,12 @@ build_reference <- function(pkg = ".",
 
 copy_figures <- function(pkg) {
   # copy everything from man/figures to docs/reference/figures
-  src_figures <- path(pkg$src_path, "man", "figures")
-  dst_figures <- path(pkg$dst_path, "reference", "figures")
-  if (file_exists(src_figures)) {
-    dir_copy_to(pkg, src_figures, dst_figures)
-  }
+  dir_copy_to(
+    src_dir = path(pkg$src_path, "man", "figures"),
+    src_root = pkg$src_path,
+    dst_dir = path(pkg$dst_path, "reference", "figures"),
+    dst_root = pkg$dst_path
+  )
 }
 
 examples_env <- function(pkg, seed = 1014L, devel = TRUE, envir = parent.frame()) {
@@ -254,11 +255,12 @@ build_reference_index <- function(pkg = ".") {
   create_subdir(pkg, "reference")
 
   # Copy icons, if needed
-  src_icons <- path(pkg$src_path, "icons")
-  dst_icons <- path(pkg$dst_path, "reference", "icons")
-  if (file_exists(src_icons)) {
-    dir_copy_to(pkg, src_icons, dst_icons)
-  }
+  dir_copy_to(
+    src_dir = path(pkg$src_path, "icons"),
+    src_root = pkg$src_path,
+    dst_dir = path(pkg$dst_path, "reference", "icons"),
+    dst_root = pkg$dst_path
+  )
 
   render_page(
     pkg, "reference-index",