Improve reference headings (r-lib#2491)

* Use markdown headings instead of roxygen2 tags
* Tweak heading hierarchy

R/build-articles.R

@@ -19,7 +19,7 @@
 #' package, not the current source version. This makes iteration quicker when
 #' you are primarily working on the text of an article.
 #'
-#' @section Index and navbar:
+#' # Index and navbar
 #' You can control the articles index and navbar with a `articles` field in
 #' your `_pkgdown.yml`. If you use it, pkgdown will check that all articles
 #' are included, and will error if you have missed any.
@@ -77,7 +77,7 @@
 #' the navbar, it will link directly to the articles index instead of
 #' providing a drop-down.
 #'
-#' @section Get started:
+#' # Get started
 #' Note that a vignette with the same name as the package (e.g.,
 #' `vignettes/pkgdown.Rmd` or `vignettes/articles/pkgdown.Rmd`) automatically
 #' becomes a top-level "Get started" link, and will not appear in the articles
@@ -86,7 +86,7 @@
 #' (If your package name includes a `.`, e.g. `pack.down`, use a `-` in the
 #' vignette name, e.g. `pack-down.Rmd`.)
 #'
-#' @section External files:
+#' # External files
 #' pkgdown differs from base R in its handling of external files. When building
 #' vignettes, R assumes that vignettes are self-contained (a reasonable
 #' assumption when most vignettes were PDFs) and only copies files explicitly
@@ -107,7 +107,7 @@
 #' Note that you can not use the `fig.path` to change the output directory of
 #' generated figures as its default value is a strong assumption of rmarkdown.
 #'
-#' @section Embedding Shiny apps:
+#' # Embedding Shiny apps
 #' If you would like to embed a Shiny app into an article, the app will have
 #' to be hosted independently, (e.g. <https://www.shinyapps.io>). Then, you
 #' can embed the app into your article using an `<iframe>`, e.g.
@@ -116,7 +116,7 @@
 #' See <https://github.com/r-lib/pkgdown/issues/838#issuecomment-430473856> for
 #' some hints on how to customise the appearance with CSS.
 #'
-#' @section Output formats:
+#' # Output formats
 #' By default, pkgdown builds all articles using the
 #' [rmarkdown::html_document()] `output` format, ignoring whatever is set in
 #' your YAML metadata. This is necessary because pkgdown has to integrate the
@@ -148,15 +148,15 @@
 #'
 #' Additionally, htmlwidgets do not work when `as_is: true`.
 #'
-#' @inheritSection build_reference Figures
-#'
-#' @section Suppressing vignettes:
+#' # Suppressing vignettes
 #' If you want articles that are not vignettes, either put them in
 #' subdirectories or list in `.Rbuildignore`. 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
+#'
 #' @inheritParams as_pkgdown
 #' @param quiet Set to `FALSE` to display output of knitr and
 #'   pandoc. This is useful when debugging.

R/build-home.R

@@ -68,12 +68,7 @@
 #' 
 #' [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
+#' ## YAML config - title and description
 #' 
 #' By default, the page title and description are extracted automatically from
 #' the `Title` and `Description` fields `DESCRIPTION` (stripping single quotes
@@ -91,7 +86,8 @@
 #'     to your growing collection.
 #' ```
 #' 
-#' (Note the use of YAML's `>` i.e. "YAML pipes"; this is a convenient way of writing paragraphs of text.)
+#' (Note the use of YAML's `>` i.e. "YAML pipes"; this is a convenient way of 
+#' writing paragraphs of text.)
 #' 
 #' ## Dev badges
 #' 
@@ -154,17 +150,17 @@
 #'   )
 #' ```
 #' 
-#' ## YAML config - authors
+#' ## Additional control via YAML
 #' 
-#' You can tweak a few things via the `authors` YAML field:
+#' You can control additinal aspects of the authors display 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:

R/build-news.R

@@ -38,7 +38,7 @@
 #' be added to the heading (see below for how to suppress); if not
 #' available on CRAN, "Unreleased" will be added.
 #'
-#' @section YAML config:
+#' # YAML config
 #'
 #' To automatically link to release announcements, include a `releases`
 #' section.

R/build-reference.R

@@ -4,7 +4,7 @@
 #' alphabetical order. To override this, provide a `reference` section in your
 #' `_pkgdown.yml` as described below.
 #'
-#' @section Reference index:
+#' # Reference index
 #' To tweak the index page, add a section called `reference` to `_pkgdown.yml`.
 #' It can contain three different types of element:
 #'
@@ -104,12 +104,12 @@
 #' either 30x30 (for regular display) or 60x60 (if you want retina display).
 #' Icons are matched to topics by aliases.
 #'
-#' ## Examples
+#' # Examples
 #'
 #' If you need to run extra code before or after all examples are run, you
 #' can create `pkgdown/pre-reference.R` and `pkgdown/post-reference.R`.
 #'
-#' @section Figures:
+#' # Figures
 #'
 #' You can control the default rendering of figures by specifying the `figures`
 #' field in `_pkgdown.yml`. The default settings are equivalent to:

R/build-search-docs.R

@@ -62,15 +62,15 @@ url_node <- function(url) {
 #'
 #' Build a JSON file encompassing all HTML pages, for use by the search script.
 #'
-#' @section YAML config:
+#' # YAML config
 #' You can exclude some paths from the search index.
 #' Below we exclude the changelog from the search index.
 #'
 #' ```yaml
 #' search:
 #'   exclude: ['news/index.html']
 #' ```
-#' @section Debugging and local testing:
+#' # Debugging and local testing
 #'
 #' Locally (as opposed to on GitHub Pages or Netlify for instance),
 #' search won't work if you simply use pkgdown preview of the static files.

R/build-tutorials.R

@@ -7,7 +7,7 @@
 #' `inst/tutorials` and `vignettes/tutorials`. Alternatively, you can
 #' list in `_pkgdown.yml` as described below.
 #'
-#' @section YAML config:
+#' # YAML config
 #' To override the default discovery process, you can provide a `tutorials`
 #' section. This should be a list where each element specifies:
 #'

R/build.R

@@ -44,7 +44,7 @@
 #' The `search` field controls the built-in search and is
 #' documented in `vignette("search")`.
 #'
-#' @section Development mode:
+#' # 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
 #' need to set the development `mode`:
@@ -133,11 +133,13 @@
 #' to danger). Finally, you can choose to override the default tooltip with
 #' `version_tooltip`.
 #'
-#' @section Template:
+#' # Template
 #' The `template` field is mostly used to control the appearance of the site.
-#' See `vignette("customise")` for details.
+#' See `vignette("customise")` for details. But it's also used to control
 #'
-#' There are two other `template` fields that control other aspects of the
+#' ## Other aspects
+#'
+#' There are a few other `template` fields that control other aspects of the
 #' site:
 #'
 #' *   `noindex: true` will suppress indexing of your pages by search engines:
@@ -166,7 +168,7 @@
 #'        trailing_slash_redirect: true
 #'      ```
 #'
-#' @section Analytics:
+#' ## Analytics
 #'
 #' To capture usage of your site with a web analytics tool, you can make
 #' use of the `includes` field to add the special HTML they need. This HTML
@@ -212,8 +214,8 @@
 #'           <script data-goatcounter="https://{YOUR CODE}.goatcounter.com/count" data-goatcounter-settings="{YOUR SETTINGS}" async src="https://gc.zgo.at/count.js"></script>
 #'     ```
 #'
+#' # Source repository
 #'
-#' @section Source repository:
 #' Use the `repo` field to override pkgdown's automatically discovery
 #' of your source repository. This is used in the navbar, on the homepage,
 #' in articles and reference topics, and in the changelog (to link to issue
@@ -260,7 +262,7 @@
 #'   branch: devel
 #' ```
 #'
-#' @section Deployment (`deploy`):
+#' # Deployment (`deploy`)
 #' There is a single `deploy` field
 #'
 #' *  `install_metadata` allows you to install package index metadata into
@@ -274,7 +276,7 @@
 #'      install_metadata: true
 #'    ```
 #'
-#' @section Redirects:
+#' # 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 
@@ -295,7 +297,7 @@
 #' 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:
+#' # Options
 #' Users with limited internet connectivity can disable CRAN checks by setting
 #' `options(pkgdown.internet = FALSE)`. This will also disable some features
 #' from pkgdown that requires an internet connectivity. However, if it is used

R/init.R

@@ -11,7 +11,7 @@
 #' See `vignette("customise")` for the various ways you can customise the
 #' display of your site.
 #'
-#' @section Build-ignored files:
+#' # Build-ignored files
 #' We recommend using [usethis::use_pkgdown()] 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