Hugo development snippets

I added a few things to this site that no one else will ever see, and you might want to add them to your Hugo site as well.

Link to open page in editor

When running in development, you can have Hugo generate a link to open the current page in your editor. This requires the editor to have a URL scheme.

I use VS Code, which supports vscode://file/... links.

The openEditor.html partial

{{/* Open the page in an editor.
   * Only makes sense in development mode.
   *
   * Usage: {{ partial "openEditor.html" . }}
   */}}
{{- if eq hugo.Environment "development" }}
<a href="vscode://file{{ .File.Filename }}" title="Open in editor">🖊 Open in editor</a>
{{- end }}

I place it in my base template so that all pages on my site get it. Here’s a screenshot:

Screenshot of the “Open in editor” link

The layout could be improved, but since it’s not visible in production that isn’t a priority for now.

Update: improve layout

(Updated 2023-09-11)

Ok I said it wasn’t a priority, but actually it annoyed me enough I made it a bit nicer. I added a little devmode box positioned absolutely at the upper left of the page (and upper center of the page on smaller screents). It includes my “open in editor” link and a link to the control panel.

Screenshot of the development navigation box

The devmodenav.html partial

{{- if eq hugo.Environment "development" }}
  <section class="devmodenav">
    <div class="devmodenav-links-container">
      <ul>
        <li class="devmode-title">
          {{ partial "svgsprite.html" "fontawesome/solid/terminal" }}Development
        </li>
        <li>
          <a href="/controls">{{ partial "svgsprite.html" "fontawesome/solid/cog" }}Control panel</a>
        </li>
        <li>
          <a href="vscode://file{{ .File.Filename }}">🖊 Open in editor</a>
        </li>
      </ul>
    </div>
  </section>
{{- end }}

The devmodenav.scss styles

.devmodenav {
  position: absolute;
  top: 0;
  left: 2em;
  display: flex;
  justify-content: center;
  margin: 3em 0 0 0;

  .devmodenav-links-container {
    padding: 0.25em 2em 0 0;
    margin: 0;
    ul {
      padding: 0 1em 0 0;
      border: 1px solid var(--devmode-emphasize-border-color);
      li {
        &.devmode-title {
          color: var(--devmode-emphasize-fg-color);
        }
        a {
          color: var(--body-fg-color-deemphasize-text);
        }
        list-style-type: none;
        font-size: 0.75em;
        line-height: 1.75em;
      }
      li:before {
        content: "";
      }
    }

  }
}

@media (max-width: 650px) {
  .devmodenav {
    position: static;
  }
}

List draft posts

I have a habit of writing notes for future posts in drafts, and I wanted to see all of these in one place. I used to use a simple Makefile target like:

.PHONY: list-drafts
list-drafts: ## Show all draft pages
	rg "draft: true" content/

But having them listed on a page where I can see them rendered as HTML is even better.

The draftsTable.html shortcode

{{/* Return all drafts in an HTML table
   *
   * Sort by section, then by date.
   */}}
<div class="mrl-simple-table-container">
<table>
  <thead>
    <tr>
      <th>Date</th>
      <th>Section</th>
      <th>Draft post</th>
    </tr>
  </thead>
  <tbody>
    {{ $pages := where .Site.Pages "Params.draft" true }}
    {{ $sortedPages := sort $pages "Section" "asc" }}

    {{ $uniqueSections := slice }}

    {{ range $sortedPages }}
      {{ $section := .Section }}
      {{ if not (in $uniqueSections $section) }}
        {{ $uniqueSections = $uniqueSections | append $section }}
      {{ end }}
    {{ end }}

    {{ range $section := $uniqueSections }}
      {{ $sortedSectionPages := sort (where $sortedPages "Section" $section) "Date" "desc" }}
      {{ range $sortedSectionPages }}
        <tr>
          <td>{{ .Date.Format "2006-01-02" }}</td>
          <td>{{ $section }}</td>
          <td><a href="{{ .RelPermalink }}">{{ .Title }}</a></td>
        </tr>
      {{ end }}
    {{ end }}
  </tbody>
</table>
</div>

I use /controls/drafts/ to display it, but it only renders in development mode. Here’s a screenshot:

Screenshot of the /controls/drafts page

List taxonomy terms

I also wanted a list of all taxonomy terms in one place. I already have /tags/ and /technologies/, but I have projcode and formulacode taxonomies that don’t generate their own pages for reasons beyond the scope of this post. Plus, I wanted to see all of the taxonomies on a single page.

I used to use a script that read frontmatter from all my content files and returned a list, but I realized I could make a webpage that does this for me too.

The taxonomyTermsList.html shortcode

{{/* Return an HTML list of all the terms for a given taxonomy.
   *
   * Usage: {{< taxonomyTermsList taxonomy="tags" >}}
   *
   * Arguments:
   *  taxonomy: The name of the taxonomy to list terms for.
   *  link: If set to "false", don't link to the term page.
   *    Our "projcode" and "formulacode" taxonomies do not generate term pages.
   */}}
{{ $taxonomy := .Get "taxonomy" }}
{{ with $.Site.Taxonomies }}
  {{ with index . $taxonomy }}
    <ul>
    {{ range $key, $value := . }}
      <li>
        {{ if (eq ($.Get "link") "false") }}
        {{ $key }}
        {{ else }}
        <a href="{{ $.Site.LanguagePrefix }}/{{ $taxonomy | urlize }}/{{ $key | urlize }}/">{{ $key }}</a>
        {{ end }}
      </li>
    {{ end }}
    </ul>
  {{ else }}
    <p>No terms found for taxonomy "{{ $taxonomy }}".</p>
  {{ end }}
{{ else }}
  <p>No taxonomies available.</p>
{{ end }}

I use /controls/taxonomies/ to display it. This one is available in the production site too so you can take a look there if you want to know what it looks like.

􀀂􀀟􀀍􀀅 􀀂􀀝􀀊 Hugo development snippets

Link to open page in editor

Update: improve layout

List draft posts

List taxonomy terms

Responses