Building your Site with Hugo

This website is built using Hugo, using the ananke theme.

Hugo makes a static site straightforward to build, and hugo has great documentation, such as their quick start page.

Creating a Site

Hugo’s cli commands include creating a new hugo site, running the dev server, and building the production assets.

First install it using your favorite package manager, then run:

hugo new site newsite

This will create a hugo project that can be used to add your pages. The next part that they recommend is to install a theme, there’s a variety of themes, but ananke is a good starting point.

Adding a Theme

git subtree add https://github.com/theNewDynamic/gohugo-theme-ananke.git master --prefix themes/ananke --squash

You can also use git submodule, download it and copy it, etc.

Then add to the config file, giving the theme name

echo "theme = 'ananke'" >> hugo.toml

Adding a Page

To add a markdown page, run

hugo new content contact-us/index.md

This will make it available at yourdomain.com/contact-us

You can also create an html page by running

hugo new content contact-us/index.html

The top of the page will have the configuration for the page, such as the title, menu to go into, etc.

---
title: "Contact Us"
date: 2023-09-06T14:35:53-05:00
menu: 'main'
weight: 4
---

Setting ‘main’ to be the menu means it’ll be automatically added to the menu, if that exists in the theme. As well, setting ‘weight’ lets you set the order of the menu.

Then under that, you can define all of your content in markdown syntax, or HTML if you picked that.

If you create a post, then you can add <!--more--> as a break for the summary.

Deploying Hugo to Cloudflare Pages

We use cloudflare & cloudflare pages for deploying static content. Manually deploying consists of the following:

• Remove the public directory if it exists. hugo does not automatically remove it.
• Run the hugo command. This will build your site and put it into the public directory.
• Run the following command to deploy to cloudflare pages, replacing the necessary fields.

  CLOUDFLARE_ACCOUNT_ID=<account_id> npx wrangler pages deploy public --project-name=<project_name>
  

You could also setup CI actions, with github or gitea, to automatically update the pages project whenever you create a release tag. This could look like the following, and what we use to deploy today.

---

name: Release Static Site
on:
  push:
    tags:
      - '*'

jobs:
  hugo_deploy:
    name: Build Hugo & Deploy
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Branch
        uses: actions/checkout@v3
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
      - name: Build Static Site
        run: hugo
        shell: bash
      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: project-name-here
          directory: public
          branch: main

When you tag a release, you’ll see the following and then your site will be deployed. This was done with a self-hosted gitea server.