Embedding ain't easy, but its alright

I write a lot of blog posts which contain code snippets. Like most people, I have done this using a fenced codeblock in markdown which is fine for short blocks of code.

The problem occours when I am embedding code from another repository; often there will be tweaks or bug fixes, and keeping the code in the blog post in sync with the code in the other repo is annoying and manual.

To make life easier for myself, I wrote a shortcode called git-embed, which at build time will fetch the specified file, and embed either the whole file, or a line range in a highlighted code block. It supports line ranges (start, finish), and it will use the file’s extension as the highlight language, unless you override with lang parameter.

Usage is like this:

{{< git-embed
  user="Pondidum"
  repo="pondidum.github.io"
  ref="master"
  file="layouts/shortcodes/git-embed.html"
  lang="go"
>}}

Which I am using to embed the shorcode’s own shortcode:

{{- $user := .Get "user" -}}
{{- $repo := .Get "repo" -}}
{{- $ref := .Get "ref" -}}
{{- $file := .Get "file" -}}


{{- $source := printf "https://github.com/%s/%s/blob/%s/%s" $user $repo $ref $file -}}
{{- $url := printf "https://raw.githubusercontent.com/%s/%s/%s/%s" $user $repo $ref $file -}}
{{- $remote := resources.GetRemote $url -}}

{{ $all_lines := split $remote.Content "\n" -}}

{{- $start := 1 -}}
{{- if isset .Params "start" -}}
  {{- $start = (.Get "start") | int -}}
{{- end -}}

{{- $finish := len $all_lines -}}
{{- if isset .Params "finish" -}}
  {{ $finish = (.Get "finish") | int -}}
{{- end -}}

{{- $start = math.Max $start 1 -}}
{{- $finish = math.Min $finish (len $all_lines) -}}

{{- $lines := slice -}}
{{- range $index, $num := (seq (add $start -1) (add $finish -1)) -}}
  {{- $lines = $lines | append (index $all_lines $num) -}}
{{- end -}}

{{- $lang := strings.TrimPrefix "." (path.Ext $file) -}}
{{- if isset .Params "lang" -}}
  {{- $lang = .Get "lang" -}}
{{- end -}}

{{- $options := "" -}}
{{- if isset .Params "options" -}}
  {{- $options = .Get "options" -}}
{{- end -}}

{{- highlight ( delimit $lines "\n") $lang $options -}}

<footer style="margin: 10px auto;">
  <small><a href="{{- $source -}}">Source</a></small>
</footer>

Future Improvements

I’d quite like to add a parameter that would allow me to embed a named function, rather than a line range. I think I’d use Tree-Sitter to do this, but Hugo doesn’t seem to have a way to execute an arbitrary command on build, so I’d need to make a small API that would do all the work… So that can wait for when the itch needs scratching more than this.

Future Improvements#

Future Improvements