Skip to content

pkgdown 2.0.0
Compare
Choose a tag to compare
@hadley hadley released this 30 Nov 21:48
v2.0.0
6acb25d

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:

    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; #1676).

Articles

  • Article subtitle, author and date (specified in the YAML frontmatter) are now
    correctly omitted from the article table of contents in the sidebar
    (@maxheld83, #1428).

  • Support for as_is: true and non-default output formats for vignettes/
    articles has been somewhat improved. Support is fundamentally limited due to
    the challenges of integrating HTML from output formats that pkgdown doesn't
    know about, but it should be a little more reliable and a little better
    documented (#1757, #1764).

  • build_articles() no longer fails if you have a directory underneath
    vignettes with a .Rmd extension (#1425).

  • build_articles() now correctly handles links to images in man/figures
    (which have the form ../man/figures) (#1472).

  • build_articles() again sets the theme argument of the document format
    to NULL when as_is: true but lets users override this via the theme
    argument of the output format.

  • build_articles() and build_home() now warn if you have images that
    won't render on the website because they're in unsupported directories
    (#1810). Generally, it's only safe to refer to figures in man/figures
    and vignettes.

  • Articles stored in vignettes/articles are moved up one level so that they
    appear in articles/ on the website. Previously, they would appear in
    articles/articles, so build_redirects() automatically adds redirects for
    any articles in the vignettes/articles directory (@gadenbuie #1911).

HTML, CSS and JS

  • New template option trailingslash_redirect that allows adding a script to
    redirect your-package-url.com to your-package-url.com/ (#1439, @cderv,
    @apreshill).

  • External links now get the class external-link. This makes them easier to
    style with CSS (#881, #1491).

  • Duplicated section ids are now de-duplicated; this makes pkgdown work better
    with the documentation of R6 classes.

  • Updated CSS styles from pandoc to improve styling of reference lists (#1469).

Deployment

  • build_site_github_pages() has been extracted out of deploy_site_github()
    to make it easier to decouple building and deployment, and so we can take
    advantage of standard deployment actions (#1756).

  • deploy_to_branch() now calls git remote set-branches with --add to avoid
    overwriting the existing remote.{remote}.fetch value (@kyleam, #1382).
    It also now cleans out the website directory by default; revert to previous
    behaviour with clean = FALSE (#1394).

  • build_reference() will error if envar CI is true and there are missing
    topics (@ThierryO, #1378).

  • You can override the auto development mode detected from the package
    version by setting env var PKGDOWN_DEV_MODE to release or devel.
    This is useful if your package uses a different convention to indicate
    development and release versions (#1081).

Other minor improvements and bug fixes

  • \special{} tags with complex contents are rendered correctly (@klmr, #1744).

  • \arguments{} and \value{} do a better job of handling mingled items and
    text (#1479). The contents of \value{} are now shown immediately after
    \arguments{}.

  • The default "branch" for linking to the file sources is HEAD, which will
    work regardless of whether your default branch is called "main" or "master".

  • Non-ORCID comments in Authors@R are now more usable: if such comments
    exist, the sidebar gains a link to the authors page, where they are displayed
    (#1516).

  • Citations with and without text versions are better handled, and text
    citations are correctly escaped for HTML (@bastistician, #1507).

  • README badges in a single paragraph placed between <!-- badges: end -->and
    <!-- badges: end --> comments are again detected (#1603).

  • The 404 page (default or from .github/404.md) is no longer built in the
    development mode (see ?build_site) as e.g. GitHub pages only uses the
    404.html in the site root (#1622).

  • All links on the 404 pages (navbar, scripts, CSS) are now absolute if there
    is an URL in the configuration file (#1622).

  • The version tooltip showed in the top navbar is now only set if you've
    explicitly set the development.mode in _pkgdown.yml (#1768).

  • All heading (e.g. headings on the reference index page, and the arguments
    heading on the reference pages) now get anchors (#1747).

  • Use autolink_bare_uris for Pandoc above version 2.0 (@marcosmolla, #1618).

  • pkgdown now recognizes GitLab URLs to the source repository and adds the
    corresponding icon to the navbar (#1493). It also supports
    GitLab subgroups
    (@salim-b, #1532).

  • Links for GitHub Enterprise and GitLab Enterprise repositories are detected
    by assuming such host address begin with github. or gitlab.
    (@ijlyttle, #1452).

  • The rules drawn by the CLI (as for example, in build_site()) are protected
    against very narrow terminal windows (@maxheld83, #1435).

  • Google Site Verification (https://support.google.com/webmasters/answer/9008080?hl=en)
    can now be configured for pkgdown sites.

  • build_rmarkdown_format sets html_document(anchor_sections = FALSE)
    to avoid needless dependencies (@atusy, #1426).

  • Jira issues in NEWS can be automatically linked by setting your project name
    (s) with repo: jira_projects: [...] and specifying a custom issue URL with
    repo: url: issue: ... in _pkgdown.yml (@jonkeane, #1466).

  • build_home() always creates citation information for the authors page,
    using metadata from DESCRIPTION when there is no inst/CITATION file,
    and links to this from the sidebar (#1904).

  • build_news() no longer breaks with URLs containing numeric fragments
    (@krassowski, #1456), recognises more styles of release heading (#1437),
    and generate stable IDs using a the combination of the heading slug and
    package number. (@Bisaloo, #1015)

Contributors

klmr, jayhesselberth, and 32 other contributors
Assets 2
Loading