Github Shortcodes for the Hugo Static Page Generator

Hugo (the static page generator I use for this website) provides various integrations for linking to or embedding content on Youtube, Twitter, Vimeo etc out of the box. This is super nice, but unfortunately it doesn’t have such an integration for Github - and I link a lot to various GitHub repositories, issues, pull requests or commits in my posts.

I thought it would be nice to have some proper integration for this, so I created two Hugo shortcodes which can take github references:

• Github Buttons: A way to quickly inline link to a repo, issue or commit.
• Github Cards: A simple social card that shows the details of a repo, issue or commit.

Github References

Github provides a set of autolinked references which work as a great reference on how to best reference things on GitHub. For my shortcodes I took inspiration from this and came up with the following 3 short references:

• Repo: owner/repo
• Issue or Pull Request: owner/repo#issue ¹
• Commit: owner/repo@hash

Fetching resources and caching

I’m not going into the details on how to fetch data with hugo shortcodes² or how the GitHub REST API ³ works.

To avoid fetching all resources on each build, I decided to version/freeze the responses with my code, this can be done with the following config change:

caches:
  getresource:
    dir: :resourceDir/
    maxAge: -1

Github Button Shortcode

Luckily there’s already a nice to render nice GitHub buttons:⁴ .

Generally the existing github-buttons was great, but I had to add a few more Octicons (the icons used by Github) and I wanted to add coloring. Thankfully this wasn’t more then a few minor changes () and once done, it was very easy to build and copy over to hugo:

npm run build && cp dist/buttons.js ../../christian.kuendig.info/assets/js/github-buttons.js

now we just need to make sure to include this file in our template (see below).

Github Card Shortcode

I unfortunately didn’t find an equivalent for nice Github cards.

I found Github’s open graph images super nice⁵ and the Github blog goes into great detail on how they were built⁶, but unfortunately there’s no easy way to reproduce them, so I decided to take them as is and embed the images on my pages.

One little thing to work around is that these images are actually not exposed via the REST API so I had to craft my own URLs. It’s pretty straightforward and follows the general Github URL scheme, but it does include a cache hash. As I couldn’t reverse-engineer the hash, I had to make sure to generate it myself and make sure to invalidate it should the image update. For repos and issues I again used the REST API to get some data, for commits I decided to just use the commit has itself as I couldn’t identify a circumstance under which the image would update.

The end result looks pretty good I think:

Usage

1. Add the hugo-github repository as a submodule theme to your project

   git submodule add https://github.com/chkuendig/hugo-github.git themes/hugo-github
   

2. Add hugo-github as the left-most element of the theme list variable in your site’s or theme’s configuration file config.yaml or config.toml. Example, with config.yaml:

   theme: ["hugo-github", "my-theme"]
   

   or, with config.toml,

   theme = ["hugo-github", "my-theme"]
   

3. To use the github-button, don’t forget to include the necessary javascript by adding the following to layouts/partials/extend_head.html (might be different for your theme):

   {{if (.HasShortcode "github_button") }}
   {{- $githubButtons := resources.Get "js/github-buttons.js" }}
   {{- if hugo.IsProduction }}
     {{- $githubButtons = minify $githubButtons }}
   {{- end }}
   <script src="{{ $githubButtons.RelPermalink }}" data-no-instant
     {{- if site.Params.assets.disableFingerprinting }}integrity="{{ $githubButtons.Data.Integrity }}"{{- end }}
   ></script>
   {{ end }}

4. Use either the github_button or github_card shortcodes as described above:

    {{< github_card "chkuendig/hugo-github" >}}
   

   or

   {{<  github_button "chkuendig/hugo-github" >}}