pkgdown 2.0.1

• Fix CRAN failures.

• Reference sections are de-duplicated correctly (#1935).

• Usage sections only generated for topics that have them; usage correctly
  displayed with BS3 (#1931)

• Empty \value{} no longer errors (#1930).

pkgdown 2.0.0

New authors

@maelle is now a pkgdown author in recognition of her significant and sustained contributions. She was the powerhouse behind many of the improvements in this release, particularly the switch to bootstrap 5, improvements to customisation, and implementation of local search.

Bootstrap 5

• pkgdown can style your site with Bootstrap 5 (with help from @jayhesselberth,
  @apreshill, @cpsievert). Opt-in by setting boostrap version in your
  _pkgdown.yml:

  template:
    bootstrap: 5

• We reviewed site accessibility and made a number of small improvements:
  (#782, #1553):

  • Default font is larger and links are always underlined.
  • Heading anchors use aria-hidden to reduce noise for screenreader users.
  • Navbar dropdowns has improved aria-labelledby.
  • The default GitHub/GitLab links gain an aria-label; use for other
    icons is now supported, and encouraged in the docs.
  • Syntax highlighting uses a new more
    accessible colour scheme,
    designed by Alison Hill (#1536)
  • A skip link makes it easier to get directly to the page contents (#1827).

• In-line footnotes mean you can read asides next to the text they refer to.

• Articles support tabsets,
  as in R Markdown.
  (@JamesHWade, #1667).

• Other minor styling improvements:

  • The active item in TOC is indicated with background colour, rather than
    a border.
  • If present, the package logo is shown on all pages near the header.
  • Section anchors now appear on the right (making them usable on mobile
    phones) (#1782).
  • The TOC is scrollable independently of the main content. This makes it
    more useful on long pages with many headings (#1610).
  • The sidebar is shown at the bottom of the page on narrow screens.
  • Function arguments and the reference index (#1822) use definition lists
    (<dl>) instead of tables. This gives more room for long argument
    names/lists of function and detailed descriptions, and displays better
    on mobile.
  • Links on the homepage no longer show the full url in the text.
  • The default navbar no longer includes a home icon - this took up
    precious horizontal space and wasn't very useful since there was already
    a link to the home page immediately to its left (#1383).

Local search

• pkgdown now supports local searching (i.e. searching without an external
  service), and is enabled by default for Bootstrap 5 sites since no set-up is
  needed (#1629, with help from @gustavdelius in #1655 and @dieghernan &
  @GregorDeCillia in #1770).

• pkgdown builds a more exhaustive sitemap.xml even for websites built with
  Bootstrap 3. This might change Algolia results if you use Algolia for search
  (#1629).

Customisation

• New vignette("customise") documents all the ways you can customise your
  site, including the new options described below (#1573).

• Sites can be easily themed with either bootswatch themes or by selectively
  overriding the bslib variables used to generate the CSS. pkgdown now uses
  scss for its own Bootstrap css tweaks, which means that you can customise
  more of the site from within _pkgdown.yml.

• You can pick from a variety of built-in syntax highlighting themes (#1823).
  These control the colours (and background) of code in <pre> tags.

• pkgdown can now translate all the text that it generates (#1446): this means
  that if you have a package where the docs are written in another language, you
  can match all the pkgdown UI to provide a seamless experience to non-English
  speakers. Activate the translations by setting the lang in _pkgdown.yaml:

  lang: fr

  pkgdown includes translations for:

  • es, Spanish, thanks to @edgararuiz-zz, @dieghernan, @rivaquiroga.
  • de, German, thnaks to @hfrick.
  • fr, French, thanks to @romainfrancois, @lionel-, @jplecavalier, and @maelle.
  • pt, Portoguese, thanks to @rich-iannone.
  • tr, Turkish, thanks to @mine-cetinkaya-rundel.
  • zh_CN, simplified Chinese, thanks to @yitao.

  If you're interested in adding translations for your language please file
  an issue and we'll help you get started.

• Template packages can now provide inst/pkgdown/_pkgdown.yml which is used
  as a set of defaults for _pkgdown.yaml. It can be used to (e.g.) provide
  author definitions, select Bootstrap version and define bslib variables,
  and customise the sidebar, footer, navbar, etc. (#1499).

• New includes parameters in-header, before-body, and after-body
  make it easy to add arbitrary HTML to every page. Their content will be
  placed at the end of the <head> tag, right below the opening <body> tag,
  and before the closing tag </body> respectively (#1487). They match the
  bookdown options in_header, before_body and after_body.

  Additionally, you can use before_title, before_navbar, and
  after_navbar to add arbitrary HTML into the navbar/page header; they
  will appear to the left of the package name/version, and to the left and
  right of the navigation links respectively (#1882).

• Authors configuration is more flexible (#1516). You can now:

  • Choose the roles used for filtering authors for the sidebar and footer.
  • Choose the text before authors in the footer.
  • Add text before and after the authors list in the sidebar.
  • Add text before and after the authors list of the authors page.

• Sidebar specification is more flexible (#1443, #1488, #1502). You can now:

  • Change the order of sidebar elements.
  • Add custom sidebar sections (with Markdown/HTML text).
  • Add a table of contents to the home page.
  • Completely suppress the sidebar.
  • Provide your own HTML for the navbar.

• Footer specification is more flexible (#1502). You can now:

  • Change the placement of elements on the left and right.
  • Add text to the left and right (or even remove/replace default text)

• You can now exclude all default components from the navbar (#1517).

• Expert users can now override layout templates provided by pkgdown or template
  packages by placing template files in pkgdown/templates (@gadenbuie, #1897).

New features

• pkgdown now supports redirects (#1259, @lorenzwalthert). The following yaml
  demonstrates the syntax, with old paths on the left and new paths/URLs on
  the right.

  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"]

• Use HTML classes pkgdown-devel or pkgdown-release to declare that certain
  content should appear only on the devel or release site. Use the class
  pkgdown-hide for content that should only appear only on GitHub/CRAN
  (#1299).

• New pkgdown_sitrep() function reports whether the site is set up correctly;
  in particularly it currently reports if auto-linking will work (#1478).

Code

• Styling for errors, warnings, and messages has been tweaked. Messages
  are now displayed the same way as output, and warnings and errors are
  bolded, not coloured. This is part of a suite of changes that aim to
  give package authors greater control over the appearance of messages,
  warnings, and errors.

• Long lines in code output are now wrapped, rather than requiring scrolling.
  This better matches rmarkdown::html_document() and what you see in the
  console.

• build_reference() now allows linking to topics from other packages (either
  function names e.g. rlang::is_installed or topic names e.g.
  sass::font_face). (#1664)

• build_reference() now runs examples with
  options(rlang_interactive = FALSE) (ensuring non-interactive behaviour in
  functions that use rlang::is_interactive()), options(cli.dynamic = FALSE),
  Sys.setenv(RSTUDIO = NA) and Sys.setLocale("LC_COLLATE", "C") (#1693).
  It also runs pkgdown/pre-reference.R before and pkgdown/post-reference.R
  after examples. These allow you to do any setup or teardown operations you
  might need (#1602).

• A reference index section with title: internal is now silently dropped,
  allowing you to suppress warnings about topics that are not listed in the
  index (#1716).

• Code blocks are now highlighted according to their declared language
  (e.g. yaml) if the documentation was built with roxygen2 7.1.2 or later
  (#1690, #1692).

• New pkgdown_print() allows you to control how your objects are rendered in
  examples. It includes built-in handling for htmlwidgets and "browseable" HTML
  so pkgdown output now more closely resembles what you see in RStudio.
  Added extension points to make HTML widgets (and RGL in particular) work
  in rendered examples (@dmurdoch).

• You can globally set the width of code output (in reference and articles)
  with

  code:
    width: 50

• Articles now render output styles created by cli/crayon (#1556).

• When copy and pasting code blocks, lines containing output (e.g. #>)
  are automatically omitted (#1675).

• Auto-linking improvements:

  • Links to inherited R6 methods now work correctly for both internal
    (#1173, @vandenman) and external (#1476) parent classes.

  • Linking no longer fails if a package contains duplicated Rd aliases.

  • Correctly link to reference pages when the \name{} entry doesn't match
    the file name (@dmurdoch, #1586; #16...

pkgdown 1.6.1

• The article index (used for autolinking vignettes across packages)
  once again works (#1401).

pkgdown 1.6.0

Major changes

• pkgdown now uses the new downlit package for all
  syntax highlighting and autolinking (in both reference topics and vignettes).
  There should be very little change in behaviour because the code in downlit
  was extracted from pkgdown, but this makes it easier to use pkgdown's nice
  linking/highlighting in more places (#1234).

• pkgdown now uses the ragg::agg_png() device to generate example figures.
  This should be a little faster and produce higher quality output. Learn
  more at https://ragg.r-lib.org (#1320).

Minor improvements and bug fixes

Rd translation

• \special{} support inside \usage{} added to allow non-standard R usage
  syntax (@klmr, #1345).

• #ifdef and #ifndef are now supported; the "current" OS is hard coded to
  "unix" to ensure reproducible output regardless of where you build the
  website (#1384).

• Nested \subsection{}s now generate appropriate heading levels
  (h3, h4, h5 etc) (#1377), and get anchor links (#1389).

• \preformatted{} no longer double escapes its contents (#1311).

Articles and vignettes

• build_articles() no longer sets the theme argument of the document format
  to NULL when as_is: true. This should allow it to work with a wider
  range of output formats including bookdown::html_vignette2() and
  friends (@GegznaV, #955, #1352).

• When build_article() fails, it gives the complete failure message (#1379).

• Markdown header attributes are now processed in all markdown files (@jonkeane, #1343)

Auto-linking and syntax highlighting

• The branch used for source linking can be configured by setting
  repo: branch: branch_name in _pkgdown.yml (@jonkeane, #1355):

  repo:
    branch: main

• autolink_html() is (soft) deprecated. Please use
  downlit::downlit_html_path() instead.

• Highlighting of empty expressions works once more (#1310).

• New deploy$install_metadata option in _pkgdown.yml. Setting it to
  true will store site metadata in the package itself, allowing offline
  access for packages that to autolink to the package's website
  (@mstr3336, #1336).

Other

• You can now control the background colour of plots with the figures.bg
  option (it is transparent by default, and given a white background by
  css). See ?build_reference for an example.

• HTML is automatically stripped from the page title (#1318).

• Suppressing CRAN dates in news file now actually works.

• All HTTP requests are now retried upon failure (@jameslamb, #1305).

• Setting clean = TRUE in deploy_site_github() removes old files from the
  deployed site before building a new one (#1297).

pkgdown 1.5.1

• Syntax highlighting works on Windows once more (#1282).

• pkgdown no longer fails if your .Rd files have duplicated \aliases
  as were produced by an older version of roxygen2 (#1290).

• Rendering empty .md file now returns empty string (#1285).

• build_articles_index() is now exported to rapidly rebuild the index (#1281)

• deploy_site_github() now accepts a host argument to specify alternate
  hosts (e.g., Github enterprise) (@dimagor, #1165) and once again works as
  intended on Travis-CI (@jimhester, #1276).

pkgdown 1.5.0

New features

• The articles index page and navbar have been overhauled. There are two
  major new features in this release:

  • The articles index page now displays article descriptions,
    taken from YAML metadata belonging to each article. This lets you provide
    more context about each article and describe why one might want to read
    it (#1227).

  • The articles navbar is now also controlled by the articles section
    in _pkgdown.yml. The ordering of the sections, and articles within
    them, control the order of the articles in the navbar, and you can
    use the new navbar field to control whether or not each section
    appears in the navbar (#1101, #1146).

• The reference index now has two levels of heading hierarchy: title and
  subtitle (#327).

• Tables of contents in sidebars now use
  bootstrap-toc; this considerably
  improves navigation for long articles and reference pages.

• You can now control the links to source files (in reference pages and
  articles) and issues and users (in the NEWS) with new repo$url config
  option (#1238). This makes it easier to use pkgdown with GitHub enterprise,
  packages in subdirectories, and other source hosts (like bitbucket).

  repo:
    url:
      home: https://github.com/r-lib/pkgdown/
      source: https://github.com/r-lib/pkgdown/blob/master/
      issue: https://github.com/r-lib/pkgdown/issues/
      user: https://github.com/

  The individual components (e.g. path, issue number, username) are pasted on
  the end of these urls so they should have trailing /s.

  You don't need to set these links for GitLab, as pkgdown now detects
  GitLab urls automatically (since they use the same structure as GitHub)
  (#1045).

• There's much richer control over Open Graph and Twitter metadata for the
  whote site and for individual articles. See new vignette("metadata") for
  details (@gadenbuie, #936).

• New deploy_to_branch() function to build and deploy a site to a branch,
  defaulting to gh-pages for use with GitHub Pages. This is used in our
  recommended GitHub action workflow for automatically building and deploying
  pkgdown sites for packages on GitHub (@jimhester, #1221).

• Updated JS libraries: jquery 3.3.1 -> 3.4.1; bootswatch 3.3.7 -> 3.4.0;
  bootstrap 3.3.7 -> bootstrap 3.4.1; docsearch 2.6.1 -> 2.6.3;
  fontawesome 5.11.1 -> 5.12.1; headroom.js 0.9.44 -> 0.11.0;
  clipboard.js 2.0.4 -> 2.0.6 (@jayhesselberth).

Auto-linking improvements

• Examples and Rmd now use exactly the same syntax highlighting strategy.

• In examples and Rmd, calls of the form current_package::foo now get
  a local link (#1262).

• \preformatted{} blocks are now highlighted and linked if they parse
  as R code (#1180).

• library(pkgdown) is now automatically linked to the reference index for
  "pkgdown" not the documentation for library() (#1161).

• help("topic") is now automatically linked to the documentation for "topic",
  not to the documentation for help() (#1210)

Minor improvements and bug fixes

Articles

• build_home() no longer uses (unrendered) README.Rmd or index.Rmd if
  corresponding .md files are not found.

• build_article() failures now print more information to help you debug
  the problem (#952).

• The name of the vignette mapped to the "Get started" entry in the navbar
  is now more flexible. You can use an article (e.g articles/{pkgname})
  and if your package has a . in its name you can replace it with - to
  generate a valid article name (e.g. the get started vignette for
  pack.down would be pack-down) (#1166).

Deployment

• deploy_to_branch() now correctly captures the commit SHA on GitHub Actions
  (@coatless, #1252).

• deploy_to_branch(github_pages = TRUE) generates a .nojekyll to prevent
  jekyll ever executing (#1242).

• CNAME is no longer generated by init_site(), but is instead conditionally
  by deploy_to_branch() when github_pages = TRUE. This is a better a fit
  because the CNAME file is only needed by GitHub pages (#969).

• deploy_site_github() argument repo_slug has been deprecated and is no
  longer needed or used. (@jimhester, #1221)

News

See additional details in ?build_news:

• You can optionally suppress the CRAN release dates added to the news
  page (#1118).

• Multi-page news style gets a better yaml specification (the old style
  will continue to work so no need to change existing YAML).

Reference

• A topic named index will not longer clobber the reference index (#1110).

• Topic names/aliases on reference index are now escaped (#1216).

• build_reference() gives better warnings if your _pkgdown.yml is
  constructed incorrectly (#1025).

• New has_keyword() topic selector for reference. has_keyword("datasets")
  is particularly useful for selecting all data documentation (#760).

• New lacks_concepts() can select topics that do not contain any of
  a number of specified concepts. (@mikldk, #1232)

Home, authors, and citation

• pkgdown now escapes html and linkifies links in comments in author info
  from DESCRIPTION (@maelle, #1204)

• pkgdown now uses the ORCiD logo included in Font Awesome 5.11 instead of
  querying it from members.orcid.org (@Bisaloo, #1153)

• badges are now extracted from everything between <!--badges: start-->
  and <!--badges: end-->. They used to be extracted only if they were
  direct children of the first <p> after <!--badges: start-->.

• build_home() now looks for pkgdown/index.md in addition to the top-level
  index or README files (@nteetor, #1031)

Navbar

• pkgdown now formats the package version displayed in the navbar the same way
  as it has been specified in the DESCRIPTION file. In particular, version
  separators (e.g. . and -) are preserved. (#1170, @kevinushey)

• add support for navbar submenus: you can create submenus following the
  convention established in rstudio/rmarkdown#721 (@ijlyttle, @wendtke, #1213)

Other

• Updated JS libraries: jquery 3.3.1 -> 3.4.1; bootswatch 3.3.7 -> 3.4.0;
  bootstrap 3.3.7 -> bootstrap 3.4.1; docsearch 2.6.1 -> 2.6.3
  (@jayhesselberth).

• Markdown conversion now explicitly allows markdown inside of HTML blocks;
  this was previously accidentally disabled (#1220).

• A timestamp for the last site build is reported in pkgdown.yml (#1122).

pkgdown 1.4.1

• Don't install test package in user library (fixes CRAN failure).

pkgdown 1.4.0

New features

• build_site(), build_reference() and build_home() gain a parameter
  devel which controls whether you're in deployment or development mode.
  It generalises and replaces (with deprecation) the existing document
  argument.

  Development mode is optimised for rapid iteration and is the default
  for build_reference(). It uses pkgload::load_all() to load code
  directly from disk in order.

  Deployment mode is slower, but guarantees correct results, and is the
  default for build_site(). It installs the package into a temporary
  library, and runs examples/articles in a new process.

• build_reference() no longer runs devtools::document() (#1079) and
  build_home() no longer re-builds README.Rmd. This makes the scope
  of responsibility of pkgdown more clear: it now only creates/modifies
  files in doc/.

• build_home() now strips quotes from Title and Description fields
  when generating page metadata. Additionally, you can now override the
  defaults via the title and description fields in the home section of
  _pkgdown.yml (#957, @maelle).

• vignette("linking") describes how pkgdown's automatic linking works, and
  how to ensure that cross-package links point to the right place.

Bug fixes and minor improvements

Rd translation

• \examples{} rendering has been completely overhauled so it now first
  converts the entire mixed Rd-R block to R prior, and then evaluates the
  whole thing. This considerably improves the fidelity of the translation
  at a small cost of no longer being able to remove \donttest{} and
  friends (#1087).

• \item{}s in \describe{} containing whitespace are translated correctly
  (#1117).

• \dots and \ldots are translated to ... instead of the ellipsis,
  since they're often found in code (#1114).

• \tabular{} translation handles code better (@mitchelloharawild, #978).

• \subsection{} contents are now treated as paragraphs, not inline text
  (#991).

• \preformatted{} blocks preserve important whitespace (#951).

Front end

• Links to online documentation for functions in code chunks are no longer
  displayed when printing (#1135, @Bisaloo).

• Updated fontawesome to v5.7.1. fontawesome 5 deprecated the fa prefix.
  If you have used custom icons in your navbar, you'll should update them from
  (e.g.) fa fa-home to fas fa-home. Brands now have a separate prefix so
  fa fa-github becomes fab fa-github (#953).

• The navbar is now automatically hidden with
  headroom.js.

• The sticky behaviour of the navbar is now implemented in pure CSS instead of
  relying a the 3rd party javascript library (#1016, @Bisaloo)

• Favicons are now automatically built from a package logo (#949).

Linking

• Infix operators (e.g., %in% and %*%) are now linked to their
  documentation (#1082).

• Function names can now be included in headers without spurious auto-linking
  (#948).

• Links to external documentation now point to rdrr.io
  (#998).

Other

• News page recognises more version specfications (including the
  "(development version)" now used by usethis) (#980).

• Subdirectories are supported for assets (#939, @ijlyttle).

• A default 404 page (404.html) is built, unless a custom .github/404.md
  is provided (#947).

• build_article() now uses the raw vignette title as page <title>
  and og:title (@maelle, #1037).

• build_home() now looks for license files spelled either as LICENSE or
  LICENCE (#972).

• build_home() can find badges in paragraph coming after the comment
  <!-- badges: start --> (#670, @gaborcsardi, @maelle).

• build_home() will add a community section to the sidebar if there is either
  a code of conduct (.github/CODE_OF_CONDUCT.md) or a contributing guide
  (.github/CONTRIBUTING.md) (#1044, @maelle).

• build_reference() gains a topics argument which allows you to re-build
  only specified topics.

• build_site(new_process = TRUE) gains a timeout,
  options(pkgdown.timeout = 10), that can be used to prevent stalled
  builds.

• deploy_site_github(install = FALSE) makes it possible to opt out of
  installation.

• dev_mode() now recognises 0.1.9000 as a development version of a package
  (this is an emerging standard we use for packages with backward incompatible
  changes) (#1101).

pkgdown 1.3.0

(This was meant to be pkgdown 1.2.1, but I accidentally submitted the wrong version to CRAN)

• Restore accidentally deleted build_logo() function so that logos
  are once more copied to the website.

• Fix to pkgdown.css so page header has correct amount of top margin.

• content-home.html template is no longer used when the homepage
  is an .Rmd (Reverts #834. Fixes #927, #929)

• deploy_site_github() now passes parameters to build_site()
  (@noamross, #922), and the documentation gives slightly better advice.

• Correct off-by-one error in navbar highlighting javascript; now no navbar
  is highlighted if none match the current path (#911).

• Tweaking of HTML table classes was fixed (@yonicd, #912)

• Restore accidentally removed docsearch.css file.

pkgdown 1.2.0

New features

• deploy_site_github() can be used from continuous intergration systems
  (like travis) to automatically deploy your package website to GitHub Pages.
  See documentation for how to set up details (@jimhester).

• build_favicon() creates high resolution favicons from the package logo,
  and saves them in pkgdown/. They are created using the
  http://realfavicongenerator.net API, and are better suited for modern web
  usage (e.g. retina display screens, desktop shortcuts, etc.). This also
  removes the dependency on the magick package, making automated deployment
  a little easier (@Bisaloo, #883).

• Users with limited internet connectivity can explicitly disable internet
  usage by pkgdown by setting options(pkgdown.internet = FALSE) (#774, #877).

Improvements to Rd translation

• rd2html() is now exported to facilitate creation of translation reprexes.

• \Sexpr{} conversion supports multiple arguments, eliminating
  x must be a string or a R connection errors when using \doi{} (#738).

• \tabular{} conversion better handles empty cells (#780).

• \usage{} now supports qualified functions eliminating
  Error in fun_info(x) : Unknown call: :: errors (#795).

• Invalid tags now generate more informative errors (@BarkleyBG, #771, #891)

Front end

• The default footer now displays the version of pkgdown used to build
  the site (#876).

• All third party resources are now fetched from a single CDN and are
  give a SRI hash (@Bisaloo, #893).

• The navbar version now has class "version" so you can more easily control
  its display (#680).

• The default css has been tweaked to ensure that icons are visible on all
  browsers (#852).

Bug fixes and minor improvements

Home page

• Can now build sites for older packages that don't have a Authors@R field
  (#727).

• Remote urls ending in .md are no tweaked to end in .html (#763).

• Bug report link is only shown if there's a "BugReports" field (#855).

• content-home.html template is now used when the homepage is an .Rmd
  (@goldingn, #787).

• A link to the source inst/CITATION was added to the authors page (#714).

News

• Uses stricter regular expression when linking to GitHub authors (#902).

Reference

• Unexported functions and test helpers are no longer loaded (#789).

• Selectors that do not match topics now generate a warning. If none of the
  specified selectors have a match, no topics are selected (#728).

Articles

• The display depth of vignette tables of contents can be configured by
  setting toc: depth in _pkgdown.yml (#821):

  toc:
    depth: 2

Overall site

• init_site() now creates a CNAME file if one doesn't already exist and the
  site's metadata includes a url field.

• build_site() loses vestigal mathjax parameter. This didn't appear to do
  anything and no one could remember why it existed (#785).

• build_site() now uses colors even if new_process = TRUE (@jimhester).