(Re-)introducing Distill for R Markdown

[This article was first published on RStudio | Open source & professional software for data science teams on RStudio, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

We are proud to announce that version 1.0 of the distill package is now on CRAN. While Distill has been around for awhile (and you may remember it by its original name, Radix), this latest version includes so many new features that we wanted to take a moment to re-introduce you to Distill.

If you just want to jump in and get starting using Distill, you can install the latest version from CRAN:

install.packages("distill")

The package website (also built with Distill) is the best place to start: https://rstudio.github.io/distill/

The Distill website

Figure 1: The Distill website

If you are not ready to commit just yet, read on to find out more about Distill and discover new features from the latest release.

What is Distill?

Distill is a package built for R Markdown, an ecosystem of packages for creating computational documents in R. The goal of the Distill package is to provide an output format optimized for online scientific and technical communication. The Distill R package provides two HTML output formats for R Markdown documents:

These formats are based on the Distill web framework used by the Distill Machine Learning Journal (Olah et al. 2018). The Distill web framework was originally developed to catalyze more engaging and effective scientific, technical communication. The idea was to create a platform to help scientists harness the benefits of modern HTML-based communication, which digital designers and journalists have been using to create interactive and engaging articles that meet readers where they are: online.

A Distill publication

Figure 2: A Distill publication

If you are keen to learn more about how visual aesthetics and interactivity can improve readers’ engagement and learning, we recommend reading Hohman et al. (2020).

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.

PBS Full-Time Kid Egg in a Bottle Experiment

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:

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.1

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.

PBS Full Time Kid DIY Bird Feeder

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:

The RStudio AI blog, built with distill

Figure 5: The RStudio AI blog, built with distill

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

These are all on top of the features we listed for individual Distill articles. You can also use RStudio’s visual markdown editor2 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).

Distill version 1.0

So, what is new with Distill? In the rest of this post, we’ll share some highlights from the latest release, but you might want to look at the release notes for the full details.

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).

A totally relatable CSS editing experience.

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 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:

    ---
    authors:
    - 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.

Distill reference site

In addition to the documentation site, Distill also gained a reference site, built with pkgdown. There, you’ll find a reference section, example gallery, and the latest news. Our sincere thanks to the members of the #rstats community who agreed to have their sites featured in the example gallery:

The Distill example gallery

Figure 7: The Distill example gallery

A hex sticker

Last but definitely not least, distill also gained a hex sticker — thanks to our artist Julie Jung!

distill hex by Julie Jung

Figure 8: distill hex by Julie Jung

Phew! If you’ve made it this far, thanks for reading and we hope you give Distill version 1.0 a whirl!

PBS Full Time Kid

Figure 9: PBS Full Time Kid

Acknowledgements

A big thanks to the 31 contributors who helped with this release by discussing problems, proposing features, and contributing code:

@ADernild, @clauswilke, @CRLNP, @henry090, @jarrodscott, @javierluraschi, @jenrichmond, @jmbuhr, @jthomasmock, @kevinushey, @m-clark, @maelle, @mfdf, @michiexile, @mihagazvoda, @MilesMcBain, @mondpanther, @mrcaseb, @mrworthington, @mvuorre, @nunompmoniz, @pneuvial, @relund, @RodrigoCerqueira, @RRemelgado, @slopp, @stared, @taraskaduk, @tonytrevisan, @umarcor, and @wordsmith189.

References

Hohman, Fred, Matthew Conlen, Jeffrey Heer, and Duen Horng (Polo) Chau. 2020. “Communicating with Interactive Articles.” Distill. https://doi.org/10.23915/distill.00028.
Olah, Chris, Arvind Satyanarayan, Ian Johnson, Shan Carter, Ludwig Schubert, Katherine Ye, and Alexander Mordvintsev. 2018. “The Building Blocks of Interpretability.” Distill. https://doi.org/10.23915/distill.00010.

  1. Thank you, Andrew Heiss!↩︎

  2. At the time of publishing, the visual markdown editor is included in the RStudio IDE Preview v1.4. Read the documentation for the most up-to-date status of the editor: https://rstudio.github.io/visual-markdown-editing/#/↩︎

To leave a comment for the author, please follow the link and comment on their blog: RStudio | Open source & professional software for data science teams on RStudio.

R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Never miss an update!
Subscribe to R-bloggers to receive
e-mails with the latest R posts.
(You will not see this message again.)

Click here to close (This popup will not appear again)