Blog Static Site Generator

---

Overview

• Static Site Generator: Hugo + TypeScript + MD
• Linting: ESLint + StyleLint +
• Hosting: Cloudflare Pages

Usage

• Minimum Requirements
• Installation
• Development
  • Development Server
  • Linting
• Writing Blog Posts

Minimum Requirements

• Node 18

If you need help installing and/or managing Node and Yarn versions, check out NVM.

Installation

npm install

• npm install installs the necessary node modules for development.

bin/install-precious <path/to/install>

• bash bin/install-precious installs precious which is used for linting code.
• To install it directly within the repository you can run mkdir -p local to create a local folder. Then run bin/install-precious local to install precious.

You should also install our pre-commit hook. You can do this from your checkout by running git/setup.sh. These hooks do things like ensure that the code you commit is tidy and passes various linter checks.

Install Hugo

Homebrew (macOS)

brew install hugo

Debian / Ubuntu

It is recommended that you install the latest release of Hugo. For debian and ubuntu users, they offer a .deb file.

Other OS

See Hugo Installation

Install Embedded Dart Sass

Download Embedded Dart Sass and make sure it is in your $PATH. This is necessary for Hugo to process SASS and SCSS files. See the Hugo documentation for more information.

Development

Development Server

The development server watches files, rebuilds the site, and reloads the browser when files change.

hugo server

Linting

npm run lint

Cloudflare Pages HTTP Headers Configuration

The static/_headers file is automatically generated from bin/_headers.config.ts. Do not edit static/_headers directly.

Making Changes to Headers

1. Edit bin/_headers.config.ts (the source of truth with readable format and TypeScript type safety)
2. Test your changes locally:

   npm run build:headers

3. Commit only bin/_headers.config.ts - the headers file is regenerated during deployment

Build-Time Generation

The static/_headers file is generated during the build process via build.sh and is not committed to git. For local testing, you can manually generate it with npm run build:headers.

Writing Blog Posts

Blog posts are written using markdown, with each post corresponding to a markdown file in the /content directory, with subdirectories for the year and month of publication (e.g., /content/YYYY/MM).

You can learn more about how blog post files work and how they are formatted in the BLOG-POST-TEMPLATE.md file.

Categories and Tags

To see a full list of categories and tags, check out the all taxonomies page. This page is automatically updated on build and push to production. If you want to see it on your local machine, start up the development server and go to /all-taxonomies.