diff --git a/R/build-articles.R b/R/build-articles.R index c3f54108e..38411d683 100644 --- a/R/build-articles.R +++ b/R/build-articles.R @@ -173,13 +173,14 @@ #' Additionally, htmlwidgets do not work when `as_is: true`. #' #' # Suppressing vignettes -#' If you want articles that are not vignettes, either put them in -#' subdirectories or list in `.Rbuildignore`. An articles link will be +#' If you want [articles](https://r-pkgs.org/vignettes.html#sec-vignettes-article) +#' that are not vignettes, use `usethis::use_article()` to create it. 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 +#' @family site components #' #' @inheritParams as_pkgdown #' @param quiet Set to `FALSE` to display output of knitr and diff --git a/R/build-favicons.R b/R/build-favicons.R index 252f7fa61..1953ed811 100644 --- a/R/build-favicons.R +++ b/R/build-favicons.R @@ -1,16 +1,17 @@ -#' Create favicons from package logo +#' Initialise favicons from package logo #' +#' @description #' This function auto-detects the location of your package logo (with the name -#' `logo.svg` (recommended format) or `logo.png`) and runs it through the -#' API to build a complete set of favicons -#' with different sizes, as needed for modern web usage. +#' `logo.svg` (recommended format) or `logo.png`, created with `usethis::use_logo()`) +#' and runs it through the API to build a +#' complete set of favicons with different sizes, as needed for modern web usage. #' #' You only need to run the function once. The favicon set will be stored in #' `pkgdown/favicon` and copied by [init_site()] to the relevant location when #' the website is rebuilt. #' #' Once complete, you should add `pkgdown/` to `.Rbuildignore ` to avoid a NOTE -#' during package checking. +#' during package checking. (`usethis::use_logo()` does this for you!) #' #' @inheritParams as_pkgdown #' @param overwrite If `TRUE`, re-create favicons from package logo. diff --git a/R/build-home.R b/R/build-home.R index 9c205b00b..142378b33 100644 --- a/R/build-home.R +++ b/R/build-home.R @@ -283,7 +283,9 @@ #' sidebar: FALSE #' ``` #' @inheritParams build_articles +#' @family site components #' @export +#' @order 1 build_home <- function(pkg = ".", override = list(), preview = NA, diff --git a/R/build-news.R b/R/build-news.R index 14b7e4cae..c61c9753e 100644 --- a/R/build-news.R +++ b/R/build-news.R @@ -66,6 +66,7 @@ #' news: #' cran_dates: false #' ``` +#' @family site components #' #' @seealso [Tidyverse style for News](https://style.tidyverse.org/news.html) #' diff --git a/R/build-reference.R b/R/build-reference.R index 87c425151..16ad706af 100644 --- a/R/build-reference.R +++ b/R/build-reference.R @@ -83,7 +83,7 @@ #' * `has_lifecycle("deprecated")` will select all topics with lifecycle #' deprecated. #' -#' All functions (except for `has_keywords()`) automatically exclude internal +#' All functions (except for `has_keyword()`) automatically exclude internal #' topics (i.e. those with `\keyword{internal}`). You can choose to include #' with (e.g.) `starts_with("build_", internal = TRUE)`. #' @@ -136,6 +136,7 @@ #' as HTML widgets. #' #' @inheritParams build_articles +#' @family site components #' @param lazy If `TRUE`, only rebuild pages where the `.Rd` #' is more recent than the `.html`. This makes it much easier to #' rapidly prototype. It is set to `FALSE` by [build_site()]. diff --git a/R/build-tutorials.R b/R/build-tutorials.R index 69ed969d9..1060a3e87 100644 --- a/R/build-tutorials.R +++ b/R/build-tutorials.R @@ -26,6 +26,7 @@ #' url: https://jjallaire.shinyapps.io/learnr-tutorial-01-data-basics/ #' ``` #' @inheritParams build_articles +#' @family site components #' @export build_tutorials <- function(pkg = ".", override = list(), preview = NA) { pkg <- section_init(pkg, depth = 1L, override = override) diff --git a/R/build.R b/R/build.R index 069ab58f1..24e17cb87 100644 --- a/R/build.R +++ b/R/build.R @@ -28,7 +28,7 @@ #' It specifies where the site will be published and is used to allow other #' pkgdown sites to link to your site when needed (`vignette("linking")`), #' generate a `sitemap.xml`, automatically generate a `CNAME` when -#' [deploying to github][deploy_site_github], generate the metadata needed +#' [deploying to github][build_site_github_pages()], generate the metadata needed #' rich social "media cards" (`vignette("metadata")`), and more. #' #' * `title` overrides the default site title, which is the package name. diff --git a/R/init.R b/R/init.R index fa0e2d50c..90ddc21d3 100644 --- a/R/init.R +++ b/R/init.R @@ -12,7 +12,7 @@ #' display of your site. #' #' # Build-ignored files -#' We recommend using [usethis::use_pkgdown()] to build-ignore `docs/` and +#' We recommend using [usethis::use_pkgdown_github_pages()] to build-ignore `docs/` and #' `_pkgdown.yml`. If use another directory, or create the site manually, #' you'll need to add them to `.Rbuildignore` yourself. A `NOTE` about #' an unexpected file during `R CMD CHECK` is an indication you have not diff --git a/README.Rmd b/README.Rmd index b286a25e4..b24dccae9 100644 --- a/README.Rmd +++ b/README.Rmd @@ -44,17 +44,19 @@ pak::pak("r-lib/pkgdown") Get started with [usethis](https://usethis.r-lib.org/): ```{r, eval = FALSE} -# Run once to configure your package to use pkgdown -usethis::use_pkgdown() +# Run once to configure your package to use and deploy pkgdown +usethis::use_pkgdown_github_pages() ``` -Then use pkgdown to build your website: - ```{r, eval = FALSE} +# Preview your site locally before publishing pkgdown::build_site() ``` -This generates a `docs/` directory containing a website. Your `README.md` becomes the homepage, documentation in `man/` generates a function reference, and vignettes will be rendered into `articles/`. Read `vignette("pkgdown")` for more details, and to learn how to deploy your site to GitHub pages. +This adds the necessary components and sets up GitHub Actions[^1] for automatic site building when deploying. +Your `README.md` becomes the homepage, documentation in `man/` generates a function reference, and vignettes will be rendered into `articles/`. + +[^1]: If you don't use GitHub, you can use `usethis::use_pkgdown()` + `pkgdown::build_site()` to create a website. ### pkgdown 2.0.0 and Bootstrap 5 @@ -69,7 +71,7 @@ Then learn about the many new ways to customise your site in `vignette("customis ## In the wild -At last count, pkgdown is used [by over 11,000 packages](https://github.com/search?q=path%3A_pkgdown.yml+language%3AYAML&type=code&l=YAML). Here are a few examples created by contributors to pkgdown: +At last count, pkgdown is used [by over 12,000 packages](https://github.com/search?q=path%3A_pkgdown.yml+language%3AYAML&type=code&l=YAML). Here are a few examples: * [bayesplot](http://mc-stan.org/bayesplot/index.html) ([source](https://github.com/stan-dev/bayesplot/tree/gh-pages)): @@ -88,6 +90,8 @@ At last count, pkgdown is used [by over 11,000 packages](https://github.com/sear ([source](https://github.com/renozao/NMF)): a framework to perform non-negative matrix factorization (NMF). +* [tidyverse and r-lib packages source](https://github.com/search?q=path%3A%22_pkgdown.yml%22+AND+%28org%3Atidyverse+OR+org%3Ar-lib%29&type=code) + Comparing the source and output of these sites is a great way to learn new pkgdown techniques. ## Code of conduct diff --git a/README.md b/README.md index 6eb921abd..0a820511c 100644 --- a/README.md +++ b/README.md @@ -48,21 +48,19 @@ pak::pak("r-lib/pkgdown") Get started with [usethis](https://usethis.r-lib.org/): ``` r -# Run once to configure your package to use pkgdown -usethis::use_pkgdown() +# Run once to configure your package to use and deploy pkgdown +usethis::use_pkgdown_github_pages() ``` -Then use pkgdown to build your website: - ``` r +# Preview your site locally before publishing pkgdown::build_site() ``` -This generates a `docs/` directory containing a website. Your -`README.md` becomes the homepage, documentation in `man/` generates a -function reference, and vignettes will be rendered into `articles/`. -Read `vignette("pkgdown")` for more details, and to learn how to deploy -your site to GitHub pages. +This adds the necessary components and sets up GitHub Actions[^1] for +automatic site building when deploying. Your `README.md` becomes the +homepage, documentation in `man/` generates a function reference, and +vignettes will be rendered into `articles/`. ### pkgdown 2.0.0 and Bootstrap 5 @@ -82,9 +80,9 @@ Then learn about the many new ways to customise your site in ## In the wild -At last count, pkgdown is used [by over 11,000 +At last count, pkgdown is used [by over 12,000 packages](https://github.com/search?q=path%3A_pkgdown.yml+language%3AYAML&type=code&l=YAML). -Here are a few examples created by contributors to pkgdown: +Here are a few examples: - [bayesplot](http://mc-stan.org/bayesplot/index.html) ([source](https://github.com/stan-dev/bayesplot/tree/gh-pages)): @@ -103,6 +101,9 @@ Here are a few examples created by contributors to pkgdown: ([source](https://github.com/renozao/NMF)): a framework to perform non-negative matrix factorization (NMF). +- [tidyverse and r-lib packages + source](https://github.com/search?q=path%3A%22_pkgdown.yml%22+AND+%28org%3Atidyverse+OR+org%3Ar-lib%29&type=code) + Comparing the source and output of these sites is a great way to learn new pkgdown techniques. @@ -111,3 +112,6 @@ new pkgdown techniques. Please note that this project is released with a [Contributor Code of Conduct](https://pkgdown.r-lib.org/CODE_OF_CONDUCT.html). By participating in this project you agree to abide by its terms. + +[^1]: If you don’t use GitHub, you can use `usethis::use_pkgdown()` + + `pkgdown::build_site()` to create a website. diff --git a/man/build_articles.Rd b/man/build_articles.Rd index f50c58a38..e1d92d88e 100644 --- a/man/build_articles.Rd +++ b/man/build_articles.Rd @@ -227,8 +227,8 @@ Additionally, htmlwidgets do not work when \code{as_is: true}. } \section{Suppressing vignettes}{ -If you want articles that are not vignettes, either put them in -subdirectories or list in \code{.Rbuildignore}. An articles link will be +If you want \href{https://r-pkgs.org/vignettes.html#sec-vignettes-article}{articles} +that are not vignettes, use \code{usethis::use_article()} to create it. 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 \code{\link[=build_site]{build_site()}} details. @@ -257,3 +257,11 @@ that will be available to custom graphics output devices such as HTML widgets. } +\seealso{ +Other site components: +\code{\link{build_home}()}, +\code{\link{build_news}()}, +\code{\link{build_reference}()}, +\code{\link{build_tutorials}()} +} +\concept{site components} diff --git a/man/build_favicons.Rd b/man/build_favicons.Rd index 245393ebf..678f60cfd 100644 --- a/man/build_favicons.Rd +++ b/man/build_favicons.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/build-favicons.R \name{build_favicons} \alias{build_favicons} -\title{Create favicons from package logo} +\title{Initialise favicons from package logo} \usage{ build_favicons(pkg = ".", overwrite = FALSE) } @@ -13,15 +13,14 @@ build_favicons(pkg = ".", overwrite = FALSE) } \description{ This function auto-detects the location of your package logo (with the name -\code{logo.svg} (recommended format) or \code{logo.png}) and runs it through the -\url{https://realfavicongenerator.net} API to build a complete set of favicons -with different sizes, as needed for modern web usage. -} -\details{ +\code{logo.svg} (recommended format) or \code{logo.png}, created with \code{usethis::use_logo()}) +and runs it through the \url{https://realfavicongenerator.net} API to build a +complete set of favicons with different sizes, as needed for modern web usage. + You only need to run the function once. The favicon set will be stored in \code{pkgdown/favicon} and copied by \code{\link[=init_site]{init_site()}} to the relevant location when the website is rebuilt. Once complete, you should add \verb{pkgdown/} to \code{.Rbuildignore } to avoid a NOTE -during package checking. +during package checking. (\code{usethis::use_logo()} does this for you!) } diff --git a/man/build_home.Rd b/man/build_home.Rd index a06f06596..224f4b5c6 100644 --- a/man/build_home.Rd +++ b/man/build_home.Rd @@ -1,25 +1,25 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/build-home-index.R, R/build-home.R -\name{build_home_index} -\alias{build_home_index} +% Please edit documentation in R/build-home.R, R/build-home-index.R +\name{build_home} \alias{build_home} +\alias{build_home_index} \title{Build home section} \usage{ -build_home_index(pkg = ".", quiet = TRUE) - build_home(pkg = ".", override = list(), preview = NA, quiet = TRUE) + +build_home_index(pkg = ".", quiet = TRUE) } \arguments{ \item{pkg}{Path to package.} -\item{quiet}{Set to \code{FALSE} to display output of knitr and -pandoc. This is useful when debugging.} - \item{override}{An optional named list used to temporarily override values in \verb{_pkgdown.yml}} \item{preview}{If \code{TRUE}, or \code{is.na(preview) && interactive()}, will preview freshly generated section in browser.} + +\item{quiet}{Set to \code{FALSE} to display output of knitr and +pandoc. This is useful when debugging.} } \description{ \code{build_home()} function generates pages at the top-level of the site @@ -292,3 +292,11 @@ Or completely remove it: }\if{html}{\out{}} } +\seealso{ +Other site components: +\code{\link{build_articles}()}, +\code{\link{build_news}()}, +\code{\link{build_reference}()}, +\code{\link{build_tutorials}()} +} +\concept{site components} diff --git a/man/build_news.Rd b/man/build_news.Rd index 4da4a3196..73f2d24f7 100644 --- a/man/build_news.Rd +++ b/man/build_news.Rd @@ -81,4 +81,11 @@ Suppress the default addition of CRAN release dates with: \seealso{ \href{https://style.tidyverse.org/news.html}{Tidyverse style for News} + +Other site components: +\code{\link{build_articles}()}, +\code{\link{build_home}()}, +\code{\link{build_reference}()}, +\code{\link{build_tutorials}()} } +\concept{site components} diff --git a/man/build_reference.Rd b/man/build_reference.Rd index 064a413fb..93742339b 100644 --- a/man/build_reference.Rd +++ b/man/build_reference.Rd @@ -133,7 +133,7 @@ or \code{sass::font_face} (topic name). deprecated. } -All functions (except for \code{has_keywords()}) automatically exclude internal +All functions (except for \code{has_keyword()}) automatically exclude internal topics (i.e. those with \verb{\\keyword\{internal\}}). You can choose to include with (e.g.) \code{starts_with("build_", internal = TRUE)}. @@ -189,3 +189,11 @@ that will be available to custom graphics output devices such as HTML widgets. } +\seealso{ +Other site components: +\code{\link{build_articles}()}, +\code{\link{build_home}()}, +\code{\link{build_news}()}, +\code{\link{build_tutorials}()} +} +\concept{site components} diff --git a/man/build_site.Rd b/man/build_site.Rd index 894edcf54..6b79760bc 100644 --- a/man/build_site.Rd +++ b/man/build_site.Rd @@ -88,7 +88,7 @@ whole site. It specifies where the site will be published and is used to allow other pkgdown sites to link to your site when needed (\code{vignette("linking")}), generate a \code{sitemap.xml}, automatically generate a \code{CNAME} when -\link[=deploy_site_github]{deploying to github}, generate the metadata needed +\link[=build_site_github_pages]{deploying to github}, generate the metadata needed rich social "media cards" (\code{vignette("metadata")}), and more. \item \code{title} overrides the default site title, which is the package name. It's used in the page title and default navbar. diff --git a/man/build_tutorials.Rd b/man/build_tutorials.Rd index 1d7abe923..cebe6612f 100644 --- a/man/build_tutorials.Rd +++ b/man/build_tutorials.Rd @@ -43,3 +43,11 @@ section. This should be a list where each element specifies: }\if{html}{\out{}} } +\seealso{ +Other site components: +\code{\link{build_articles}()}, +\code{\link{build_home}()}, +\code{\link{build_news}()}, +\code{\link{build_reference}()} +} +\concept{site components} diff --git a/man/init_site.Rd b/man/init_site.Rd index 7d638ddf6..5e0638c91 100644 --- a/man/init_site.Rd +++ b/man/init_site.Rd @@ -22,7 +22,7 @@ See \code{vignette("customise")} for the various ways you can customise the display of your site. } \section{Build-ignored files}{ -We recommend using \code{\link[usethis:use_pkgdown]{usethis::use_pkgdown()}} to build-ignore \verb{docs/} and +We recommend using \code{\link[usethis:use_pkgdown]{usethis::use_pkgdown_github_pages()}} to build-ignore \verb{docs/} and \verb{_pkgdown.yml}. If use another directory, or create the site manually, you'll need to add them to \code{.Rbuildignore} yourself. A \code{NOTE} about an unexpected file during \verb{R CMD CHECK} is an indication you have not diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 0833a5941..f47693756 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -9,9 +9,9 @@ authors: Maëlle Salmon: href: https://masalmon.eu Hadley Wickham: - href: http://hadley.nz + href: https://hadley.nz Posit Software, PBC: - href: https://www.posit.co + href: https://posit.co template: bootstrap: 5 @@ -51,21 +51,21 @@ articles: reference: - title: Build - + - subtitle: Build the complete site contents: - build_site - clean_site - preview_site - pkgdown_sitrep - + - subtitle: Build part of a site desc: These functions are useful for rapid iteration when you're working on a specific part of your site. contents: - - starts_with("build_") - - -build_site - - -build_site_github_pages + - has_concept("site components") + - build_search + - build_redirects - init_site - subtitle: Customisation @@ -85,6 +85,7 @@ reference: - as_pkgdown - in_pkgdown - render_page + - build_favicons - title: Regression tests contents: diff --git a/vignettes/pkgdown.Rmd b/vignettes/pkgdown.Rmd index 9cfdaee51..643dda46f 100644 --- a/vignettes/pkgdown.Rmd +++ b/vignettes/pkgdown.Rmd @@ -10,21 +10,24 @@ vignette: > --- The goal of pkgdown is to make it easy to make an elegant and useful package website with a minimum of work. -You can get a basic website up and running in just a couple of minutes: +You can get a basic website up and running in just a couple of minutes. If you're using GitHub, we recommend setting up pkgdown and GitHub actions to automatically build and publish your site: ```{r, eval = FALSE} -# Run once to configure package to use pkgdown -usethis::use_pkgdown() -# Run to build the website -pkgdown::build_site() +# Run this once to publish your site regularly +usethis::use_pkgdown_github_pages() ``` -If you're using GitHub, we also recommend setting up GitHub actions to automatically build and publish your site: +If you are not using GitHub, you will have to run `pkgdown::build_site()` manually everytime you want to update the site. ```{r, eval = FALSE} -usethis::use_pkgdown_github_pages() +# Run once +# Remove docs/ from gitignore to ensure it is checked into git. +usethis::use_pkgdown() +# Run everytime you want to update your site +pkgdown::build_site() ``` + While you'll get a decent website without any additional work, if you want a website that really pops, you'll need to read the rest of this vignette. It starts by showing you how to configure pkgdown with a `_pkgdown.yml`. You'll learn about the main components of the site (the home page, reference, articles, and news), and then how to publish and promote your site. @@ -105,7 +108,7 @@ reference: Note the use of `starts_with()` to select all functions with a common prefix. You can also use `ends_with()` and `matches()`. -See complete details in `?build_reference`. +See complete details in `?build_reference`, including other topic matching helper functions. While iterating on the reference index you might want to run `pkgdown::build_reference_index()`. It just re-builds the index page, making it faster to quickly change `_pkgdown.yml` and see how it affects your site. @@ -113,11 +116,12 @@ It just re-builds the index page, making it faster to quickly change `_pkgdown.y ## Articles pkgdown will automatically build all vignettes found in `vignettes/`, translating them to HTML files in `articles/`. -Due to the way that pkgdown has to integrate RMarkdown generated HTML with its own HTML, relatively little control is available over the output format. +It is recommended to name your intro article with your package name to generate a Get Started page automatically. + +Due to the way that pkgdown has to integrate R Markdown generated HTML with its own HTML, relatively little control is available over the output format. You can see the details in `?build_articles`. -If you want to include an article on the website but not in the package (e.g., because it's large), you can either place it in a subdirectory of `vignettes/` (e.g. `vignettes/web_only`) or add it to `.Rbuildignore` (and make sure that there's no `vignettes:` section in the yaml header). -In the extreme case where you want to produce only articles but not vignettes, you should add the complete `vignettes/` directory to `.Rbuildignore` and ensure that DESCRIPTION does not have a `VignetteBuilder` field. +If you want to include an [article](https://r-pkgs.org/website.html#non-vignette-articles) on the website but not in the package (e.g., because it's large), you can use `usethis::use_article()` to set it up. ## News @@ -145,12 +149,9 @@ See `?build_news` for more customisation options including how to: ## Publishing -If you use GitHub, there are two ways to publish your site on GitHub Pages: - -- Build the site locally, check in the docs directory, then configure GitHub Pages to [use that directory](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site). - -- Use GitHub actions to automatically build and publish the site every time you make a change. - The easiest way to set this up is to run `usethis::use_pkgdown_github_pages()`. +If you use GitHub, the easiest way to build and publish your site is via GitHub actions. +Using GitHub actions automatically builds and publishes the site every time you make a change. +The easiest way to set this up is to run `usethis::use_pkgdown_github_pages()`, and if you need to customize the action, see [README.md r-lib/actions](https://github.com/r-lib/actions/tree/v2-branch/examples#build-pkgdown-site). ## Promoting @@ -166,4 +167,4 @@ Once your finalized site is built and published on the web, you should publicize (`usethis::use_pkgdown_github_pages()` does this for you.) -3. On Twitter (make sure to include `#rstats`). +3. On social media (make sure to include `#rstats`). diff --git a/vignettes/translations.Rmd b/vignettes/translations.Rmd index eccb08e04..394825b3f 100644 --- a/vignettes/translations.Rmd +++ b/vignettes/translations.Rmd @@ -92,5 +92,5 @@ Then commit your changes to Git and submit your pull request for review: ```{r} #| eval: false -usethis::pr_submit() +usethis::pr_push() ```