Chris Achinga's Blog

Personal site and blog built with Hugo (extended) using the PaperMod theme.

Quick Start

• Prerequisite: Install Hugo Extended v0.147+ (hugo version should show/contain extended).
• Run locally (includes drafts):
  • hugo server -D
  • Visit http://localhost:1313
• Build production output: hugo --minify (outputs to public/).

Deployment

• Automatic deploys to GitHub Pages on every push to main via .github/workflows/hugo.yaml.
• Custom domain is configured via CNAME and baseURL in hugo.yaml.
• To trigger a manual deploy, use the “Run workflow” button in GitHub Actions for “Deploy Hugo site to Pages”.

Project Structure

• hugo.yaml: Site configuration and PaperMod params (menus, theme settings, etc.).
• content/posts/: Markdown articles (the main content section).
• archetypes/default.md: Default front matter used by hugo new.
• layouts/shortcodes/articleCount.html: Shortcode used on the homepage to display total article count.
• assets/: SCSS and media for asset pipeline; consider Page Bundles for post-local images (see below).
• static/: Files here are served as-is at site root (e.g., place global /images/... here if not using bundles).

Adding Articles

Use Hugo’s generator to start a post with the default archetype:

hugo new posts/my-new-article.md

This creates a draft file with minimal front matter. Common front matter fields for this site and PaperMod:

---
author: ["Chris Achinga"]
title: "My New Article"
date: "2025-01-01"
description: "One-line summary for previews and SEO"
tags: ["tag1", "tag2"]
ShowToc: true      # shows Table of Contents on the right
TocOpen: true      # opens the ToC by default (optional)
draft: true        # publish by setting to false
# Optional social/cover settings used by PaperMod
images: ["/images/og/my-cover.png"]    # used for OpenGraph/Twitter cards
cover:
  image: "/images/headers/my-cover.png"
  alt: "Descriptive alt text"
  caption: "Photo credit or context"
---

When ready to publish, set draft: false and commit to main.

Drafts

• hugo server -D includes drafts in local preview.
• There is also a .drafts/ folder in this repo for scratch notes. Files in .drafts/ are not part of the site; move finalized content into content/posts/.

Images and Media

Recommended: use a Page Bundle so images live with the post.

1. Create a bundled post:

hugo new posts/my-post/index.md

2. Put images alongside index.md, then reference them relatively in Markdown:

content/posts/my-post/
├── index.md
└── screenshot.png

Markdown usage inside index.md:

![Alt text](./screenshot.png)

Alternatively, if you prefer global paths, place assets under static/images/... and reference them as /images/... in Markdown and front matter. The assets/images/... folder is available for pipeline processing; for simple embeds prefer Page Bundles or static/images.

PaperMod Syntax Cheatsheet

PaperMod supports standard Markdown plus helpful options and shortcodes. Highlights used in this project:

• Front matter ToC: set ShowToc: true (and optionally TocOpen: true).

• Code blocks with line numbers and highlights:

  ```js {linenos=true,hl_lines=[2,5]}
  const a = 1
  const b = 2
  console.log(a + b)
  

• Copy buttons for code: enabled globally via params.ShowCodeCopyButtons: true.

• Figure shortcode (PaperMod-enhanced):

  {{< figure src="/images/example.png" alt="Example" caption="A helpful caption" align=center >}}

• Details/collapsible sections (HTML):

  <details>
    <summary>Click to expand</summary>
    Hidden details content here.
  </details>

• Emoji: enabled; use shortcodes like :sparkles: or native emoji.

More examples live in content/posts/formatting-posts-on-hugo.md.

Menus, Taxonomies, Search

• Menus: edit languages.en.menu.main in hugo.yaml.
• Taxonomies: tags, categories, series are enabled. Add in front matter.
• Search: JSON index is enabled via outputs.home in hugo.yaml; PaperMod search page is at /search/.

Useful Commands

• Start dev server with drafts: hugo server -D
• Start dev server (published only): hugo server
• Clean and rebuild production: hugo --gc --minify
• Show Hugo version: hugo version

Notes

• The GitHub Actions workflow pins Hugo to v0.147.2. For consistency, use a local version close to that.
• The homepage shows total article count using the articleCount shortcode in layouts/shortcodes/articleCount.html.