This is a companion discussion topic for the original entry at https://blog.rstudio.com/2020/12/07/distill
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: Distill for R Markdown
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:
- Single HTML articles (
distill_article), and - Multi-page HTML websites, including blogs (
distill_website).
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.
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.
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.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.
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 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).
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.
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:
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!
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!
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 . Communicating with Interactive Articles.
Olah, Chris, Arvind Satyanarayan, Ian Johnson, Shan Carter, Ludwig Schubert, Katherine Ye, and Alexander Mordvintsev. 2018. “The Building Blocks of Interpretability.” Distill . The Building Blocks of Interpretability.
- Thank you, Andrew Heiss
- 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/#/[↩︎](https://blog.rstudio.com/2020/12/07/distill/#fnref2)