From a2e45a843f838d84e9ed330cb9c3e57a3969fa03 Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Wed, 22 May 2024 15:15:53 -0500 Subject: [PATCH 1/3] Elimiante the search vignette Fixes #2564 --- NEWS.md | 1 + R/build-search-docs.R | 13 +++++-- man/build_search.Rd | 12 ++++-- pkgdown/_pkgdown.yml | 4 +- vignettes/search.Rmd | 86 ------------------------------------------- 5 files changed, 23 insertions(+), 93 deletions(-) delete mode 100644 vignettes/search.Rmd diff --git a/NEWS.md b/NEWS.md index 5b1a15a90..2b583003d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,6 @@ # pkgdown (development version) +* `vignette("search")` has been removed since BS3 is deprecated and all the BS5 docs are also included in `build_search()` (#2564). * YAML validation has been substantially improved so you should get much clearer errors if you have made a mistake (#1927). Please file an issue if you find a case where the error message is not helpful. * `template_reference()` and `template_article()` now only add backticks to function names if needed (#2561). * Custom navbars that specify `icon` but not `aria-label` will now generate a message reminding you to provide one for to improve accessibility (#2533). diff --git a/R/build-search-docs.R b/R/build-search-docs.R index de7959502..6ce4ded87 100644 --- a/R/build-search-docs.R +++ b/R/build-search-docs.R @@ -65,12 +65,19 @@ url_node <- function(url) { } #' Build search index +#' +#' @description +#' Generate a JSON search index from the built site. This is used by +#' [fuse.js](https://www.fusejs.io/) to provide a javascript powered search for +#' BS5 powered pkgdown sites. #' -#' Build a JSON file encompassing all HTML pages, for use by the search script. +#' NB: `build_search()` is called automatically by [build_site()]; you don't +#' need call it yourself. This page documents how it works and its customisation +#' options. #' #' # YAML config -#' You can exclude some paths from the search index. -#' Below we exclude the changelog from the search index. +#' You can exclude some paths from the search index using `search.exclude`. +#' Below we exclude the changelog from the search index: #' #' ```yaml #' search: diff --git a/man/build_search.Rd b/man/build_search.Rd index 4d2fc04fe..3c787b518 100644 --- a/man/build_search.Rd +++ b/man/build_search.Rd @@ -13,11 +13,17 @@ build_search(pkg = ".", override = list()) values in \verb{_pkgdown.yml}} } \description{ -Build a JSON file encompassing all HTML pages, for use by the search script. +Generate a JSON search index from the built site. This is used by +\href{https://www.fusejs.io/}{fuse.js} to provide a javascript powered search for +BS5 powered pkgdown sites. + +NB: \code{build_search()} is called automatically by \code{\link[=build_site]{build_site()}}; you don't +need call it yourself. This page documents how it works and its customisation +options. } \section{YAML config}{ -You can exclude some paths from the search index. -Below we exclude the changelog from the search index. +You can exclude some paths from the search index using \code{search.exclude}. +Below we exclude the changelog from the search index: \if{html}{\out{
}}\preformatted{search: exclude: ['news/index.html'] diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 7d3366acc..cbb9b0ad5 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -36,7 +36,6 @@ articles: - customise - accessibility - linking - - search - metadata - title: Advanced techniques @@ -83,6 +82,9 @@ reference: contents: - starts_with("test", internal = TRUE) +redirects: +- ["/articles/search.html", "/reference/build_search.html"] + news: releases: - text: "Version 2.0.0" diff --git a/vignettes/search.Rmd b/vignettes/search.Rmd deleted file mode 100644 index 2fc7cf81e..000000000 --- a/vignettes/search.Rmd +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: "Search" -description: > - Learn how to set up search for your pkgdown site. -output: rmarkdown::html_vignette -vignette: > - %\VignetteIndexEntry{Search} - %\VignetteEngine{knitr::rmarkdown} - %\VignetteEncoding{UTF-8} ---- - -```{r, include = FALSE} -knitr::opts_chunk$set( - collapse = TRUE, - comment = "#>" -) -``` - -Depending on the Bootstrap version used for your pkgdown website, search will be either built-in (Bootstrap 5 and up) or will need some more configuration of an external service (Bootstrap 3). -We'd recommend switching to Bootstrap 5, see `vignette("customise")`. - -## Bootstrap 5: built-in search - -With BS5, search is built-in so building your pkgdown website will automatically build a search index that's available in navbar (using [fuse.js](https://www.fusejs.io/)). -Currently the only available customisation is excluding some paths from the search index: - -``` yaml -search: - exclude: ['news/index.html'] -``` - -Note that search requires a "real" server, not a local `file://` based preview, so search won't work with the default preview. -To test search with a local preview, you'll need to use `servr::httw("docs")` or similar. - -## Bootstrap 3: Algolia - -pkgdown websites can integrate search capability using [DocSearch](https://docsearch.algolia.com/) from Algolia. -DocSearch is a powerful search engine that is free for documentation websites. -There are only two steps needed to enable DocSearch on a pkgdown website. - -### Indexing - -Once you have published your pkgdown website, submit the [pkgdown site URL to Docsearch](https://docsearch.algolia.com/). -Docsearch will contact you via e-mail to confirm you are the website owner. - -Docsearch will set up a crawler configuration that indexes your site every 24 hours. -pkgdown builds a suggested Docsearch crawler configuration in `docsearch.json` and you should point the Docsearch team to this configuration as a starting point. -If you want to optimize your search, Docsearch will accept pull requests to the configuration that incorporate [additional options](https://github.com/algolia/docsearch-configs#introduction) to fine tune the scraping. - -### Configuration - -The Docsearch team will e-mail you some JavaScript to integrate into your website. - -``` js -