diff --git a/NEWS.md b/NEWS.md index 5b1a15a907..2b583003da 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 de79595027..6ce4ded870 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/R/build.R b/R/build.R index e7995c0eee..069ab58f17 100644 --- a/R/build.R +++ b/R/build.R @@ -40,11 +40,6 @@ #' footer which appear on every page. Learn more about these fields in #' `vignette("customise")`. #' -#' # Search -#' -#' The `search` field controls the built-in search and is -#' documented in `vignette("search")`. -#' #' # Development mode #' The `development` field allows you to generate different sites for the #' development and released versions of your package. To use it, you first diff --git a/man/build_search.Rd b/man/build_search.Rd index 4d2fc04fea..3c787b518b 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/man/build_site.Rd b/man/build_site.Rd index e79c04b047..894edcf541 100644 --- a/man/build_site.Rd +++ b/man/build_site.Rd @@ -101,11 +101,6 @@ footer which appear on every page. Learn more about these fields in \code{vignette("customise")}. } -\section{Search}{ -The \code{search} field controls the built-in search and is -documented in \code{vignette("search")}. -} - \section{Development mode}{ The \code{development} field allows you to generate different sites for the development and released versions of your package. To use it, you first diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 7d3366acc5..d8a57ff07a 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/customise.Rmd b/vignettes/customise.Rmd index c3c691c757..f5d7c0fa16 100644 --- a/vignettes/customise.Rmd +++ b/vignettes/customise.Rmd @@ -243,7 +243,7 @@ It makes use of the the six built-in components: - `articles`, if there are any vignettes or articles. - `tutorials`, if there any tutorials. - `news`, if `NEWS.md` exists. -- `search`, the search box (see `vignette("search")` for more details). +- `search`, the search box (see `?build_search` for more details). - `github`, a link to the source repository (with an icon), if it can be automatically determined from the `DESCRIPTION`. [^dots]: Note that dots (`.`) in the package name need to be replaced by hyphens (`-`) in the vignette filename to be recognized as the intro. That means for a diff --git a/vignettes/search.Rmd b/vignettes/search.Rmd deleted file mode 100644 index 2fc7cf81e3..0000000000 --- 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 -