(Re-)introducing Distill for R Markdown

Distill for single HTML articles

If you have ever knit an R Markdown file to html_document(), then you can think of distill_article() as its scientific alter-ego.

Figure 3: PBS Full-Time Kid Egg in a Bottle Experiment

Distill articles offer users an R Markdown format with built-in bells and whistles that make scientific communication easier, including:

• Ability to incorporate JavaScript and D3-based interactive visualizations made with R.

• Support for citations, appendices, hover-able footnotes, and asides.

• Tools for making articles easily citeable, as well as for generating Google Scholar compatible citation metadata.

• Auto-numbering of figures and tables, and cross-referencing of figures and tables.

• Built-in support for multiple authors with affiliations and ORCID iD.

• Adding creative commons licensed content with specific reuse instructions.

Each of these features are designed to help scientists use the web and R to communicate about their work more effectively. But you can also use Distill to publish any HTML content, like instructions for making bagels- Distill works great for that too.¹

Distill for websites and blogs

While a single article may often be all that you need, many data science projects involve a collection of multiple R Markdown documents. When you have more than one R Markdown file knitted to HTML in your collection, it’s a good time to think about knitting them together into a single, navigable website. It is much easier for folks to engage with your work when you can share a link directly to it that they can see and explore it themselves.

Figure 4: PBS Full Time Kid DIY Bird Feeder

Distill can knit together a collection of distill articles into a cohesive and navigable website. Distill sites feature an upper navigation bar with links (which may also include dropdown menus). In addition, Distill blogs offer page layout options like listing pages and the ability to customize them. A listing page doesn’t have to be populated manually; instead, it creates a clickable, sequential list of all your posts (usually with nice thumbnail images and some post metadata like author, date, etc.). Blog posts also get special treatment by Distill — they are never automatically re-rendered when your site is re-built.

Here is a Distill blog in action, from the RStudio AI blog:

Figure 5: The RStudio AI blog, built with distill

Distill adds several built-in features to make websites better-suited for scientific communication:

• Site-wide search.

• Per-article sharing preview images (for OpenGraph, Twitter, Slack, etc.).

• Import posts from other external sources.

• Canonical urls - handy for when your own post is re-published elsewhere.

• Customizable RSS feeds (either with summaries or full post content).

• Site logo in the upper navbar.

• Integrated Google Analytics support.

• Favicon support.

These are all on top of the features we listed for individual Distill articles. You can also use RStudio’s visual markdown editor² to compose Distill articles, which provides a WYSIWYG (What You See Is What You Get) writing experience as well as the ability to insert citations from a document bibliography, reference management software, and even open-source bibliographic databases like PubMed.

Importantly, Distill websites are built without any kind of static site generator (like Jekyll or Hugo), which means that Distill websites offer users the bliss of building a website without any additional software dependencies (this means, all you need is R and the distill package to make it work).

Theming

In this latest release, we have introduced the ability to theme your Distill article, website, or blog without needing to write your own CSS from scratch. Distill output formats have a modern and streamlined theme “out of the box,” but we also know that it is important for users to be able to create a non-cookie-cutter site with less friction (i.e., less CSS).

Figure 6: A totally relatable CSS editing experience.

To sidestep CSS wrangling, you can now create and apply a Distill theme, which allows you to customize common elements without needing to create a CSS file from scratch. To get started, you can use the new create_theme() function:

create_theme(name = "bespoke-theme") 

Follow the docs on theming to learn more. There, we provide a demo with code for going from the default theme (left) to a bespoke theme (right) by changing only a few fields in bespoke-theme.css:

But themes aren’t just for full websites! You can also theme a single Distill article, and you can change the theme for an individual article within a Distill website. As before, you can always use custom CSS styles to go fully custom; the theme allows you to bypass the detective work typically involved in discovering which CSS selectors are needed to change the key elements most users wish to control. Finally, we provided some example Distill themes for inspiration.

Other highlights

• Added built-in search functionality, based on Fuse.js. Search will be enabled by default for new distill blogs, and can be enabled on websites as well.

• Headings provide anchor links upon hover, making it easier to find and share the URL for a specific section of a webpage or article.

• Improved default syntax highlighting theme, optimized for accessibility based on the a11y syntax highlighting themes by Eric Bailey. All colors in the theme meet the minimum WCAG 2.0 guidelines for contrast accessibility of > 4.5 (AA).

• Improved handling and display of article categories for blogs, allowing readers to more easily see the categories for each individual post on listing pages.

• Support for ORCID integration in article metadata:

  ---
  author:
  - name: Dianne Cook
    affiliation: Monash University
    orcid_id: 0000-0002-3813-7155
  ---

• Downlit integration for automatic linking of R code in code chunks to function reference documentation.

  Downlit links to any package’s reference pages directly.