Building a {distill} website

A journey through how this website came to be

Why a website?

Well, I finally did it! I made a website. And to celebrate, I’m going to share how I did it. And, why did I do it? Two main reasons: 1. to share materials that might be useful for others, 2. to document some things for myself all in one place.

I opted for a {distill} site because it seemed like it would allow me enough freedom to customize my site and not so much freedom that I would get bogged down in details (ie. choosing colors … oops, I still spent a lot of time on that).

Resources

Before I start, I want to share some of the resources I used.

• Alison Hill and Desirée De Leon’s webinar about Sharing on Short Notice. WATCH THIS before going any further. This is where I was first introduced to netlify and it blew my mind how easy it was to turn my html files into a website. You might even start with that first before jumping into a website. You also might find you like some of the other options they discuss more than {distill}.

• The distill documentation, which also happens to be a … distill website!

• Other people’s distill websites: Ijeamaka Anyene, Shannon Pileggi(aka Piping Hot Data), Miles McBain, Tom Mock, and more!

• Alison Hill’s website for A+ content and design inspiration. I think I find a new resource every time I visit her site. For example, check out her talk on Recent updates in the R markdown family.

• And more! I’ll try to make note of difference resources I used throughout the blog.

If you would like to follow along with the video I created, find it here.

Building the site

Now, let’s get on to creating the site. I am going to embed YouTube videos along the way. This is actually all the same YouTube video, but I will set them at the point I am discussing so it’s easier for you to skip parts if you’d like.

Setting up a GitHub repo & starting the project

See Tom Mock’s post here. I think his way of doing this makes more sense than mine. Unfortunately, I saw it after I did mine :(

I’m trying to get into the habit of starting all my projects with a GitHub repo. So, that’s what I did here, too. Here are all the steps:

• Create a repo
  
• Create project in R Studio by cloning the repo
  
• Load {distill} library
  
• Create a “starter” site using the create_website() function. I used this rather than create_blog() because I wanted to to make my main page an About page rather than the blog. I will add the blog part later. Read the {distill} documentation to help you decide which you should do. Because I created my GitHub repo first, I had to do some weird things to fix the folder structure. It works, but it’s a little ugly.
  • Move all files except the .Rproj one from the folder just created to the main repository folder.
    
  • Delete the website folder (should be empty except the .Rproj file).
    
  • Delete the README.md file in the main repository folder (when I didn’t, the site wouldn’t build later).

Or follow along in the video (through minute 8:04):

Building the site for the first time

Next, we want to build the site. In order to do this in an easy way, save all your files, close R Studio and reopen it, making sure to be in the project for your distill site. When you do this, a Build tab should appear in your panel in the upper right corner (or wherever you typically have your Environment, History, etc.). Click the Build Website icon and you should see your site! (8:25 in the video, if you want to see me do it.)

At this point, there are many different directions you could go. I’ll tell you about what I did. If you don’t want to do a lot more customization, you can jump to ?? to find out an easy way to publish your website.

Customize the home page

I wanted my “Home” page to be my “About” page. To do this, I first made some changes to the _site.yml file, deleting the “About” portion of the navbar and renaming the text for the homepage, “About”.

Then, to start customizing my “About” page, I add a photo of myself to the index.Rmd file and put in some placeholders for places I will write some information.

Follow along in the video (through minute 17:35):

Add the blog and create your first post

If you went the blog route from the beginning, you won’t need to do this part. Note that in the video, I did things in the wrong order

• Add a post using create_post("mypost"). This will generate an R Markdown file with the name mypost.Rmd (unless you change the slug), a _posts folder, and a folder that is titled with the date and the name of the post. By starting with the date, it will keep your posts in a nice order :)
  
• Edit your blog post R markdown file at will. Be sure to knit this file so that it shows up on the blog. These files are not knit automatically. That is purposeful.
  
• Create a new R Markdown file with ONLY a yaml heading with a title and listing. Save it to the main repository.
• Modify the _site.yml file to link the listing page. The text can be whatever you would like - this is what will show up on the navbar. The href value is the .html of the listing .Rmd file.
  
• Add a customized blog preview image. Put the image you want to use in the folder for the blog post. In the yaml heading of your blog’s R Markdown file, add preview: image.png where image.png is the name of your image. By default, the preview will be the first plot generated in your R code.

Follow along in the video (through minute 33:27):

Further modify _site.yml

In this part, I add some custom icons to the top navbar of the site. These include a personal favicon on the left side (I end up getting rid of it, though) and links to my GitHub, LinkedIn, and twitter pages (and later I add one to my YouTube channel).

Add the following to the _site.yml file after the navbar heading. Be careful of indentation. You can check out my file here (I have edited more since making the video, though).

- icon: fa fa-github
  href: https://github.com/YOUR_USERNAME
- icon: fa fa-linkedin
  href: https://www.linkedin.com/in/YOUR_LINKEDIN/
- icon: fa fa-twitter
  href: https://twitter.com/YOUR_TWITTER

To add a personalized favicon, add the following after navbar:, where ll.png is personal favicon. You can also add a link to a website where it goes when you click on it. Again, be careful of indenting.

  logo:
    image: ll.png

Follow the video below (through minute 44:22). When I did this the first time, I made some mistakes, so I have you skipping through that part of the video.

Publish the site via netlify

Now that you have a website, you can easily publish it via netlify. I will show you how to link it to your GitHub repo so that every time to you push changes to GitHub, your website will reflect those changes. I recommend setting up an account on netlify first.

Watch the video to see how I do it (through minute 48:22):

Make it yours!

The last piece is to do some customization. Thanks to the wonderful {distill} authors, we can use the create_theme() function to guide us through modifying some css. I am a complete novice when it comes to css, so having an easier way to work with it is extremely helpful. I highly recommend reading through the documentation about theming and the recent updates. And read thoroughly (I may not have done that the first time)!

• Use create_theme("my_theme") to generate a my_theme.css file with some starter css code.
  
• Make changes as desired.
  
• At the bottom, you can add custom css, too. In the video, I only made one change using custom css - changing the background color. And I did it incorrectly! I tried putting it in the middle of the {distill} css code, but I needed to put it at the bottom, after the {distill} css. You can see where I do it correctly in my current css file.
  
• Add theme: "my_theme.css" to the bottom of the _site.yml file.

You can watch the video until the end, if you’d like: