Welcome to my {distill} website!

Update: August 2022

Since this post was originally written, I have replaced my {disill} website with this one built with Quarto.

If you’re looking to build a new website using R (or python or Julia), I would 100% recommend Quarto over {distill}.

That said, I still have a soft spot for {distill} and am keeping this post on the blog for posterity.

Hello, and welcome to my new site, built using the {distill} package. Here’s why I switched from {blogdown}, and the resources and inspirations that helped me in the process.

Why {distill}?

As the documentation says, {distill} for R Markdown is a web publishing format optimised for scientific and technical communication. Recent updates to the package, particularly the ability to customise the theme through the create_theme() function, have made it a really appealing choice for those wanting a personalised website based only on R Markdown. The fact that {distill} is made just in R Markdown is a big win for those not wanting to go down (or, like me, looking to get away from), the Hugo route. I’d had a Hugo Academic website for four years, built on {blogdown}, and had been stung a number of times by it breaking after updates to Hugo and Hugo Academic. Last year, I switched to {hugodown}, and that helped, but I had some serious FOMO following that shift after the release of {blogdown} v1.0 a few months later, with all its handy check functions. By then, anyway, I was also displeased with the shift from Hugo Academic to Wowchemy, and getting a little bored of that theme anyway. I had also started seeing more and more {distill} sites pop up from those I admire in the RStats community. I looked into it and and I loved the simplicity of it, both in looks and in management. No more impenetrable file structures! No more not being sure quite why my website is working/looking as it does! Attending Alison Hill’s incredible ‘Crafting Kind Tools’ talk, in which she described the care put into making the {distill} user experience an enjoyable one, was the last push I needed to start my website again (though, to be fair, that talk also described similar care put into the latest release of {blogdown}).

I’m finding working with {distill} to be an absolute joy!

Resources

This post is not a guide on how to get a {distill} site up an running. There are already great resources for that. In particular, here are the resources I found helpful.

The basics

• The blogpost from RStudio on (Re-)introducting Distill for R Markdown is a great place to start.

• For getting up and running, the official {distill} documentation is excellent (and also a {distill} website).

• Whilst we’re on resources from the RStudio team, it’s worth remembering that because {distill} is built on {rmarkdown}, recent developments to that package, such as the ability to style a site with {sass} ¹, and developments in {knitr}, such as the ability to easily add alt-text to images, follow through to {distill} too.

• There’s a great building a blog with distill post from Tom Mock

• And one on building a {distill} website from Lisa Lendway

Next steps

• The {postcards} package from Sean Kross makes it incredibly easy to create simple, stylish, landing pages, and they make great home pages for {distill} sites. Alison Hill has a walk-through on how to set this up: M-F-E-O: postcards + distill

• Tom Mock has another excellent {distill} post on including and meta tagging extra content in a distill blog, useful for if/when you want your site to contain content other than distill_articles

• Whilst the create_post() function in {distill} is a great way to get started on a blog post, Eric Ekholm shows how he developed a function wrapped around it to personalise the {distill} template

• For styling content, John Helveston shows how to customise {distill} with {htmltools} and CSS.

• If you want to allow readers to comment on your posts, then follow this guide from Vebash Naidoo on how to enable utterances with {distill}

Inspirations/Code

I’m extremely grateful to the authors of the above posts for taking the time to write up what they’ve developed and what they know/have learnt to do, therefore making it easy for others to apply. I guess that’s what blogs are for! But I’ve also learnt a lot from finding sites that I simply like the look of, or have cool features, and looking at the source code on GitHub and adapting it for my own site. Here are some sites that I’ve drawn on for inspiration and code²:

• John Helveston

site source

I particularly like his icon_link buttons (as demonstrated just above), and the second collection for talks. John tells me he is turn took inspiration for this from Emi Tanaka’s site.

• Ijeamaka Anyene

site source

Ijeamaka has a really cool projects page, where she’s created a card for each project, which I’ve implemented on my site.

• Tom Mock

site source

Come for the minimalist, stylish design, stay for the fantastic blog content, not just on {distill}, but also on {gt}, R Markdown, #TidyTuesday and much more besides.

Finding out more

The above just scratches the surface. There are many more great sites built on {distill} out there, and lots more ways to customise them. Below are some good ways to find out more.

The distillery

The distillery is a {distill} blog about building {distill} blogs and websites. As the site’s GitHub README states:

This site was built for the community of distill users to find ways to build and customize their sites and to inspire one another. If you have a distill website or blog, we would love to have it included in the distillery showcase! Have a post about ways to customize or add new features to your blog? We would love to have it included on the distillery tips & tricks page!

The showcase is a great place to browse sites for inspiration and the tips and tricks page has loads of great resources (many of which I want to implement on my site in the future, for example Jannick Buhr’s post on making a dark mode for your {distill} site).

Twitter

There are a number of folk who tweet about {distill} (alongside other #rstats content). I’ve seen useful tweets from Shannon Pileggi @PipingHotData, Lisa Lendway @lisalendway and John Helveston @JohnHelveston. And it pretty much goes without saying that anyone with an interest in {distill} should be following its authors (and general R Markdown gurus), Alison Hill @apreshill, Christophe Dervieux @chrisderv, Rich Iannone @riannone and Yihui Xie @xieyihui (note that the author and original creator of {distill} is JJ Allaire - he does have a twitter account but doesn’t seem to use it).

A sneak-peek at {distilltools}

Inspiried by the above-mentioned posts from John Helveston and Eric Ekholm, I’ve started working on a package, {distilltools}, a collection of tools to support the creation and styling of content on websites created using {distill}.

site source

It is in the very early stages of development. I am actively seeking contributions - both ideas and code - to help build the package to be broadly useful to a wide variety of {distill} users. The idea is for the package to become a curated, collaborative, community-driven project. Please see the contributing guide for more details on how to get involved. In terms of relationship between packages, I hope in time that {distilltools} can be for {distill} something like what {xaringanExtra} and {xaringanthemer} are for {xaringan}. Some of what I have in mind may sit better within the distill package itself, and I am in touch with the {distill} team about that.

At the time of writing, there are just three functions:

• icon_link: creates the html for a link button with icon and text (as seen above). Output of icon_link will need styling via the icon-link class to make it look like a button.
• create_talk(): a wrapper around distill::create_post() that creates a post in the talk directory and includes buttons (made with icon-link()) for slides (both web and pdf), material, video and project. These can easily be edited in the resulting .Rmd file.
• create_post_from_template(): this function operates almost identically to distill::create_post() except for the addition of a path argument, which allows the user to pass in a path to an .Rmd file that can be used as a template for the post. (Note that this function is likely going to be pulled into the {distill} package and hence be depreciated here.)

Expect to hear much more from me, both on this blog and twitter, about {distilltools} in the near future.

Last updated

2022-11-11 21:33:56 GMT

Details

source code, R environment

Session info

Toggle

─ Session info ───────────────────────────────────────────────────────────────
 setting  value
 version  R version 4.2.1 (2022-06-23)
 os       macOS Monterey 12.6.1
 system   aarch64, darwin20
 ui       X11
 language (EN)
 collate  en_US.UTF-8
 ctype    en_US.UTF-8
 tz       Europe/London
 date     2022-11-11
 pandoc   2.19.2 @ /Applications/RStudio.app/Contents/Resources/app/quarto/bin/tools/ (via rmarkdown)
 quarto   1.2.247 @ /usr/local/bin/quarto

─ Packages ───────────────────────────────────────────────────────────────────
 ! package      * version    date (UTC) lib source
 P distilltools * 0.0.0.9003 2022-08-01 [?] Github (EllaKaye/distilltools@03881a1)
 P sessioninfo  * 1.2.2      2021-12-06 [?] CRAN (R 4.2.0)

 [1] /private/var/folders/xf/jb2591gj41xbj0c4y2d8_7ch0000gn/T/Rtmp66BdZk/renv-library-234b7954f300
 [2] /Users/ellakaye/Rprojs/mine/ellakaye-quarto/renv/library/R-4.2/aarch64-apple-darwin20
 [3] /Library/Frameworks/R.framework/Versions/4.2-arm64/Resources/library

 P ── Loaded and on-disk path mismatch.

──────────────────────────────────────────────────────────────────────────────

Footnotes

1. When I first tried this in {distill}, I couldn’t get it working, but it seems this has been patched now

2. Update since porting this post to Quarto: some of the sites in this section have also been rewritten since this was originally posted. The links below may no longer be to {distill} sites, or may be missing the features that I attribute to them in this post.