Embed GitHub Gist in Hugo posts

Embed GitHub Gist in Hugo posts

I was approached by Divya Akula with a suggestion to use a link to GitHub for my script and I really bought in the idea because I used to do it on Wordpress. I started googling and trying out solutions which did not work and messed up my blog repo. Fortunately being MVP I have access to GitHub Copilot and asked Copilot with a simple prompt which gave me a simple straight forward looking solution.

Notes: This section is generated by GitHub Copilot using the prompt “how to embed github gist within hugo site” and I amended it with caveats and examples I used.

To create a custom shortcode in Hugo, follow these steps:

  1. In your Hugo site’s directory, navigate to the layouts/shortcodes directory. If it doesn’t exist, create it.

  2. Inside the shortcodes directory, create a new file with the name of your shortcode. For example, if you want to create a shortcode named gist, you would create a file named gist.html.

  3. In this file, write the HTML that you want the shortcode to output. For a gist shortcode, you might write something like this:

<script src="https://gist.github.com/{{ .Get 0 }}/{{ .Get 1 }}.js"></script>

This code will create a script tag that links to the Gist specified by the parameters passed to the shortcode.

  1. Save the file. You can now use your custom shortcode in your markdown files like this: Replace username with your GitHub username and gist_id with the ID of the Gist you want to embed.

Example for gist url https://gist.github.com/reshmee011/c23123e5f1abedd1085876279ac17b7f

When you build your Hugo site, the shortcode will be replaced with the HTML you specified in the shortcode file.

Caveats

Don’t update the theme layouts section

I did that and broke my theme.

11:51:20 PM: Starting to prepare the repo for build
11:51:21 PM: Failed during stage 'preparing repo': From https://github.com/reshmee011/m365blogs
 * branch            main       -> FETCH_HEAD
   12c52c1..89bd13c  main       -> origin/main
Fetching submodule Hugo/sites/M365Blog/themes/ananke
From https://github.com/theNewDynamic/gohugo-theme-ananke
   a1a99cf..f34c219  master     -> origin/master
fatal: remote error: upload-pack: not our ref a6af9573bf68429ff0eb1e66a0d9dd53d54654db
Errors during submodule fetch:
	Hugo/sites/M365Blog/themes/ananke
: exit status 1
11:51:21 PM: Preparing Git Reference refs/heads/main
11:51:21 PM: Error pulling repository: From https://github.com/reshmee011/m365blogs
 * branch            main       -> FETCH_HEAD
   12c52c1..89bd13c  main       -> origin/main
Fetching submodule Hugo/sites/M365Blog/themes/ananke
From https://github.com/theNewDynamic/gohugo-theme-ananke
   a1a99cf..f34c219  master     -> origin/master
fatal: remote error: upload-pack: not our ref a6af9573bf68429ff0eb1e66a0d9dd53d54654db
Errors during submodule fetch:
	Hugo/sites/M365Blog/themes/ananke
: exit status 1
11:51:21 PM: Failing build: Failed to prepare repo

I deleted and readded the theme to fix using

$ git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

However still had some issues building my site.

Potential errors

1:26:46 AM: Error: Error building site: failed to render pages: render of "home" failed: "/opt/build/repo/Hugo/sites/M365Blog/themes/ananke/layouts/index.html:48:23": execute of template failed: template: index.html:48:23: executing "main" at <.Site.GetPage>: can't evaluate field Site in type string
Total in 423 ms
1:26:46 AM: ​
1:26:46 AM: "build.command" failed                                        
1:26:46 AM: ────────────────────────────────────────────────────────────────
1:26:46 AM: ​
1:26:46 AM:   Error message
1:26:46 AM:   Command failed with exit code 255: hugo --gc --minify -b $URL (https://ntl.fyi/exit-code-255)
1:26:46 AM: ​
1:26:46 AM:   Error location
1:26:46 AM:   In build.command from netlify.toml:
1:26:46 AM:   hugo --gc --minify -b $URL
1:26:46 AM: ​
1:26:46 AM:   Resolved config
1:26:46 AM:   build:
1:26:46 AM:     base: /opt/build/repo/Hugo/sites/M365Blog
1:26:46 AM:     command: hugo --gc --minify -b $URL
1:26:46 AM:     commandOrigin: config
1:26:46 AM:     environment:
1:26:46 AM:       - NODE_ENV
1:26:46 AM:       - TZ
1:26:46 AM:       - HUGO_VERSION
1:26:46 AM:       - HUGO_ENV
1:26:46 AM:     publish: /opt/build/repo/Hugo/sites/M365Blog/public
1:26:46 AM:     publishOrigin: config
1:26:46 AM: Build failed due to a user error: Build script returned non-zero exit code: 2
1:26:46 AM: Failing build: Failed to build site
1:26:46 AM: Finished processing build request in 26.545s

Resolutions

Ultimately I reverted to a commit which worked using the git reset

git reset 12c52c1e031abf9fab7cdf077dd088644eb1e294
git push

I followed the instructions provided by github copilot under my site folder creating the layouts > shortcodes folder before creating the gist.html file and it worked.