Download Font Files

To download the font files and import them, we need to move the foncts.css to ~/static/css. The fonts.css file sets up fonts for the site, which could be done in main.css.

We also need to move the font files themselves. We can define a font class, but the site still needs a font file to implement that font, similar to installing new fonts on your computer. Blogdown stores font files in ~/static/fonts. We can get fonts from a lot of places, but a great resource is Google Fonts. Select a font and download the files. One of the fonts I selected, Rubik, provided a variable font instead of a static font - you can read about the difference here. The files included are all .ttf, but we need .woff2. We can use this free conversion tool. Once the files are converted we can add them to our ~/static/fonts folder.

# Copy & Edit CSS
fs::file_copy("themes/hugo-lithium/static/css/fonts.css", "static/css/fonts.css", overwrite = F)
usethis::edit_file("static/css/fonts.css")

# Copy font files
fs::dir_copy("themes/hugo-lithium/static/fonts", "static")

After adding the fonts to the folder, we need to import the fonts in our CSS. We can use the example from the variable font documentation as-is, but you can read more about the @font-face rule here.

@font-face {
    font-family: 'Rubik';
    src: url('../fonts/Rubik-VariableFont_wght.woff2') format('woff2 supports variations'),
       url('../fonts/Rubik-VariableFont_wght.woff2') format('woff2-variations');
    font-weight: 100 900;
    font-stretch: 25% 151%;
}

Use Font API

Alternatively, we can directly import the fonts into our CSS. I recommend this as it’s much easier, but it requires an internet connection when rendering the site. To do this select a font, choose the styles, and copy the style sheet code. Make sure to select all the styles and weights you want available.

@import url('https://fonts.googleapis.com/css2?family=Rubik:wght@300;400;500;700;800;900&display=swap');
@import url('https://fonts.googleapis.com/css2?family=Overpass:wght@100;500;700;800;900&display=swap');
@import url('https://fonts.googleapis.com/css2?family=Roboto:wght@100;300;500;700;900&display=swap');
@import url('https://fonts.googleapis.com/css2?family=Merriweather:wght@300;400;700&display=swap');
@import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@300;400;500&display=swap');

Apply New Fonts

We can add we can add the font to HTML elements or CSS selectors’ properties. We want to change the font of the navbar buttons so we’ll change the font-family property of the CSS selector .nav-links li. We can also make other changes like increasing font-size, weight, etc. Regarding font-size, you can use rem or em instead of px sizes, which scale to the browser settings, learn more here. I chose to use rem. Also, I set fallback fonts as recommended if you read about web safe fonts. I don’t think it’s necessary to fall back to serif or monospace unless you want to ensure a specific typeface, the browser will fallback to something automatically.

body {
  font-family: Roboto, Merriweather;
  font-size: 1rem;
}

.nav-links li {
  display: inline-block;
  margin: 0 0 0 15px;
  font-family: Rubik, Overpass;
  font-size: 1.25rem;
}

That all looks great, but it’d also be nice to have some behavior when the user hovers on the button. We can do that by modifying a CSS selector with :hover. The :hover is a CSS Pseudo-selector applied to elements when you mouse over them. There are many Pseudo-selectors available you can read about here. The main CSS file already has a .nav-links a:hover selector so we can add a font-weight and text-decoration property to that. There’s a lot more we can do with buttons, but this site is very minimalist so I think this style works well. However, you can see several other options and how to implement them here. 

.nav-links a:hover {
  color: #000;
  font-weight: bold;
  text-decoration: underline;
}

I also decided to remove 5px worth of padding from the navbar to make it just a tad shorter…

.header {
  padding: 15px 0;
  position: relative;
  background: #F6F9FB;
  border-bottom: 1px solid #eaeaea;
}

Now we have a simple, but functional navbar!

Fonts

We already changed fonts in the navbar so I won’t walk back through the entire process, but here’s the CSS code I used to modify fonts throughout my content. I just repeated the some process of finding parts of the page I wanted to modify, finding the CSS selectors, importing the font I wanted, and applying it to the CSS selector. 

.nav-links li {
  display: inline-block;
  margin: 0 0 0 15px;
  font-family: Rubik, Overpass;
  font-size: 1.25rem;
}

h1, h2, .article-title {
  font-family: Roboto, Merriweather;
  font-size: 1.5rem;
  font-weight: bold;
}

h3, h4, .article-duration, .archive-item-link {
  font-family: Roboto, Merriweather;
  font-size: 1.3em;
  font-weight: bold;
}

h5, h6, .footer {
  font-family: Roboto, Merriweather;
  font-size: 1rem;
  font-weight: bold;
}

.article-date {
  font-family: Roboto, Merriweather;
  font-size: .9rem;
}

body {
  font-family: Roboto, Merriweather;
  font-size: 1rem;
}

code {
  font-family: Fira Code, Source Code Pro, monospace;
  font-weight: 300;
}

Now we have a blog with a custom navbar and fonts throughout all of the content. However, you might notice some content doesn’t pick up our CSS configurations.

Style Raster Graphics

When we publish blog posts we’ll render all sorts of content using R libraries. Unfortunately, the outputs from our R code may not easily integrate to our site and this can be one of the trickier parts of maintaining a nice looking blog, especially if you choose a highly styled theme 😬 In this case, the image a raster graphic. Raster graphics are image files (pixels), which have no use for CSS code. We need to apply the same properties to our R graphics to match the style of the site. This applies to any plotting using the graphics device including ggplot2 😲

We can resolve this problem a few different ways, but the first and most obvious approach is to customize the ggplot2 theme. The theme() function in ggplot2 provides a huge number of settings that can be used to customize the output including color, font, background, etc. This really becomes more of a ggplot2 tutorial, so I’m going to skip a bit of the details but the aforementioned resources should provide more than enough to customize your ggplot2 output for your blog. I try to be DRY (do not repeat yourself) when possible so I created a few themes for my blog for different visual types (e.g. one for standard visuals, one for faceted plots, one for non-grid based plots like network diagrams, etc.). Below is a gist of my standard theme if it’s a helpful starting point. You can choose existing themes and add onto them as show below (i.e. theme_minimal() + theme(...)).

blogdown::shortcode("gist", "mark-druffel", "83b839abe61d056a2b4cef81d09f7bcc")

Depending how you style your blog, I think you could also use thematic and bslib, but since the blog doesn’t use bootstrap by default I personally haven’t tried to do that… Aside from the theme, some other helpful resources when using ggplot2 in blogdown include ggthemes, ragg, showtext, and ggtext.

library(ragg)
library(showtext)
library(tidyverse)
library(ggrepel)
# Tell knitr to use ragg for graphics
knitr::opts_chunk$set(dev = "ragg_png")
# font_add_google is a function in sysfonts which is loaded by showtext
font_add_google("Rubik", "rubik")
font_add_google("Roboto", "roboto")
font_add_google("Fira Code", "firaCode")
# Adding a noticeable font just to make sure everything is working
font_add_google("Homemade Apple", "homemadeApple")
showtext_auto()
theme_void_blog <- function(...){
  ggplot2::theme_void() + 
    ggplot2::theme(
      text = ggplot2::element_text(
        family = "roboto",
        size = 11, 
        inherit.blank = FALSE),
      title = ggplot2::element_text(
        family = "homemadeApple",
        face = "bold",
        size = 18, 
        inherit.blank = FALSE,
        hjust = .5),
      plot.subtitle = ggplot2::element_text(
        family = "homemadeApple",
        size = 14, 
        inherit.blank = FALSE), 
    legend.title = ggplot2::element_text(
      family = "rubik", 
      size = 12,
      face = "bold",
      inherit.blank = FALSE,
      hjust = .5), 
    legend.text = ggplot2::element_text(
      family = "roboto", 
      color = "#33334D", 
      size = 10, hjust = 0)
    ) + 
    ggplot2::theme(...)
}

tibble::tibble(
  #value = c(280, 60, 20),
  value = c(280, 60, 20),
  name = c('Sky', 'Shady side of pyramid', 'Sunny side of pyramid'),
  color = c('#0292D8', '#F7EA39', '#C4B632')
) |> 
  ggplot(aes(x = "", y = value, label = name, fill = color)) + 
  geom_col() + 
  coord_polar(theta = "y", start = pi / 1.275, direction = -1) +
  scale_fill_identity() +
  geom_text_repel(family = "roboto", size = 5, nudge_x = .6, show.legend = FALSE, segment.color = "transparent") +
  labs(title = "To make sure showtext is working") +
  theme_void_blog() 

CSS Conflicts

Some htmlwidgets have generic CSS selectors that are in main.css, but no way to modify them through the library. An example I’ve bumped into in the past was the library skimr. These selectors were probably chosen intentionally to try to easily match site styles, but sometimes it doesn’t look great. To avoid those conflicts, throughout your entire main.css file you can use a prefix for the site. For example, you could change .header to .site-header.

# Find and replace ".header {"  to ".site-header {"
usethis::edit_file(main_css)

If you do that, you’ll have to find references of that class in your html partials. First, move the partial from the theme as we’ve mentioned before. WARNING, WE MODIFY THIS FILE SEVERAL PLACES. DO NOT RUN THIS CODE IF YOU ALREADY MOVED THIS FILE INTO YOUR PARTIALS FOLDER, IT WILL ERASE YOUR WORK!

fs::file_copy(paste0(here::here(),'/themes/hugo-lithium/layouts/partials/header.html'), paste0(here::here(), '/layouts/partials/header.html'))

You’d need to modify header.html to the code below by changing the <header class="header"> to <header class="site-header">.

<!DOCTYPE html>
<html lang="{{ .Site.LanguageCode }}">
  <head>
    {{ partial "head.html" . }}
  </head>
  <body>
    <div class="wrapper">
      <header class="site-header">
        {{ partial "nav.html" . }}
      </header>

Section Links

Sometimes you want to refer a user to a prior section. Do this the same way you add a hyperlink, but replace spaces in the section name with hyphens. For example, to refer someone back to the beginning of this entire section I would use [this](#build-a-site-from-scratch). which does this.

Bullets

I often add bullets and the style looks terrible because markdown isn’t actually recognizing them as bullets. This is caused by two mistakes I commonly make: 

• Keep one line between the paragraph above the bullets and the bullets themselves.
  
• Make sure you end the above paragraph and each bullet with a linebreak.
  

Linebreaks

According the markdown documentation:

CommonMark and a few other lightweight markup languages let you type a backslash () at the end of the line, but not all Markdown applications support this, so it isn’t a great option from a compatibility perspective.

The markdown docs instead recommend using two spaces (which is impossible to see in the IDE) or
at the end of a line. I’ve gotten into the habit of using backslash, but
seems like a good option as well.

High Level Overview

The codefoling is made possible by a JS function, we’ll call it codefolding.js, which searches each page for code based on the HTML classes assigned by blogdown. When it finds code, it wraps it in an HTML div and adds a button. The JS function collapses the div when the button is clicked. That JavaScript function needs to be available to the pages, which means it needs to be in the header or footer of each HTML page. Further, that function relies on other code from bootstrap and custom CSS which need to be loaded first.

Add Dependencies

Sebastian wrote his codefolding blog post using Bootstrap 3 relying on collapse.js, dropdown.js, and transition.js, the last of which was deprecated in Bootstrap 4. I’m not enough of a Bootstrap guru to know where that functionality lives in Bootstrap 4 and frankly didn’t want to bother working through that for this one feature on my site - so I just stuck with Bootstrap 3, it works just fine. Those bootstrap functions rely on jquery so you need to download that as well. Finally, we’ll need popper.js to allow scrolling within our code boxes, but James’ post provided an API so we’ll just add it in our partials. For posterity, you can just download the bootstrap.min.js file, but I stuck with the three functions only since that’s all I needed.

• Bootstrap 3 Latest Version
• Jquery - I used 3.6.1

Add the JS files to the static/js folder. As we learned when changing the home button, the static/js files will override the files inside ~/themes/hugo-lithium/static. I this case, those files aren’t in ~/themes/hugo-lithium/static/images/logo.png so they’re simply additive. Again, you only need the three specific files or bootstrap.bundle.min.js, not all four as shown below.

Aside from JS, we’ll also need some CSS to format the div around the code block and the button that controls it. Ideally, we’d just use a recent Bootstrap distribution like this which does work, but it conflicts with other parts of the theme - for me it knocked things out of place in the navbar. We’d need to modify our main.css to manage the conflicts between that file and the boostrap file which could be a lot more work than just creating a custom CSS file for the code folding, which is what I decided to do. Copy the code below and save it at ~/static/css/codefolding.css. If you want to make your button look different (e.g. different color, hovering behavior, etc.), this is the place to do that.

#code-folding-buttons {float: right;}
#code-folding-buttons .pull-right > .dropdown-menu {
    right: 0;
    left: auto;
}
#code-folding-buttons .btn.btn-default.btn-xs.dropdown-toggle {
    float: right;
}
#code-folding-buttons.open > .dropdown-menu {
    display: block;
}
#code-folding-buttons .dropdown-menu li {
    padding: 5px;
}

/* Each code block button */
.code-folding-btn { 
  margin-right: 10px;
  margin-bottom: 4px; 
  width: 125%;
  background: #fff;
  border-top: #252525 1px solid;
  border-bottom: #252525 1px solid;
  border-left: #252525 2px solid;
  border-right: #252525 2px solid;
  border-radius: 10px;
  text-align: center;
  color: black;
  padding: 6px;
  float: right;
  font-family: Rubik;
  font-size: .75rem;
  font-weight: 400;
}

.code-folding-btn:hover { 
  background: #252525;
  border-top: #fff 1px solid;
  border-bottom: #fff 1px solid;
  border-left: #fff 2px solid;
  border-right: #fff 2px solid;
  color: white;
  font-family: Rubik;
  font-size: .75rem;
  font-weight: 600;
}

.row { 
    display: flex;
    border-bottom: solid 1px #d7d7d7;
}
.col-md-12 {
    margin: 0 0 0 auto;
}

.collapse {
    display: none; 
}
.in { 
    display: block ;
    border: solid 1px #d7d7d7;
    border-radius: 5px;
}

/* Main show/hide button */
#code-folding-buttons {float: right;}

#code-folding-buttons .dropdown-menu {
    min-width: 80px;
    padding: 5px 0;
    margin: 2px 0 0;
    font-size: 14px;
}

Add Modify Partials

Now that we have dependencies in place, we need to add the necessary HTML partials so that the dependencies are added when the site is rendered by Hugo. You can structure your partials however you want, but each theme generally has things structured a certain way that might be easy to piggy back off of. Below is some R code to copy files from the existing theme (hugo-lithium specific) and create new files we need.

fs::file_touch(paste0(here::here(), '/layouts/partials/header_maincodefolding.html'))
fs::file_copy(paste0(here::here(),'/themes/hugo-lithium/layouts/partials/head_custom.html'), paste0(here::here(), '/layouts/partials/head_custom.html'))
fs::file_copy(paste0(here::here(),'/themes/hugo-lithium/layouts/partials/header.html'), paste0(here::here(), '/layouts/partials/header.html'))

Notice partials have if statements in them, such as {{ if eq .RelPermalink "/" }} ... {{ else }}{{ if .Description }} ... {{ end }}{{ end }}. These if statements reference variables in config.yaml, it’s how the config.yaml is able to parameterize a Hugo site. When the site is rendered, Hugo reads the yaml and includes HTML partials based on the if statements. I actually don’t use parameters for my codefolding, but Sebastien set them up in his post and I left them in here for people who may want them - and to just better illustrate how Hugo works. You can completely remove all the if statements in the partials we create and leave the parameters off of the config file if you like. 

header_alldoc_codefolding_button.html

Optionally, Sebastien added a code folding button at the top of all posts which can show or hide code throughout the document. It looks like the screenshot below:

I decided to leave this off of my site because I don’t like putting it in the navbar and it just felt clunky at the top of the doc. I would want to modify the navbar and use an icon in the top right, but didn’t seem worth the work. This is the html partial to do that though which I called header_alldoc_codefolding_button.html. You can copy it either way if you like, it won’t be rendered unless it’s added to another partial file.

{{ if and (not .Site.Params.disable_codefolding) (not .Params.disable_codefolding) (in (string .Content) "</pre>") }}
<div id="code-folding-buttons" class="btn-group pull-right">
  <button type="button" class="btn btn-default btn-xs dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true" data-_extension-text-contrast="">
    <span>Show/Hide all code</span> 
    <span class="caret"></span>
  </button>
  <ul class="dropdown-menu" style="min-width: 50px;">
  <li><a id="rmd-show-all-code" href="#">Show All Code</a>
  </li><li><a id="rmd-hide-all-code" href="#">Hide All Code</a></li>
  </ul>
</div>
{{ end }}

head_custom.html

The lithium template has a head_custom.html file by default, which is empty. It’s already loaded into the site so we don’t have to modify / create as many partials to implement our code folding by using it. We can use this to load dependencies into the site’s header. First, we’ll load the jquery, bootrap, and popper.js dependencies. Next, we load codefolding.js and codefolding.css. Finally, we can run codefolding.js (i.e. within $(document).ready). If you don’t plan to use config.yaml to disable code folding on certain posts you can omit the if statements.

{{ if not .Site.Params.disable_codefolding }}
<script src="{{ "js/jquery-3.6.0.min.js" | relURL }}"></script>
<script src="{{ "js/transition.js" | relURL }}"></script>
<script src="{{ "js/collapse.js" | relURL }}"></script>
<script src="{{ "js/dropdown.js" | relURL }}"></script>
  <script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js"></script>
{{ end }}
{{ if and (not .Site.Params.disable_codefolding) (not .Params.disable_codefolding) (in (string .Content) "</pre>") }} 

<script src="{{ "js/codefolding.js" | relURL }}"></script>
<link rel="stylesheet" href="{{ "css/codefolding.css" | relURL }}" />
<script>
$(document).ready(function () {
  window.initializeCodeFolding("show" === {{ if isset .Params "codefolding_show" }}{{ .Params.codefolding_show }}{{ else }}{{ default ("hide") .Site.Params.codefolding_show }}{{ end }});
});
</script>
{{ end }}

The head_custom.html partial is pulled into the ~/themes/hugo-lithium/layouts/partials/head.html partial, which we don’t need to modify or move out of themes. It’s loaded on the last line below with no if statement (i.e. it’s always loaded).

<!DOCTYPE html>
<html lang="{{ .Site.LanguageCode }}">
  <head>
    {{ partial "head.html" . }}
  </head>
  <body>
    <div class="wrapper">
      <header class="header">
        <!-- Add this if you want the butto to callapse and show all code on a page --> 
        {{ partial "header_alldoc_codefolding_button.html" . }}
        {{ partial "nav.html" . }}
      </header>

Setup Config

If you included the if statements in the partials, add these parameters to config.yaml at level 1 (i.e. not nested underneath anything in the file).

# Set to true to disable code folding
disable_codefolding: false
# Set to "hide" or "show" all codes by default
codefolding_show: hide
codefolding_nobutton: true

And voila, you have code folding!

Pages with code should now have a button beside the code which will expand and collapse the code.

footer.html

I don’t use RSS feed at the moment, so I removed that. I might add it back at some point if I can get into a better groove with posting. I added an email, github, twitter, linkedin, and a credit to the blogdown repo. 

      <footer class="footer">
        <ul class="footer-links">
          {{ with .Site.Params.social }}
          <li>
            <a href="mailto: mark.druffel@gmail.com" class="fa fa-envelope " aria-hidden="true" title="Email"></i><span class="sr-only">Github</span></a>
          </li>
          <li>
            <a href="https://github.com/{{ .github }}"><i class="fa fa-github" aria-hidden="true" title="Github"></i><span class="sr-only">Github</span></a>
          </li>
          <li>
            <a href="https://twitter.com/{{ .twitter }}"><i class="fa fa-twitter" aria-hidden="true" title="Twitter"></i><span class="sr-only">Twitter</span></a>
          </li>
          <li>
            <a href="https://www.linkedin.com/in/{{ .linkedin }}"><i class="fa fa-linkedin" aria-hidden="true" title="LinkedIn"></i><span class="sr-only">LinkedIn</span></a>
          </li>
          {{ end }}
          <li>
            <a href="https://gohugo.io/" class="footer-links-kudos">Made with <img src="{{ "images/hugo-logo.png" | relURL }}" alt="Img link to Hugo website" width="22" height="22"></a>
          </li>
          <li>
            <a href="https://bookdown.org/yihui/blogdown/" class="footer-links-kudos">Via <img src="{{ "images/blogdown-logo.png" | relURL }}" width="22" height="22"></a>
          </li>
        </ul>
      </footer>
    </div>
    {{ partial "footer_highlightjs" . }}
    {{ partial "footer_mathjax" . }}
    {{ template "_internal/google_analytics.html" . }}
  </body>
</html>

If you render the site with this partial you’ll end up with this footer, which is really ugly. The reason is we referenced font awesome logos in the footer.html partial so we need font awesome to render the logos. We need to add a font awesome dependency in the site header or footer to do that.

head_custom.html

WARNING, WE MODIFY THIS FILE SEVERAL PLACES. DO NOT RUN THIS CODE IF YOU ALREADY MOVED THIS FILE INTO YOUR PARTIALS FOLDER, IT WILL ERASE YOUR WORK! The lithium template has a head_custom.html file by default, which is empty. It’s already loaded into the site so we don’t have to modify / create as many partials to implement our code folding by using it. We can use this to load dependencies into the site’s header.

fs::file_copy(paste0(here::here(),'/themes/hugo-lithium/layouts/partials/head_custom.html'), paste0(here::here(), '/layouts/partials/head_custom.html'))

At the top of head_custom.html, add this line. The async part of the code keeps the site from loading slowly when font awesome doesn’t respond instantaneously.

<script async src="https://use.fontawesome.com/32c3d13def.js"></script>

Now the footer looks better, but it’s still missing the image at the end. That’s the blogdown package logo which I added manually since it’s not in font awesome. Add the required image to ~/static/images and make sure the name matches the filename in the HTML partial footer.html.

Once you add the blogdown logo file, the footer should look like this. 

disqusShortname

Disqus is a simple way to add a comments box on your site. Disqus has helped me engage with other data scientists through their sites which is a super simple way to connect with other people in the profession. It’s so simple, I highly recommend it. To use Disqus on your site, you need to create an account and then create a new site on that account. When you create a site, you give it a shortname which you can then add to the config.yaml.

baseurl: /
languageCode: en-us
title: DocStation Analytics
theme: hugo-lithium
googleAnalytics: ''
disqusShortname: 'add the name here'

canonifyURLs

Tells Hugo to use canonical urls.

baseurl: /
languageCode: en-us
title: DocStation Analytics
theme: hugo-lithium
googleAnalytics: ''
canonifyURLs: true

enableRobotsTXT

Tells Hugo to use a custom robots.txt file, which tells bots how to interact with your site. Learn more here. To modify the robots.txt file, add the below code to the config.yaml.

baseurl: /
languageCode: en-us
title: DocStation Analytics
theme: hugo-lithium
googleAnalytics: ''
enableRobotsTXT: true

Then create a new robots.txt file at ~/layouts/robots.txt.