From eba8eece66a546f25b41f87d438b0b5e33c1c521 Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Thu, 18 Apr 2024 08:01:08 -0500 Subject: [PATCH 1/6] Describe what check_pkgdown() actually does (#2460) Fixes #2260 --- R/check.R | 9 ++++++++- man/check_pkgdown.Rd | 8 +++++++- 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/R/check.R b/R/check.R index 1858ab454..08343d2da 100644 --- a/R/check.R +++ b/R/check.R @@ -1,7 +1,14 @@ #' Check `_pkgdown.yml` #' +#' @description #' Check that your `_pkgdown.yml` is valid without building the whole -#' site. +#' site. Currently this: +#' +#' * Checks the reference and article indexes to ensure that pkgdown can +#' read them, and that every documentation topic and vignette/article is +#' included in the index. +#' +#' * Validates any opengraph metadata that you might have supplied #' #' @export #' @inheritParams as_pkgdown diff --git a/man/check_pkgdown.Rd b/man/check_pkgdown.Rd index 1be57ec87..d049c9439 100644 --- a/man/check_pkgdown.Rd +++ b/man/check_pkgdown.Rd @@ -11,5 +11,11 @@ check_pkgdown(pkg = ".") } \description{ Check that your \verb{_pkgdown.yml} is valid without building the whole -site. +site. Currently this: +\itemize{ +\item Checks the reference and article indexes to ensure that pkgdown can +read them, and that every documentation topic and vignette/article is +included in the index. +\item Validates any opengraph metadata that you might have supplied +} } From b87df21d3cabfcfa757413e7ef3cfb8432536405 Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Thu, 18 Apr 2024 11:28:12 -0500 Subject: [PATCH 2/6] Check navbar structure (#2467) Fixes #2312 --- NEWS.md | 1 + R/navbar.R | 16 +++++++++++----- tests/testthat/_snaps/navbar.md | 14 +++++++++++--- tests/testthat/test-navbar.R | 17 ++++++++++++++--- 4 files changed, 37 insertions(+), 11 deletions(-) diff --git a/NEWS.md b/NEWS.md index 6f316e20b..5cdb677ef 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,6 @@ # pkgdown (development version) +* `data_template()` gives a more informative error if you've misspecified the navbar (#2312). * The skip link now becomes visible when focussed (#2138). Thanks to @glin for the styles! * `build_reference_index()` gives more informative errors if your `contents` field is malformed (#2323). * The left and right footers no longer contain an extra empty paragraph tag and the footer gains additional padding-top to keep the whitespace constant (#2381). diff --git a/R/navbar.R b/R/navbar.R index e5d670332..8c1b31627 100644 --- a/R/navbar.R +++ b/R/navbar.R @@ -54,18 +54,24 @@ navbar_links <- function(pkg, depth = 0L) { yaml_character(pkg, c("navbar", "structure", "left")), names(components) ) - # Backward compatibility left <- navbar$left %||% components[left_comp] right <- navbar$right %||% components[right_comp] list( - left = render_navbar_links(left, depth = depth, bs_version = pkg$bs_version), - right = render_navbar_links(right, depth = depth, bs_version = pkg$bs_version) + left = render_navbar_links(left, depth = depth, pkg = pkg), + right = render_navbar_links(right, depth = depth, pkg = pkg) ) } -render_navbar_links <- function(x, depth = 0L, bs_version = 3) { +render_navbar_links <- function(x, depth = 0L, pkg) { + if (!is.list(x)) { + cli::cli_abort( + "Invalid navbar specification in {pkgdown_config_href({pkg$src_path})}", + call = quote(data_template()) + ) + } + stopifnot(is.integer(depth), depth >= 0L) tweak <- function(x) { @@ -83,7 +89,7 @@ render_navbar_links <- function(x, depth = 0L, bs_version = 3) { x <- lapply(x, tweak) } - if (bs_version == 3) { + if (pkg$bs_version == 3) { rmarkdown::navbar_links_html(x) } else { bs4_navbar_links_html(x) diff --git a/tests/testthat/_snaps/navbar.md b/tests/testthat/_snaps/navbar.md index 40190cdf0..552e2a765 100644 --- a/tests/testthat/_snaps/navbar.md +++ b/tests/testthat/_snaps/navbar.md @@ -177,10 +177,18 @@ Error in `navbar_links()`: ! navbar.structure.left must be a character vector. +# data_navbar() errors with bad left/right + + Code + data_navbar(pkg) + Condition + Error in `data_template()`: + ! Invalid navbar specification in _pkgdown.yml + # render_navbar_links BS3 & BS4 default Code - cat(render_navbar_links(x, bs_version = 3)) + cat(render_navbar_links(x, pkg = list(bs_version = 3))) Output
  • Get started @@ -220,7 +228,7 @@ --- Code - cat(render_navbar_links(x, bs_version = 4)) + cat(render_navbar_links(x, pkg = list(bs_version = 4))) Output
  • Get started @@ -246,7 +254,7 @@ # render_navbar_links BS4 no divider before first element Code - cat(render_navbar_links(x, bs_version = 4)) + cat(render_navbar_links(x, pkg = list(bs_version = 4))) Output
  • diff --git a/tests/testthat/test-navbar.R b/tests/testthat/test-navbar.R index 6ab2c4afe..c97f2bb85 100644 --- a/tests/testthat/test-navbar.R +++ b/tests/testthat/test-navbar.R @@ -132,6 +132,16 @@ test_that("data_navbar() errors with bad side specifications", { expect_snapshot(data_navbar(pkg), error = TRUE) }) +test_that("data_navbar() errors with bad left/right", { + pkg <- local_pkgdown_site(meta = " + navbar: + right: [github] + ") + + expect_snapshot(data_navbar(pkg), error = TRUE) +}) + + test_that("for bs4, default bg and type come from bootswatch", { style <- navbar_style(bs_version = 5) expect_equal(style, list(bg = "light", type = "light")) @@ -164,8 +174,9 @@ test_that("render_navbar_links BS3 & BS4 default", { ), news = list(text = "News", href = "news/index.html") ) - expect_snapshot(cat(render_navbar_links(x, bs_version = 3))) - expect_snapshot(cat(render_navbar_links(x, bs_version = 4))) + + expect_snapshot(cat(render_navbar_links(x, pkg = list(bs_version = 3)))) + expect_snapshot(cat(render_navbar_links(x, pkg = list(bs_version = 4)))) }) test_that("render_navbar_links BS4 no divider before first element", { @@ -183,7 +194,7 @@ test_that("render_navbar_links BS4 no divider before first element", { ) ) ) - expect_snapshot(cat(render_navbar_links(x, bs_version = 4))) + expect_snapshot(cat(render_navbar_links(x, pkg = list(bs_version = 4)))) }) test_that("can specific link target", { From 92f1b966e7be7f8fd0199a7ea9e892ac64c6bb10 Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Thu, 18 Apr 2024 11:57:16 -0500 Subject: [PATCH 3/6] More info about making a template package (#2465) Fixes #2291 --- vignettes/customise.Rmd | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/vignettes/customise.Rmd b/vignettes/customise.Rmd index 48b56c484..e4825ad6c 100644 --- a/vignettes/customise.Rmd +++ b/vignettes/customise.Rmd @@ -226,23 +226,26 @@ It can contain any of the following: - A configuration file in `inst/pkgdown/_pkgdown.yml`. This can be used to set (e.g.) author definitions, Bootstrap version and variables, the sidebar, footer, navbar, etc. - Templates in `inst/pkgdown/templates/` will override the default templates. - Assets in `inst/pkgdown/assets/` will be copied in to the destination directory. + (Note these files are only copied; you'll need to reference them in your stylesheet or elsewhere in order for them to be actually used.) - `inst/pkgdown/extra.scss` will be added to the bslib ruleset. + (Note that `extra.css` is not supported in templates.) -Any configuration/files supplied will override the pkgdown defaults, but will be overridden by site specific settings. +The pkgdown defaults will be overriden by these template files, which are in turn overridden by package specific settings. -Once you have created your template package `theverybest`, you can use it by: +Once you have created your template package `theverybest`, you need to set it as your site's theme: -- Setting it as your sites theme: +``` yaml +template: + package: theverybest +``` - ``` yaml - template: - package: theverybest - ``` +You then also need to make sure it's available when your site is build. Typically, you won't want to publish this package to CRAN, but you will want to publish to GitHub. Once you've done that, and assuming you're using the [usethis workflow](https://usethis.r-lib.org/reference/use_pkgdown.html), add the following line to your `DESCRIPTION`: -- If you're building your site using GitHub actions or other similar tool, you'll also need to installed `theverybest`. - If you're using the r-lib [pkgdown workflow](https://github.com/r-lib/actions/tree/master/examples#build-pkgdown-site), you can add the following line to your `DESCRIPTION`: +```yaml +Config/Needs/website: myorg/theverybest +``` - Config/Needs/website: theverybest +This will ensure that the GitHub action will automatically install it from GitHub when building your pkgdown site. To get some sense of how a theming package works, you can look at: From 4d204e1e3adba87ff7a40f3795c96981eea5d2c1 Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Thu, 18 Apr 2024 12:02:58 -0500 Subject: [PATCH 4/6] Don't globally change cli.default_handler for tests (#2470) I removed this primarily because it globally suppresses cli output after you run any test file interactively, but IMO it also increases the fidelity of the snapshots. --- tests/testthat/_snaps/build-articles.md | 4 ++++ tests/testthat/_snaps/build-favicons.md | 3 +++ tests/testthat/_snaps/build-github.md | 1 + tests/testthat/_snaps/build-home-citation.md | 1 + tests/testthat/_snaps/build-home.md | 5 +++++ tests/testthat/_snaps/build-news.md | 1 + tests/testthat/_snaps/build-reference.md | 4 ++++ tests/testthat/_snaps/figure.md | 2 ++ tests/testthat/setup.R | 3 --- 9 files changed, 21 insertions(+), 3 deletions(-) delete mode 100644 tests/testthat/setup.R diff --git a/tests/testthat/_snaps/build-articles.md b/tests/testthat/_snaps/build-articles.md index 9c59cec2b..f64bcaa2a 100644 --- a/tests/testthat/_snaps/build-articles.md +++ b/tests/testthat/_snaps/build-articles.md @@ -11,6 +11,7 @@ Code build_articles(pkg, lazy = FALSE) Message + -- Building articles ----------------------------------------------------------- Writing `articles/index.html` Reading vignettes/kitten.Rmd Writing `articles/kitten.html` @@ -20,6 +21,7 @@ Code build_articles(pkg) Message + -- Building articles ----------------------------------------------------------- Writing `articles/index.html` Reading vignettes/html-vignette.Rmd Writing `articles/html-vignette.html` @@ -112,6 +114,8 @@ Code build_redirects(pkg) + Message + -- Building redirects ---------------------------------------------------------- # pkgdown deps are included only once in articles diff --git a/tests/testthat/_snaps/build-favicons.md b/tests/testthat/_snaps/build-favicons.md index 622da598b..aed4be803 100644 --- a/tests/testthat/_snaps/build-favicons.md +++ b/tests/testthat/_snaps/build-favicons.md @@ -2,6 +2,8 @@ Code expect_output(build_favicons(pkg), "Building favicons") + Message + -- Building favicons ----------------------------------------------------------- Condition Error in `build_favicons()`: ! Can't find package logo PNG or SVG to build favicons. @@ -12,6 +14,7 @@ Code build_favicons(pkg) Message + -- Building favicons ----------------------------------------------------------- Favicons already exist in 'pkgdown' i Set `overwrite = TRUE` to re-create. diff --git a/tests/testthat/_snaps/build-github.md b/tests/testthat/_snaps/build-github.md index a5aa82eff..897353eed 100644 --- a/tests/testthat/_snaps/build-github.md +++ b/tests/testthat/_snaps/build-github.md @@ -3,6 +3,7 @@ Code build_github_pages(pkg) Message + -- Extra files for GitHub pages ------------------------------------------------ Writing `.nojekyll` Writing `CNAME` diff --git a/tests/testthat/_snaps/build-home-citation.md b/tests/testthat/_snaps/build-home-citation.md index 8e49e9250..6646db218 100644 --- a/tests/testthat/_snaps/build-home-citation.md +++ b/tests/testthat/_snaps/build-home-citation.md @@ -3,6 +3,7 @@ Code build_home(pkg) Message + -- Building home --------------------------------------------------------------- Writing `authors.html` Writing `404.html` diff --git a/tests/testthat/_snaps/build-home.md b/tests/testthat/_snaps/build-home.md index 3bb26f309..d3f62ff2d 100644 --- a/tests/testthat/_snaps/build-home.md +++ b/tests/testthat/_snaps/build-home.md @@ -3,6 +3,7 @@ Code build_home(pkg) Message + -- Building home --------------------------------------------------------------- Writing `authors.html` Writing `404.html` @@ -11,6 +12,7 @@ Code build_home(pkg) Message + -- Building home --------------------------------------------------------------- Writing `authors.html` Writing `404.html` @@ -19,6 +21,7 @@ Code build_home(pkg) Message + -- Building home --------------------------------------------------------------- Writing `authors.html` Condition Warning: @@ -32,6 +35,7 @@ Code build_home(pkg) Message + -- Building home --------------------------------------------------------------- Writing `authors.html` Writing `404.html` @@ -40,6 +44,7 @@ Code build_home(pkg) Message + -- Building home --------------------------------------------------------------- Writing `authors.html` Reading .github/404.md Writing `404.html` diff --git a/tests/testthat/_snaps/build-news.md b/tests/testthat/_snaps/build-news.md index c0af6e18c..c91e9f9ab 100644 --- a/tests/testthat/_snaps/build-news.md +++ b/tests/testthat/_snaps/build-news.md @@ -32,6 +32,7 @@ Code build_news(pkg) Message + -- Building news --------------------------------------------------------------- Writing `news/news-2.0.html` Writing `news/news-1.1.html` Writing `news/news-1.0.html` diff --git a/tests/testthat/_snaps/build-reference.md b/tests/testthat/_snaps/build-reference.md index 6049eb43c..2bb006202 100644 --- a/tests/testthat/_snaps/build-reference.md +++ b/tests/testthat/_snaps/build-reference.md @@ -3,6 +3,7 @@ Code build_reference(pkg) Message + -- Building function reference ------------------------------------------------- Writing `reference/index.html` Reading man/f.Rd Condition @@ -17,6 +18,7 @@ Code build_reference(pkg, topics = "e") Message + -- Building function reference ------------------------------------------------- Writing `reference/index.html` Reading man/e.Rd Writing `reference/e.html` @@ -26,6 +28,7 @@ Code build_reference(pkg, topics = "e") Message + -- Building function reference ------------------------------------------------- Writing `reference/index.html` Reading man/e.Rd Writing `reference/e.html` @@ -35,6 +38,7 @@ Code build_reference(pkg, topics = "a") Message + -- Building function reference ------------------------------------------------- Writing `reference/index.html` Reading man/a.Rd Writing `reference/a.html` diff --git a/tests/testthat/_snaps/figure.md b/tests/testthat/_snaps/figure.md index ace2904d0..2e7fbc508 100644 --- a/tests/testthat/_snaps/figure.md +++ b/tests/testthat/_snaps/figure.md @@ -3,6 +3,7 @@ Code build_reference(pkg, devel = FALSE) Message + -- Building function reference ------------------------------------------------- Writing `reference/index.html` Reading man/figure.Rd Writing `reference/figure.html` @@ -12,6 +13,7 @@ Code build_articles(pkg) Message + -- Building articles ----------------------------------------------------------- Writing `articles/index.html` Reading vignettes/figures.Rmd Writing `articles/figures.html` diff --git a/tests/testthat/setup.R b/tests/testthat/setup.R deleted file mode 100644 index 75010f6ee..000000000 --- a/tests/testthat/setup.R +++ /dev/null @@ -1,3 +0,0 @@ -# suppress cli messages in interactive testthat output -# https://github.com/r-lib/cli/issues/434 -options(cli.default_handler = function(...) { }) From 321f012c141942aedfb89789fa1ad5ecd397ba9c Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Thu, 18 Apr 2024 12:03:27 -0500 Subject: [PATCH 5/6] Work with empty markdown files (#2466) Fixes #2309 --- NEWS.md | 1 + R/markdown.R | 4 ++++ tests/testthat/test-markdown.R | 4 ++++ 3 files changed, 9 insertions(+) diff --git a/NEWS.md b/NEWS.md index 5cdb677ef..12e4bccd5 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,6 @@ # pkgdown (development version) +* `build_home()` no longer errors when you have an empty `.md` file (#2309). * `data_template()` gives a more informative error if you've misspecified the navbar (#2312). * The skip link now becomes visible when focussed (#2138). Thanks to @glin for the styles! * `build_reference_index()` gives more informative errors if your `contents` field is malformed (#2323). diff --git a/R/markdown.R b/R/markdown.R index 5574343fe..4e040f890 100644 --- a/R/markdown.R +++ b/R/markdown.R @@ -38,6 +38,10 @@ markdown_text_block <- function(text, ...) { markdown_body <- function(path, strip_header = FALSE) { xml <- markdown_path_html(path, strip_header = strip_header) + if (is.null(xml)) { + return(NULL) + } + # Extract body of html - as.character renders as xml which adds # significant whitespace in tags like pre transformed_path <- withr::local_tempfile() diff --git a/tests/testthat/test-markdown.R b/tests/testthat/test-markdown.R index fbae59023..cbe5be266 100644 --- a/tests/testthat/test-markdown.R +++ b/tests/testthat/test-markdown.R @@ -4,6 +4,10 @@ test_that("handles empty inputs", { expect_equal(markdown_text_block(NULL), NULL) expect_equal(markdown_text_block(""), NULL) + + path <- withr::local_tempfile() + file.create(path) + expect_equal(markdown_body(path), NULL) }) test_that("header attributes are parsed", { From 9d22b8c6a8a4c4d9753315ad52b854096de4eb95 Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Thu, 18 Apr 2024 12:03:56 -0500 Subject: [PATCH 6/6] Also tweak urls with fragment (#2469) Fixes #2313 --- NEWS.md | 2 ++ R/tweak-tags.R | 6 ++++-- tests/testthat/test-tweak-tags.R | 4 +++- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/NEWS.md b/NEWS.md index 12e4bccd5..f4440a37f 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,6 +1,8 @@ # pkgdown (development version) +* `build_readme()` now correctly tweaks links to markdown files that use an anchor, e.g. `foo.md#heading-name` (#2313). * `build_home()` no longer errors when you have an empty `.md` file (#2309). + * `data_template()` gives a more informative error if you've misspecified the navbar (#2312). * The skip link now becomes visible when focussed (#2138). Thanks to @glin for the styles! * `build_reference_index()` gives more informative errors if your `contents` field is malformed (#2323). diff --git a/R/tweak-tags.R b/R/tweak-tags.R index dc16ede88..7c9b8cb60 100644 --- a/R/tweak-tags.R +++ b/R/tweak-tags.R @@ -43,10 +43,12 @@ tweak_link_md <- function(html) { return() hrefs <- xml2::xml_attr(links, "href") - needs_tweak <- grepl("\\.md$", hrefs) & xml2::url_parse(hrefs)$scheme == "" + + urls <- xml2::url_parse(hrefs) + needs_tweak <- urls$scheme == "" & grepl("\\.md$", urls$path) fix_links <- function(x) { - x <- gsub("\\.md$", ".html", x) + x <- gsub("\\.md\\b", ".html", x) x <- gsub("\\.github/", "", x) x } diff --git a/tests/testthat/test-tweak-tags.R b/tests/testthat/test-tweak-tags.R index e4849df4a..5a08e9891 100644 --- a/tests/testthat/test-tweak-tags.R +++ b/tests/testthat/test-tweak-tags.R @@ -119,16 +119,18 @@ test_that("docs with no headings are left unchanged", { test_that("local md links are replaced with html", { html <- xml2::read_html(' + ') tweak_link_md(html) expect_equal( xpath_attr(html, "//a", "href"), - c("local.html", "http://remote.com/remote.md") + c("local.html", "local.html#fragment", "http://remote.com/remote.md") ) }) + test_that("tweak_link_external() add the external-link class if needed", { html <- xml2::read_html('