↓ Skip to main content
Knowledge Base
  1. Posts/

Blowfish + Hugo + Markdown Reference

·743 words·4 mins
Author
Derin Alan Ritter
making computers do stuff
Table of Contents

This post is my own reference. Each section shows a feature rendered live, with the source in a code block above so I can copy it.

Front matter
#

---
title: "Title"
summary: "Short summary used on list pages and meta tags"
description: "Used in <meta name=description>; falls back to summary"
date: 2026-05-04
lastmod: 2026-05-04
expiryDate: 2027-01-01
draft: false
slug: "custom-url-slug"
aliases: ["/old-url/"]
categories: ["Reference"]
tags: ["a", "b"]
series: ["My Series"]
series_order: 1
authors: ["derin"]
externalUrl: "https://example.com"
showHero: true
heroStyle: "basic"        # basic | big | background | thumbAndBackground
showAuthor: true
showDate: true
showDateUpdated: false
showReadingTime: true
showWordCount: true
showTableOfContents: true
showSummary: true
sharingLinks: ["twitter", "linkedin", "email"]
robotsNoIndex: false
xml: true
---

Markdown basics
#

Inline
#

bold, italic, both, strikethrough, inline code, a link, and a footnote.1

Lists
#

  • one
  • two
    • nested
  • three
  1. first
  2. second
  3. third
  • done
  • not done

Blockquote
#

Quotes can be nested.

Like this.

Tables
#

ColumnTypeNotes
idintprimary key
nametextindexed
created_attimestampUTC

Code blocks
#

def fib(n):
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return a

With line numbers and highlighted lines:

1
2
3

package main
import "fmt"
func main() { fmt.Println("hello") }

Raw HTML
#

Cmd+K, highlighted, H2O, x2.

Math (KaTeX)
#

Add the katex shortcode once anywhere on the page to load KaTeX, then write math with $...$ or $$...$$.

{{< katex >}}

Inline: $E = mc^2$.

Display:

$$ \int_{-\infty}^{\infty} e^{-x^2},dx = \sqrt{\pi} $$

Diagrams (Mermaid)
#

{{< mermaid >}}
graph LR
    A[Idea] --> B{Useful?}
    B -- yes --> C[Write post]
    B -- no --> D[Forget about it]
    C --> E[Publish]
{{< /mermaid >}}
graph LR
    A[Idea] --> B{Useful?}
    B -- yes --> C[Write post]
    B -- no --> D[Forget about it]
    C --> E[Publish]

Charts (Chart.js)
#

{{< chart >}}
type: 'line',
data: {
  labels: ['Jan','Feb','Mar','Apr','May'],
  datasets: [{ label: 'Posts written', data: [1,3,2,5,4] }]
}
{{< /chart >}}

Blowfish shortcodes
#

Alert
#

Warn the reader about something important.
Use any Blowfish icon as the first arg.

Lead
#

A larger intro paragraph that stands above the body copy.

Badge
#

New

Button
#

Visit my portfolio

Icon
#

Inline:

Keyword / KeywordList
#

A

highlighted keyword
mid-sentence.

hugo
blowfish
markdown

Tabs
#

npm install foo
pnpm add foo
bun add foo

Accordion
#

Click to expand
Hidden detail goes here. Useful for long FAQs or asides.

Timeline
#

  1. Started blog

    2026

    Set up Hugo + Blowfish.

  2. Wrote first real post

    2026

    Replaced the demo content.

Article cards (link to other posts)
#

{{< article link="/posts/some-other-post/" >}}

List of posts as cards
#

{{< list cardView=true limit=3 where="Type" value="posts" >}}

Embeds
#

GitHub repo card:

GitHub Repository Thumbnail
gohugoio/hugo

The world’s fastest framework for building websites.

Go
87899
8251

Gist:

YouTube (lite, lazy-loaded):

Email obfuscation
#

Direction
#

English content.

Color swatches
#

Typewriter effect
#

Asset-dependent shortcodes (source only)
#

These need real files in the post’s bundle (next to index.md) so the source is shown in code blocks rather than rendered. Drop in the asset, then uncomment to use.

Image (page resource):

![alt text](feature.png "optional title")

Figure with caption:

{{< figure
    src="feature.png"
    alt="Caption-bearing image"
    caption="Figures get a caption row underneath."
>}}

Gallery:

{{< gallery >}}
{{< galleryItem src="img1.jpg" caption="One" >}}
{{< galleryItem src="img2.jpg" caption="Two" >}}
{{< /gallery >}}

Carousel (glob of images in the bundle):

{{< carousel images="gallery/*" >}}

Native video:

{{< video src="demo.mp4" autoplay="true" muted="true" >}}

Screenshot frame:

{{< screenshot src="ui.png" >}}

Code import from a remote file:

{{< codeimporter url="https://raw.githubusercontent.com/example/repo/main/file.py" type="python" >}}

Markdown import (compose from fragments):

{{< mdimporter url="fragment.md" >}}

Hugo built-ins
#

Ref / relref — link by file path, survives renames
#

[See another post]({{< ref "/posts/some-other-post" >}})

Page resources
#

When images, PDFs, or data files live in the post’s bundle directory (next to index.md), reference them by relative name (feature.png), not by URL. Hugo will hash, optimize, and emit them automatically.

Series
#

Add to front matter:

series: ["My Series Name"]
series_order: 1

Blowfish renders prev/next navigation and a series index page.

Drafts and futures
#

hugo ignores draft: true and future-dated content by default. Preview with hugo server -D -F.

Build commands
#

hugo server -D            # local preview, includes drafts
hugo server -D -F         # also future-dated posts
hugo --gc --minify        # production build into ./public
hugo new posts/foo/index.md

When in doubt, the Blowfish docs are canonical.2

  1. Footnotes drop to the bottom of the page automatically. ↩︎

  2. This file lives at content/en/posts/blowfish-reference/index.md. ↩︎