Hugo Academic Source Links

Source Links

If you’ve ever noticed, at the top of any Tidyverse documentation page is a link to the source file for the functions described on the page.

This level of out-there transparency may or may not be what you want in your blog. But it’s especially useful in a work context.

Consider the scenario:

• Aasif runs an analysis in January and writes about it in the team blog. Stakeholders and others throughout the company read about it there.
• Bianca, a VP, is looking at the results 3 months later and is curious if they still hold with the new data that’s come in, or if we tweak such-and-such an assumption.
• But Aasif is on vacation, so Bianca asks Charlie to run the analysis. She shows him the post where she read about it all. The source link literally could not be more obvious, right at the top of the post. So Charlie has a much easier time re-running it.

Now we all know that’s not the end of the story; it only means he’s found the file! But finding the file that easily is not at all trivial in a multi-team environment.

So I’ve implemented these little links at work, and I’ve done it here as well. It’s actually pretty easy to do.

How to Add Source Links

It takes no more than 6 steps—counting liberally. After we walk through those steps, I’ll explain how they work.

1. In config/_default/params.toml find this line and ensure it’s accurate:

   # Enable visitors to edit pages?
   #   `repo` defines the repository URL. `editable` defines which page types can be edited.
   edit_page = {repo_url = "https://github.com/BenjaminWolfe/benjamin", content_dir = "", repo_branch = "main", editable = {docs = true, page = false, post = false}}

2. Add these lines after it:

   # Show source links?
   #   `source_path` is everything between `repo_url` and `repo_branch` (above)
   #   in the link to an Rmd, ipynb, or md file. It varies from provider to provider.
   show_source_links = true
   source_path = "/blob/"

3. Find the file themes/hugo-academic/layouts/partials/page_metadata.html and copy it to layouts/partials/page_metadata.html. (That is, copy it from themes/hugo-academic into the root of your site.) This is how you override a template in Hugo; that way if you update your Hugo Academic theme, you won’t lose your changes.

4. At the top of the file after $is_list and $page are defined, add this line:

   {{ $source_url := print $page.File.Dir $page.File.BaseFileName ($page.Params.source_extension | default ".md") }}

5. Then, after the section on article reading time, add this code block:

     {{ if and (site.Params.show_source_links) (eq $page.Type "post") }}
     <span class="middot-divider"></span>
     <span class="source-reference">
       <a href="{{ site.Params.edit_page.repo_url }}{{ site.Params.source_path }}{{ site.Params.edit_page.repo_branch }}/content/{{ $source_url }}" target="_blank" rel="noopener">{{ $source_url }}</a>
     </span>
     {{ end }}

6. Finally, when you start each post, include this in the YAML:

   source_extension: '.Rmd'

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.

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