Hugo Academic Source Links

How Does It Work?

I think the Hugo docs are actually really intuitive and user-friendly, on a par maybe with the Tidyverse and jQuery docs. Reading through them even cursorily gives you a pretty good sense of how things work.

Site Parameters

Anything you put in config/_default/params.toml is accessible with site.Params.your_lowercase_toml_parameter.

  • This is where we get site.Params.show_source_links and site.Params.source_path, parameters you’ve just added yourself.
  • Two others already existed: site.Params.edit_page.repo_url and site.Params.edit_page.repo_branch.

Post Header YAML

Anything you put in the YAML headers of a file are accessible with .page.Params.your_lowercase_yaml_parameter. The accessor is slightly different in our code—it starts with $p instead of .p—only because $page is defined as equal to .page a few lines earlier.

This is where $page.Params.source_extension comes from. Note that if you are sure you’ll always be writing .Rmd files, you can hard-code this into the template! Then you can skip adding the parameter to your post headers.

Adding the parameter to the YAML means this same link can work for R Markdown, Jupyter Notebooks, or plain old markdown files.

Built-In Variables

$page.File.Dir and $page.File.BaseFileName are built-in page attributes, documented straightforwardly in the Hugo docs.

Variable Definition

Variables in Hugo are declared with the := operator. Later changes to the variable’s value can be made with = (no colon).


The default statement is a little trick I picked up from themes/hugo-academic/layouts/partials/page_edit.html, as I was looking to replace instances of master with main:

<a href="{{site.Params.edit_page.repo_url}}/edit/{{site.Params.edit_page.repo_branch | default "master"}}/{{$content_dir}}/{{.File.Path}}">

Here it’s reasonable to assume an .md file extension if one isn’t specified. This is especially the case if you happen to be using hugodown; hugodown will always have an .md file, since it allows Hugo to generate the HTML files server-side.

Curly-Curly Operators

layouts/partials/page_metadata.html is written in HTML. Anything between the double curly braces is run and, if there’s output, that output is included in the HTML. You might think of it as a glue statement writ large. The operators will be even more familiar to you if you’ve ever used the whisker package.

HTML Partials

layouts/partials/page_metadata.html is not a full web page; it’s a partial page dictating only how to display a page’s metadata. That allows this same HTML template to be reused in several places:

  • layouts/partials/page_header.html
  • layouts/partials/li_compact.html
  • layouts/partials/li_list.html
  • layouts/partials/li_card.html

You can trace through what is used where if you have your site open in RStudio by using the Command+Shift+F (or Control+Shift+F, for Window) “Find in Files” functionality.

page_header.html for example is in turn used in a whole host of HTML pages, including layouts/section/post.html. And that is how we end up seeing our output at the top of the page you’re currently reading.

Benjamin E. Wolfe
Data Scientist

Benjamin Wolfe is an R enthusiast, Python learner, and poet. He loves to write, if he can ever finish a blog post.