From fb4040eadc92b6bb908365b8452db9809039d40c Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Tue, 23 Apr 2024 08:22:57 -0500 Subject: [PATCH] Eliminate use of child docs in documentation (#2484) The only file that was actually used in multiple places was sidebar-configuration.Rmd, but I don't think it actually belongs in customise.Rmd with navbar and footer because it only affects a single page. Fixes #2367 --- R/build-home.R | 275 +++++++++++++++++- R/build.R | 43 ++- man/build_home.Rd | 121 +++++--- man/build_site.Rd | 41 +-- man/rmd-fragments/authors-configuration.Rmd | 98 ------- man/rmd-fragments/footer-configuration.Rmd | 32 -- man/rmd-fragments/home-configuration.Rmd | 81 ------ man/rmd-fragments/navbar-configuration.Rmd | 94 ------ man/rmd-fragments/redirects-configuration.Rmd | 14 - man/rmd-fragments/sidebar-configuration.Rmd | 63 ---- vignettes/customise.Rmd | 128 +++++++- 11 files changed, 516 insertions(+), 474 deletions(-) delete mode 100644 man/rmd-fragments/authors-configuration.Rmd delete mode 100644 man/rmd-fragments/footer-configuration.Rmd delete mode 100644 man/rmd-fragments/home-configuration.Rmd delete mode 100644 man/rmd-fragments/navbar-configuration.Rmd delete mode 100644 man/rmd-fragments/redirects-configuration.Rmd delete mode 100644 man/rmd-fragments/sidebar-configuration.Rmd diff --git a/R/build-home.R b/R/build-home.R index b726e782c..ad10e8b72 100644 --- a/R/build-home.R +++ b/R/build-home.R @@ -14,15 +14,278 @@ #' `build_home_index()` rebuilds just the index page; it's useful for rapidly #' iterating when experimenting with site styles. #' -#' ```{r child="man/rmd-fragments/home-configuration.Rmd"} +#' # Home page +#' +#' The main content of the home page (`index.html`) is generated from +#' `pkgdown/index.md`, `index.md`, or `README.md`, in that order. +#' Most packages will use `README.md` because that's also displayed by GitHub +#' and CRAN. Use `index.md` if you want your package website to look +#' different to your README, and use `pkgdown/index.md` if you don't want that +#' file to live in your package root directory. +#' +#' If you use `index.Rmd` or `README.Rmd` it's your responsibility to knit +#' the document to create the corresponding `.md`. pkgdown does not do this +#' for you because it only touches files in the `doc/` directory. +#' +#' Extra markdown files in the base directory (e.g. `ROADMAP.md`) or in +#' `.github/` (e.g. `CODE_OF_CONDUCT.md`) are copied by `build_home()` to `docs/` and converted to HTML. +#' +#' The home page also features a sidebar with information extracted from the +#' package. You can tweak it via the configuration file, to help make the home +#' page an as informative as possible landing page. +#' +#' ## Images and figures +#' +#' If you want to include images in your `README.md`, they must be stored +#' somewhere in the package so that they can be displayed on the CRAN website. +#' The best place to put them is `man/figures`. If you are generating figures +#' with R Markdown, make sure you set up `fig.path` as followed: +#' +#' ``` r +#' knitr::opts_chunk$set( +#' fig.path = "man/figures/" +#' ) #' ``` -#' ```{r child="man/rmd-fragments/authors-configuration.Rmd"} +#' +#' This should usually go in a chunk with `include = FALSE`. +#' +#' ```` markdown +#' ```{r chunk-name, include=FALSE}`r ''` +#' knitr::opts_chunk$set( +#' fig.path = "man/figures/" +#' ) #' ``` -#' -#' @section Sidebar: -#' ```{r child="man/rmd-fragments/sidebar-configuration.Rmd"} +#' ```` +#' +#' ## Package logo +#' +#' If you have a package logo, you can include it at the top of your README +#' in a level-one heading: +#' +#' ``` markdown +#' # pkgdown +#' ``` +#' +#' [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 +#' +#' By default, the page title and description are extracted automatically from +#' the `Title` and `Description` fields `DESCRIPTION` (stripping single quotes +#' off quoted words). CRAN ensures that these fields don't contain phrases +#' like "R package" because that's obvious on CRAN. To make your package more +#' findable on search engines, it's good practice to override the `title` and +#' `description`, thinking about what people might search for: +#' +#' ```yaml +#' home: +#' title: An R package for pool-noodle discovery +#' description: > +#' Do you love R? Do you love pool-noodles? If so, you might enjoy +#' using this package to automatically discover and add pool-noodles +#' to your growing collection. +#' ``` +#' +#' (Note the use of YAML's `>` i.e. "YAML pipes"; this is a convenient way of writing paragraphs of text.) +#' +#' ## Dev badges +#' +#' pkgdown identifies badges in three ways: +#' +#' - Any image-containing links between `` and +#' ``, as e.g. created by `usethis::use_readme_md()` +#' or `usethis::use_readme_rmd()`. There should always be an empty line after +#' the `` line. If you divide badges into paragraphs, +#' make sure to add an empty line before the `` line. +#' +#' - Any image-containing links within `
`. +#' +#' - Within the first paragraph, if it only contains image-containing links. +#' +#' Identified badges are **removed** from the _main content_. +#' They are shown or not in the _sidebar_ depending on the development mode and +#' sidebar customization, see the sidebar section. +#' +#' # Authors +#' +#' By default, pkgdown will display author information in three places: +#' +#' * the sidebar, +#' * the left part side of the footer, +#' * the author page. +#' +#' This documentation describes how to customise the overall author display. +#' See `?build_home` and `?build_site` for details about changing the location +#' of the authors information within the home sidebar and the site footer. +#' +#' ## Authors ORCID and bio +#' +#' Author ORCID identification numbers in the `DESCRIPTION` are linked using +#' the ORCID logo: +#' +#' ```r +#' Authors@R: c( +#' person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre"), +#' comment = c(ORCID = "0000-0003-4757-117X") +#' ), +#' person("Jay", "Hesselberth", role = "aut", +#' comment = c(ORCID = "0000-0002-6299-179X") +#' ) +#' ) +#' ``` +#' +#' If you want to add more details about authors or their involvement with the +#' package, you can use the comment field, which will be rendered on the +#' authors page. +#' +#' ```r +#' Authors@R: c( +#' person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre"), +#' comment = c(ORCID = "0000-0003-4757-117X", "Indenter-in-chief") +#' ), +#' person("Jay", "Hesselberth", role = "aut", +#' comment = c(ORCID = "0000-0002-6299-179X") +#' ) +#' ) +#' ``` +#' +#' ## YAML config - authors +#' +#' You can tweak a few things 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: +#' +#' * If `href` is provided, the author's name will be linked to this URL. +#' * If `html` is provided, it will be shown instead of the author's name. +#' This is particularly useful if you want to display the logo of a corporate +#' sponsor. Use an absolute URL to an image, not a relative link. Use an empty +#' alternative text rather than no alternative text so a screen-reader would +#' skip over it. +#' +#' ```yaml +#' authors: +#' firstname lastname: +#' href: "http://name-website.com" +#' html: "" +#' ``` +#' +#' +#' By default, the "developers" list shown in the sidebar and footer is +#' populated by the maintainer ("cre"), authors ("aut"), and funder ("fnd") +#' from the `DESCRIPTION`. You could choose other roles for filtering. +#' With the configuration below: +#' +#' * only the maintainer and funder(s) appear in the footer, after the text +#' "Crafted by", +#' * all authors and contributors appear in the sidebar, +#' * the authors list on the sidebar is preceded and followed by some text, +#' * the authors list on the authors page is preceded and followed by some text. +#' +#' +#' ```yaml +#' authors: +#' footer: +#' roles: [cre, fnd] +#' text: "Crafted by" +#' sidebar: +#' roles: [aut, ctb] +#' before: "So *who* does the work?" +#' after: "Thanks all!" +#' before: "This package is proudly brought to you by:" +#' after: "See the [changelog](news/index.html) for other contributors. :pray:" +#' ``` +#' +#' If you want to filter authors based on something else than their roles, +#' consider using a custom sidebar/footer component +#' (see `?build_home`/`?build_site`, respectively). +#' +#' # Sidebar +#' +#' You can customise the homepage sidebar with the `home.sidebar` field. +#' It's made up of two pieces: `structure`, which defines the overall layout, +#' and `components`, which defines what each piece looks like. This organisation +#' makes it easy to mix and match the pkgdown defaults with your own +#' customisations. +#' +#' This is the default structure: +#' +#' ``` yaml +#' home: +#' sidebar: +#' structure: [links, license, community, citation, authors, dev] +#' ``` +#' +#' These are drawn from seven built-in components: +#' +#' - `links`: automated links generated from `URL` and `BugReports` fields +#' from `DESCRIPTION` plus manual links from the `home.links` field: +#' +#' ``` yaml +#' home: +#' links: +#' - text: Link text +#' href: https://website.com +#' - text: Roadmap +#' href: /roadmap.html +#' ``` +#' +#' - `license`: Licensing information if `LICENSE`/`LICENCE` or +#' `LICENSE.md`/`LICENCE.md` files are present. +#' +#' - `community`: links to to `.github/CONTRIBUTING.md`, +#' `.github/CODE_OF_CONDUCT.md`, etc. +#' +#' - `citation`: link to package citation information. Uses either +#' `inst/CITATION` or, if absent, information from the `DESCRIPTION`. +#' +#' - `authors`: selected authors from the `DESCRIPTION`. +#' +#' - `dev`: development status badges extracted from `README.md`/`index.md`. +#' This is only shown for "development" versions of websites; see +#' "Development mode" in `?build_site` for details. +#' +#' - `toc`: a table of contents for the README (not shown by default). +#' +#' You can also add your own components, where `text` is markdown text: +#' +#' ``` yaml +#' home: +#' sidebar: +#' structure: [authors, custom, toc, dev] +#' components: +#' custom: +#' title: Funding +#' text: We are *grateful* for funding! +#' ``` +#' +#' Alternatively, you can provide a ready-made sidebar HTML: +#' +#' ``` yaml +#' home: +#' sidebar: +#' html: path-to-sidebar.html +#' ``` +#' +#' Or completely remove it: +#' +#' ``` yaml +#' home: +#' sidebar: FALSE #' ``` -#' #' @inheritParams build_articles #' @export build_home <- function(pkg = ".", diff --git a/R/build.R b/R/build.R index 3206e05a0..470abe7ed 100644 --- a/R/build.R +++ b/R/build.R @@ -14,7 +14,7 @@ #' that aspect of the site. This page documents options that affect the #' whole site. #' -#' @section General config: +#' # General config #' * `destination` controls where the site will be generated, defaulting to #' `docs/`. Paths are relative to the package root. #' @@ -33,6 +33,17 @@ #' * `title` overrides the default site title, which is the package name. #' It's used in the page title and default navbar. #' +#' # Navbar and footer +#' +#' The `navbar` and `footer` fields control the appearance of the navbar +#' 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")`. +#' #' @section 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 @@ -122,17 +133,6 @@ #' to danger). Finally, you can choose to override the default tooltip with #' `version_tooltip`. #' -#' ## Page layout -#' -#' The `navbar`, `footer`, and `sidebar` fields control the appearance -#' of the navbar, footer, and sidebar respectively. They have many individual -#' options which are documented in the **Layout** section of -#' `vignette("customise")`. -#' -#' @section Search: -#' The `search` field controls the built-in search and is -#' documented in `vignette("search")`. -#' #' @section Template: #' The `template` field is mostly used to control the appearance of the site. #' See `vignette("customise")` for details. @@ -275,8 +275,25 @@ #' ``` #' #' @section Redirects: -#' ```{r child="man/rmd-fragments/redirects-configuration.Rmd"} +#' 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`. #' #' @section Options: #' Users with limited internet connectivity can disable CRAN checks by setting diff --git a/man/build_home.Rd b/man/build_home.Rd index a58304180..6c5224112 100644 --- a/man/build_home.Rd +++ b/man/build_home.Rd @@ -37,22 +37,29 @@ including: iterating when experimenting with site styles. } \section{Home page}{ -The main content of the home page (\code{index.html}) is generated from \code{pkgdown/index.md}, \code{index.md}, or \code{README.md}, in that order. -Most packages will use \code{README.md} because that's also displayed by GitHub and CRAN. -Use \code{index.md} if you want your package website to look different to your README, and use \code{pkgdown/index.md} if you don't want that file to live in your package root directory. - -If you use \code{index.Rmd} or \code{README.Rmd} it's your responsibility to knit the document to create the corresponding \code{.md}. -pkgdown does not do this for you because it only touches files in the \verb{doc/} directory. - -Extra markdown files in the base directory (e.g. \code{ROADMAP.md}) or in \verb{.github/} (e.g. \code{CODE_OF_CONDUCT.md}) are copied by \code{build_home()} to \verb{docs/} and converted to HTML. - -The home page also features a sidebar with information extracted from the package. -You can tweak it via the configuration file, to help make the home page an as informative as possible landing page. +The main content of the home page (\code{index.html}) is generated from +\code{pkgdown/index.md}, \code{index.md}, or \code{README.md}, in that order. +Most packages will use \code{README.md} because that's also displayed by GitHub +and CRAN. Use \code{index.md} if you want your package website to look +different to your README, and use \code{pkgdown/index.md} if you don't want that +file to live in your package root directory. + +If you use \code{index.Rmd} or \code{README.Rmd} it's your responsibility to knit +the document to create the corresponding \code{.md}. pkgdown does not do this +for you because it only touches files in the \verb{doc/} directory. + +Extra markdown files in the base directory (e.g. \code{ROADMAP.md}) or in +\verb{.github/} (e.g. \code{CODE_OF_CONDUCT.md}) are copied by \code{build_home()} to \verb{docs/} and converted to HTML. + +The home page also features a sidebar with information extracted from the +package. You can tweak it via the configuration file, to help make the home +page an as informative as possible landing page. \subsection{Images and figures}{ -If you want to include images in your \code{README.md}, they must be stored somewhere in the package so that they can be displayed on the CRAN website. -The best place to put them is \code{man/figures}. -If you are generating figures with R Markdown, make sure you set up \code{fig.path} as followed: +If you want to include images in your \code{README.md}, they must be stored +somewhere in the package so that they can be displayed on the CRAN website. +The best place to put them is \code{man/figures}. If you are generating figures +with R Markdown, make sure you set up \code{fig.path} as followed: \if{html}{\out{
}}\preformatted{knitr::opts_chunk$set( fig.path = "man/figures/" @@ -61,7 +68,7 @@ If you are generating figures with R Markdown, make sure you set up \code{fig.pa This should usually go in a chunk with \code{include = FALSE}. -\if{html}{\out{
}}\preformatted{```\{r chunk-name, include=FALSE\} +\if{html}{\out{
}}\preformatted{```\{r chunk-name, include=FALSE\}`r ''` knitr::opts_chunk$set( fig.path = "man/figures/" ) @@ -71,7 +78,8 @@ knitr::opts_chunk$set( \subsection{Package logo}{ -If you have a package logo, you can include it at the top of your README in a level-one heading: +If you have a package logo, you can include it at the top of your README +in a level-one heading: \if{html}{\out{
}}\preformatted{# pkgdown }\if{html}{\out{
}} @@ -81,12 +89,16 @@ If you have a package logo, you can include it at the top of your README in a le \subsection{YAML config - home}{ -To tweak the home page, you need a section of the configuration file called \code{home}. +To tweak the home page, you need a section of the configuration file called +\code{home}. \subsection{Page title and description}{ -By default, the page title and description are extracted automatically from the \code{Title} and \code{Description} fields \code{DESCRIPTION} (stripping single quotes off quoted words). -CRAN ensures that these fields don't contain phrases like "R package" because that's obvious on CRAN. -To make your package more findable on search engines, it's good practice to override the \code{title} and \code{description}, thinking about what people might search for: +By default, the page title and description are extracted automatically from +the \code{Title} and \code{Description} fields \code{DESCRIPTION} (stripping single quotes +off quoted words). CRAN ensures that these fields don't contain phrases +like "R package" because that's obvious on CRAN. To make your package more +findable on search engines, it's good practice to override the \code{title} and +\code{description}, thinking about what people might search for: \if{html}{\out{
}}\preformatted{home: title: An R package for pool-noodle discovery @@ -105,15 +117,18 @@ To make your package more findable on search engines, it's good practice to over pkgdown identifies badges in three ways: \itemize{ -\item Any image-containing links between \verb{} and \verb{}, as e.g. created by \code{usethis::use_readme_md()} or \code{usethis::use_readme_rmd()}. -There should always be an empty line after the \verb{} line. -If you divide badges into paragraphs, make sure to add an empty line before the \verb{} line. +\item Any image-containing links between \verb{} and +\verb{}, as e.g. created by \code{usethis::use_readme_md()} +or \code{usethis::use_readme_rmd()}. There should always be an empty line after +the \verb{} line. If you divide badges into paragraphs, +make sure to add an empty line before the \verb{} line. \item Any image-containing links within \verb{
}. \item Within the first paragraph, if it only contains image-containing links. } Identified badges are \strong{removed} from the \emph{main content}. -They are shown or not in the \emph{sidebar} depending on the development mode and sidebar customization, see the sidebar section. +They are shown or not in the \emph{sidebar} depending on the development mode and +sidebar customization, see the sidebar section. } } @@ -125,10 +140,13 @@ By default, pkgdown will display author information in three places: \item the author page. } -This documentation describes how to customise the overall author display. See \code{?build_home} and \code{?build_site} for details about changing the location of the authors information within the home sidebar and the site footer. +This documentation describes how to customise the overall author display. +See \code{?build_home} and \code{?build_site} for details about changing the location +of the authors information within the home sidebar and the site footer. \subsection{Authors ORCID and bio}{ -Author ORCID identification numbers in the \code{DESCRIPTION} are linked using the ORCID logo: +Author ORCID identification numbers in the \code{DESCRIPTION} are linked using +the ORCID logo: \if{html}{\out{
}}\preformatted{Authors@R: c( person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre"), @@ -140,8 +158,9 @@ Author ORCID identification numbers in the \code{DESCRIPTION} are linked using t ) }\if{html}{\out{
}} -If you want to add more details about authors or their involvement with the package, -you can use the comment field, which will be rendered on the authors page. +If you want to add more details about authors or their involvement with the +package, you can use the comment field, which will be rendered on the +authors page. \if{html}{\out{
}}\preformatted{Authors@R: c( person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre"), @@ -165,18 +184,16 @@ You can tweak a few things via the \code{authors} YAML field: \item text before and after authors on the authors page. } -You can modify how each author's name is displayed -by adding a subsection for \code{authors}. -Each entry in \code{authors} should be named -with the author's name (matching \code{DESCRIPTION}) -and can contain \code{href} and/or \code{html} fields: +You can modify how each author's name is displayed by adding a subsection +for \code{authors}. Each entry in \code{authors} should be named the author's name +(matching \code{DESCRIPTION}) and can contain \code{href} and/or \code{html} fields: \itemize{ \item If \code{href} is provided, the author's name will be linked to this URL. \item If \code{html} is provided, it will be shown instead of the author's name. This is particularly useful if you want to display the logo of a corporate -sponsor. Use an absolute URL to an image, not a relative link. -Use an empty alternative text rather than no alternative text so a screen-reader -would skip over it. +sponsor. Use an absolute URL to an image, not a relative link. Use an empty +alternative text rather than no alternative text so a screen-reader would +skip over it. } \if{html}{\out{
}}\preformatted{authors: @@ -185,12 +202,13 @@ would skip over it. html: "" }\if{html}{\out{
}} -By default, the "developers" list shown in the sidebar and footer is populated by the maintainer ("cre"), authors -("aut"), and funder ("fnd") from the \code{DESCRIPTION}. -You could choose other roles for filtering. +By default, the "developers" list shown in the sidebar and footer is +populated by the maintainer ("cre"), authors ("aut"), and funder ("fnd") +from the \code{DESCRIPTION}. You could choose other roles for filtering. With the configuration below: \itemize{ -\item only the maintainer and funder(s) appear in the footer, after the text "Crafted by", +\item only the maintainer and funder(s) appear in the footer, after the text +"Crafted by", \item all authors and contributors appear in the sidebar, \item the authors list on the sidebar is preceded and followed by some text, \item the authors list on the authors page is preceded and followed by some text. @@ -215,10 +233,11 @@ consider using a custom sidebar/footer component } \section{Sidebar}{ - You can customise the homepage sidebar with the \code{home.sidebar} field. -It's made up of two pieces: \code{structure}, which defines the overall layout, and \code{components}, which defines what each piece looks like. -This organisation makes it easy to mix and match the pkgdown defaults with your own customisations. +It's made up of two pieces: \code{structure}, which defines the overall layout, +and \code{components}, which defines what each piece looks like. This organisation +makes it easy to mix and match the pkgdown defaults with your own +customisations. This is the default structure: @@ -229,7 +248,8 @@ This is the default structure: These are drawn from seven built-in components: \itemize{ -\item \code{links}: automated links generated from \code{URL} and \code{BugReports} fields from \code{DESCRIPTION} plus manual links from the \code{home.links} field: +\item \code{links}: automated links generated from \code{URL} and \code{BugReports} fields +from \code{DESCRIPTION} plus manual links from the \code{home.links} field: \if{html}{\out{
}}\preformatted{home: links: @@ -238,11 +258,16 @@ These are drawn from seven built-in components: - text: Roadmap href: /roadmap.html }\if{html}{\out{
}} -\item \code{license}: Licensing information if \code{LICENSE}/\code{LICENCE} or \code{LICENSE.md}/\code{LICENCE.md} files are present. -\item \code{community}: links to to \code{.github/CONTRIBUTING.md}, \code{.github/CODE_OF_CONDUCT.md}, etc. -\item \code{citation}: link to package citation information. Uses either \code{inst/CITATION} or, if absent, information from the \code{DESCRIPTION}. +\item \code{license}: Licensing information if \code{LICENSE}/\code{LICENCE} or +\code{LICENSE.md}/\code{LICENCE.md} files are present. +\item \code{community}: links to to \code{.github/CONTRIBUTING.md}, +\code{.github/CODE_OF_CONDUCT.md}, etc. +\item \code{citation}: link to package citation information. Uses either +\code{inst/CITATION} or, if absent, information from the \code{DESCRIPTION}. \item \code{authors}: selected authors from the \code{DESCRIPTION}. -\item \code{dev}: development status badges extracted from \code{README.md}/\code{index.md}. This is only shown for "development" versions of websites; see "Development mode" in \code{?build_site} for details. +\item \code{dev}: development status badges extracted from \code{README.md}/\code{index.md}. +This is only shown for "development" versions of websites; see +"Development mode" in \code{?build_site} for details. \item \code{toc}: a table of contents for the README (not shown by default). } diff --git a/man/build_site.Rd b/man/build_site.Rd index 5b3d89fca..4d104d0c0 100644 --- a/man/build_site.Rd +++ b/man/build_site.Rd @@ -76,7 +76,6 @@ that aspect of the site. This page documents options that affect the whole site. } \section{General config}{ - \itemize{ \item \code{destination} controls where the site will be generated, defaulting to \verb{docs/}. Paths are relative to the package root. @@ -95,6 +94,17 @@ It's used in the page title and default navbar. } } +\section{Navbar and footer}{ +The \code{navbar} and \code{footer} fields control the appearance of the navbar +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 @@ -181,20 +191,6 @@ theme, but become progressively more eye catching as you go from default to danger). Finally, you can choose to override the default tooltip with \code{version_tooltip}. } - -\subsection{Page layout}{ - -The \code{navbar}, \code{footer}, and \code{sidebar} fields control the appearance -of the navbar, footer, and sidebar respectively. They have many individual -options which are documented in the \strong{Layout} section of -\code{vignette("customise")}. -} -} - -\section{Search}{ - -The \code{search} field controls the built-in search and is -documented in \code{vignette("search")}. } \section{Template}{ @@ -338,11 +334,15 @@ time (e.g. because behind a firewall or requires auth). \section{Redirects}{ -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. +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. +The syntax is the following, with old paths on the left, and new paths or +URLs on the right. \if{html}{\out{
}}\preformatted{redirects: - ["articles/old-vignette-name.html", "articles/new-vignette-name.html"] @@ -350,7 +350,8 @@ The syntax is the following, with old paths on the left, and new paths or URLs o - ["articles/yet-another-old-vignette-name.html", "https://pkgdown.r-lib.org/dev"] }\if{html}{\out{
}} -If for some reason you choose to redirect an existing page make sure to exclude it from the search index, see \code{?build_search}. +If for some reason you choose to redirect an existing page make sure to +exclude it from the search index, see \code{?build_search}. } \section{Options}{ diff --git a/man/rmd-fragments/authors-configuration.Rmd b/man/rmd-fragments/authors-configuration.Rmd deleted file mode 100644 index 5b45a382f..000000000 --- a/man/rmd-fragments/authors-configuration.Rmd +++ /dev/null @@ -1,98 +0,0 @@ -# Authors - -By default, pkgdown will display author information in three places: - -* the sidebar, -* the left part side of the footer, -* the author page. - -This documentation describes how to customise the overall author display. See `?build_home` and `?build_site` for details about changing the location of the authors information within the home sidebar and the site footer. - -## Authors ORCID and bio - -Author ORCID identification numbers in the `DESCRIPTION` are linked using the ORCID logo: - -```r -Authors@R: c( - person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre"), - comment = c(ORCID = "0000-0003-4757-117X") - ), - person("Jay", "Hesselberth", role = "aut", - comment = c(ORCID = "0000-0002-6299-179X") - ) - ) -``` - -If you want to add more details about authors or their involvement with the package, -you can use the comment field, which will be rendered on the authors page. - -```r -Authors@R: c( - person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre"), - comment = c(ORCID = "0000-0003-4757-117X", "Indenter-in-chief") - ), - person("Jay", "Hesselberth", role = "aut", - comment = c(ORCID = "0000-0002-6299-179X") - ) - ) -``` - -## YAML config - authors - -You can tweak a few things 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 -with the author's name (matching `DESCRIPTION`) -and can contain `href` and/or `html` fields: - -* If `href` is provided, the author's name will be linked to this URL. -* If `html` is provided, it will be shown instead of the author's name. - This is particularly useful if you want to display the logo of a corporate - sponsor. Use an absolute URL to an image, not a relative link. - Use an empty alternative text rather than no alternative text so a screen-reader - would skip over it. - -```yaml -authors: - firstname lastname: - href: "http://name-website.com" - html: "" -``` - - -By default, the "developers" list shown in the sidebar and footer is populated by the maintainer ("cre"), authors -("aut"), and funder ("fnd") from the `DESCRIPTION`. -You could choose other roles for filtering. -With the configuration below: - -* only the maintainer and funder(s) appear in the footer, after the text "Crafted by", -* all authors and contributors appear in the sidebar, -* the authors list on the sidebar is preceded and followed by some text, -* the authors list on the authors page is preceded and followed by some text. - - -```yaml -authors: - footer: - roles: [cre, fnd] - text: "Crafted by" - sidebar: - roles: [aut, ctb] - before: "So *who* does the work?" - after: "Thanks all!" - before: "This package is proudly brought to you by:" - after: "See the [changelog](news/index.html) for other contributors. :pray:" -``` - -If you want to filter authors based on something else than their roles, -consider using a custom sidebar/footer component -(see `?build_home`/`?build_site`, respectively). diff --git a/man/rmd-fragments/footer-configuration.Rmd b/man/rmd-fragments/footer-configuration.Rmd deleted file mode 100644 index 900339f7e..000000000 --- a/man/rmd-fragments/footer-configuration.Rmd +++ /dev/null @@ -1,32 +0,0 @@ -You can customise the footer with the `footer` field. -It's made up of two pieces: `structure`, which defines the overall layout, and `components`, which defines what each piece looks like. -This organisation makes it easy to mix and match the pkgdown defaults with your own customisations. - -This is the default structure: - -``` yaml -footer: - structure: - left: developed_by - right: built_with -``` - -Which uses two of the three built-in components: - -- `developed_by`, a sentence describing the main authors of the package. (See `?build_home` if you want to tweak *which* authors appear in the footer.) -- `built_with`, a sentence advertising pkgdown. -- `package`, the name of the package. - -You can override these defaults with the `footer` field. -The example below puts the authors' information on the right along with a legal disclaimer, and puts the pkgdown link on the left. - -``` yaml -footer: - structure: - left: pkgdown - right: [developed_by, legal] - components: - legal: Provided without **any warranty**. -``` - -Each side is pasted into a single string (separated by `" "`) and then converted from markdown to HTML. diff --git a/man/rmd-fragments/home-configuration.Rmd b/man/rmd-fragments/home-configuration.Rmd deleted file mode 100644 index 96a6faaa7..000000000 --- a/man/rmd-fragments/home-configuration.Rmd +++ /dev/null @@ -1,81 +0,0 @@ -# Home page - -The main content of the home page (`index.html`) is generated from `pkgdown/index.md`, `index.md`, or `README.md`, in that order. -Most packages will use `README.md` because that's also displayed by GitHub and CRAN. -Use `index.md` if you want your package website to look different to your README, and use `pkgdown/index.md` if you don't want that file to live in your package root directory. - -If you use `index.Rmd` or `README.Rmd` it's your responsibility to knit the document to create the corresponding `.md`. -pkgdown does not do this for you because it only touches files in the `doc/` directory. - -Extra markdown files in the base directory (e.g. `ROADMAP.md`) or in `.github/` (e.g. `CODE_OF_CONDUCT.md`) are copied by `build_home()` to `docs/` and converted to HTML. - -The home page also features a sidebar with information extracted from the package. -You can tweak it via the configuration file, to help make the home page an as informative as possible landing page. - -## Images and figures - -If you want to include images in your `README.md`, they must be stored somewhere in the package so that they can be displayed on the CRAN website. -The best place to put them is `man/figures`. -If you are generating figures with R Markdown, make sure you set up `fig.path` as followed: - -``` r -knitr::opts_chunk$set( - fig.path = "man/figures/" -) -``` - -This should usually go in a chunk with `include = FALSE`. - -```` markdown -```{r chunk-name, include=FALSE}`r ''` -knitr::opts_chunk$set( - fig.path = "man/figures/" -) -``` -```` - -## Package logo - -If you have a package logo, you can include it at the top of your README in a level-one heading: - -``` markdown -# pkgdown -``` - -[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 - -By default, the page title and description are extracted automatically from the `Title` and `Description` fields `DESCRIPTION` (stripping single quotes off quoted words). -CRAN ensures that these fields don't contain phrases like "R package" because that's obvious on CRAN. -To make your package more findable on search engines, it's good practice to override the `title` and `description`, thinking about what people might search for: - -``` yaml -home: - title: An R package for pool-noodle discovery - description: > - Do you love R? Do you love pool-noodles? If so, you might enjoy - using this package to automatically discover and add pool-noodles - to your growing collection. -``` - -(Note the use of YAML's `>` i.e. "YAML pipes"; this is a convenient way of writing paragraphs of text.) - -## Dev badges - -pkgdown identifies badges in three ways: - -- Any image-containing links between `` and ``, as e.g. created by `usethis::use_readme_md()` or `usethis::use_readme_rmd()`. - There should always be an empty line after the `` line. - If you divide badges into paragraphs, make sure to add an empty line before the `` line. - -- Any image-containing links within `
`. - -- Within the first paragraph, if it only contains image-containing links. - -Identified badges are **removed** from the _main content_. -They are shown or not in the _sidebar_ depending on the development mode and sidebar customization, see the sidebar section. diff --git a/man/rmd-fragments/navbar-configuration.Rmd b/man/rmd-fragments/navbar-configuration.Rmd deleted file mode 100644 index 810a5dba9..000000000 --- a/man/rmd-fragments/navbar-configuration.Rmd +++ /dev/null @@ -1,94 +0,0 @@ -You can customise the navigation bar that appears at the top of the page with the `navbar` field. -It's made up of two pieces: `structure`, which defines the overall layout, and `components`, which defines what each piece looks like. -This organisation makes it easy to mix and match pkgdown defaults with your own customisations. - -This is the default structure: - -``` yaml -navbar: - structure: - left: [intro, reference, articles, tutorials, news] - right: [search, github] -``` - -It makes use of the the six built-in components: - -- `intro`: "Get Started", which links to a vignette or article with the same name as the package[^dots]. -- `reference`, if there are any `.Rd` files. -- `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). -- `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 - package `foo.bar` the intro needs to be named `foo-bar.Rmd`. - -You can use the `structure` field to reorganise the navbar without changing the default contents: - -``` yaml -navbar: - structure: - left: [search] - right: [reference, articles] -``` - -You can use `components` to override the default content. -For example, this yaml provides a custom articles menu: - -``` yaml -navbar: - components: - articles: - text: Articles - menu: - - text: Category A - - text: Title A1 - href: articles/a1.html - - text: Title A2 - href: articles/a2.html - - text: ------- - - text: "Category B" - - text: Article B1 - href: articles/b1.html -``` - -Components uses the same syntax as [RMarkdown menus](https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html#site-navigation). -The elements of `menu` can be: - -- A link (`text` + `href`) - -- A heading (just `text`) - -- A separator (`text: ——–`) - -Instead of text, you can also use the name of an `icon`s from [fontawesome](https://fontawesome.com/icons?d=gallery). -You should also provide a textual description in the `aria-label` field for screenreader users. - -To add a new component to the navbar, you need to modify both `structure` and `components`. -For example, the following yaml adds a new "twitter" component that appears to the left of the github icon. - -``` yaml -navbar: - structure: - right: [twitter, github] - components: - twitter: - icon: fa-twitter - href: http://twitter.com/hadleywickham - aria-label: Twitter -``` - -Finally, you can add arbitrary HTML to three locations in the navbar: - -```yaml -template: - includes: - before_title: - after_navbar: -``` - -These includes will appear on all screen sizes, and will not be collapsed into the the navbar drop down. - -You can also customise the colour scheme of the navbar by using the `type` and `bg` parameters. See above for details. diff --git a/man/rmd-fragments/redirects-configuration.Rmd b/man/rmd-fragments/redirects-configuration.Rmd deleted file mode 100644 index 46338ea85..000000000 --- a/man/rmd-fragments/redirects-configuration.Rmd +++ /dev/null @@ -1,14 +0,0 @@ -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`. diff --git a/man/rmd-fragments/sidebar-configuration.Rmd b/man/rmd-fragments/sidebar-configuration.Rmd deleted file mode 100644 index 24196a16d..000000000 --- a/man/rmd-fragments/sidebar-configuration.Rmd +++ /dev/null @@ -1,63 +0,0 @@ -You can customise the homepage sidebar with the `home.sidebar` field. -It's made up of two pieces: `structure`, which defines the overall layout, and `components`, which defines what each piece looks like. -This organisation makes it easy to mix and match the pkgdown defaults with your own customisations. - -This is the default structure: - -``` yaml -home: - sidebar: - structure: [links, license, community, citation, authors, dev] -``` - -These are drawn from seven built-in components: - -- `links`: automated links generated from `URL` and `BugReports` fields from `DESCRIPTION` plus manual links from the `home.links` field: - - ``` yaml - home: - links: - - text: Link text - href: https://website.com - - text: Roadmap - href: /roadmap.html - ``` - -- `license`: Licensing information if `LICENSE`/`LICENCE` or `LICENSE.md`/`LICENCE.md` files are present. - -- `community`: links to to `.github/CONTRIBUTING.md`, `.github/CODE_OF_CONDUCT.md`, etc. - -- `citation`: link to package citation information. Uses either `inst/CITATION` or, if absent, information from the `DESCRIPTION`. - -- `authors`: selected authors from the `DESCRIPTION`. - -- `dev`: development status badges extracted from `README.md`/`index.md`. This is only shown for "development" versions of websites; see "Development mode" in `?build_site` for details. - -- `toc`: a table of contents for the README (not shown by default). - -You can also add your own components, where `text` is markdown text: - -``` yaml -home: - sidebar: - structure: [authors, custom, toc, dev] - components: - custom: - title: Funding - text: We are *grateful* for funding! -``` - -Alternatively, you can provide a ready-made sidebar HTML: - -``` yaml -home: - sidebar: - html: path-to-sidebar.html -``` - -Or completely remove it: - -``` yaml -home: - sidebar: FALSE -``` diff --git a/vignettes/customise.Rmd b/vignettes/customise.Rmd index a2e56aa57..cc56c7021 100644 --- a/vignettes/customise.Rmd +++ b/vignettes/customise.Rmd @@ -215,24 +215,142 @@ Because the navbar is styled with HTML, you'll need to `build_home_index(); init ## Layout {#layout} -You can customise the contents of the navbar, footer, and home page sidebar using the `navbar`, `footer`, and `sidebar` fields. +You can customise the contents of the navbar, footer, using the `navbar` and `footer` fields. +See `?build_home` for how to customise the sidebar on the homepage. They all use a similar structure that separately defines the overall `structure` and the individual `components`. ### Navbar {#navbar-heading} -```{r child="../man/rmd-fragments/navbar-configuration.Rmd"} +You can customise the navigation bar that appears at the top of the page with the `navbar` field. +It's made up of two pieces: `structure`, which defines the overall layout, and `components`, which defines what each piece looks like. +This organisation makes it easy to mix and match pkgdown defaults with your own customisations. + +This is the default structure: + +``` yaml +navbar: + structure: + left: [intro, reference, articles, tutorials, news] + right: [search, github] +``` + +It makes use of the the six built-in components: + +- `intro`: "Get Started", which links to a vignette or article with the same name as the package[^dots]. +- `reference`, if there are any `.Rd` files. +- `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). +- `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 + package `foo.bar` the intro needs to be named `foo-bar.Rmd`. + +You can use the `structure` field to reorganise the navbar without changing the default contents: + +``` yaml +navbar: + structure: + left: [search] + right: [reference, articles] ``` +You can use `components` to override the default content. +For example, this yaml provides a custom articles menu: + +``` yaml +navbar: + components: + articles: + text: Articles + menu: + - text: Category A + - text: Title A1 + href: articles/a1.html + - text: Title A2 + href: articles/a2.html + - text: ------- + - text: "Category B" + - text: Article B1 + href: articles/b1.html +``` + +Components uses the same syntax as [RMarkdown menus](https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html#site-navigation). +The elements of `menu` can be: + +- A link (`text` + `href`) + +- A heading (just `text`) + +- A separator (`text: ——–`) + +Instead of text, you can also use the name of an `icon`s from [fontawesome](https://fontawesome.com/icons?d=gallery). +You should also provide a textual description in the `aria-label` field for screenreader users. + +To add a new component to the navbar, you need to modify both `structure` and `components`. +For example, the following yaml adds a new "twitter" component that appears to the left of the github icon. + +``` yaml +navbar: + structure: + right: [twitter, github] + components: + twitter: + icon: fa-twitter + href: http://twitter.com/hadleywickham + aria-label: Twitter +``` + +Finally, you can add arbitrary HTML to three locations in the navbar: + +```yaml +template: + includes: + before_title: + after_navbar: +``` + +These includes will appear on all screen sizes, and will not be collapsed into the the navbar drop down. + +You can also customise the colour scheme of the navbar by using the `type` and `bg` parameters. See above for details. + ### Footer -```{r child="../man/rmd-fragments/footer-configuration.Rmd"} +You can customise the footer with the `footer` field. +It's made up of two pieces: `structure`, which defines the overall layout, and `components`, which defines what each piece looks like. +This organisation makes it easy to mix and match the pkgdown defaults with your own customisations. + +This is the default structure: + +``` yaml +footer: + structure: + left: developed_by + right: built_with ``` -### Sidebar +Which uses two of the three built-in components: + +- `developed_by`, a sentence describing the main authors of the package. (See `?build_home` if you want to tweak *which* authors appear in the footer.) +- `built_with`, a sentence advertising pkgdown. +- `package`, the name of the package. + +You can override these defaults with the `footer` field. +The example below puts the authors' information on the right along with a legal disclaimer, and puts the pkgdown link on the left. -```{r child = "../man/rmd-fragments/sidebar-configuration.Rmd"} +``` yaml +footer: + structure: + left: pkgdown + right: [developed_by, legal] + components: + legal: Provided without **any warranty**. ``` +Each side is pasted into a single string (separated by `" "`) and then converted from markdown to HTML. + ## Additional HTML and files If you need to include additional HTML, you can add it in the following locations: