Learning Guide

If you used the Build Your Own prompt to set up your site, a lot just happened very quickly. You now have a working website, but you might not understand how or why it works. That’s completely okay. You don’t need to understand everything at once, or ever, honestly. Plenty of people drive cars without knowing how engines work.

But if you’re curious, this guide walks through the technologies your site uses, starting from the basics. Take it at your own pace.

The Web: HTML, CSS, and Browsers

Everything on the web boils down to a few simple ideas. When you visit a website, your browser (Chrome, Firefox, Safari, etc.) downloads files from a server and displays them. The most important file types are:

  • HTML: the structure and content of a page (headings, paragraphs, links, images)
  • CSS: the visual styling (colors, fonts, layout, spacing)

Your Hugo site generates these files for you. You write in Markdown (see below), and Hugo converts it into HTML and CSS that browsers understand.

Learn more:

Markdown: Writing Without Code

You don’t write HTML directly. Instead, you write in Markdown, a simple formatting language. For example:

# This is a heading

This is a paragraph with **bold** and *italic* text.

- This is a list item
- So is this

[This is a link](https://example.com)

Your blog posts and about page are all Markdown files. That’s all you need to edit to update your site’s content.

Learn more:

Hugo: Turning Markdown into a Website

Hugo is a static site generator. It takes your Markdown files and a theme (Weaver, in your case) and produces a folder of HTML and CSS files, a complete website ready to be served.

Key concepts:

  • content/: where your writing lives (posts, pages)
  • hugo.toml: your site’s configuration (title, author info, menus)
  • themes/: the template and styling for your site
  • public/: the generated site (you don’t edit this; Hugo builds it)

To preview your site locally, run hugo server -D and open the URL it gives you in your browser. Changes you make to files will appear immediately.

Learn more:

Git: Tracking Changes

Git is a version control system. It keeps a history of every change you make to your files, so you can always go back to a previous version if something breaks. Think of it like infinite undo for your entire project.

Key commands you’ll use:

  • git add <file>: stage a file to be saved
  • git commit -m "description": save a snapshot with a message
  • git push: send your changes to GitHub

You don’t need to memorize these. Your LLM coding tool handles them for you. But it’s helpful to know what’s happening.

Learn more:

GitHub: Hosting Your Code

GitHub is a platform that stores your git repositories (project folders) online. It also provides GitHub Pages, a free hosting service that serves your site to the world.

When you push changes with git, GitHub receives them, runs a build process (see below), and publishes your updated site automatically.

Learn more:

GitHub Actions: Automatic Deployment

The file at .github/workflows/hugo.yml is a workflow, a set of instructions that GitHub runs automatically every time you push changes. Your workflow:

  1. Installs Hugo
  2. Builds your site from Markdown into HTML
  3. Deploys the result to GitHub Pages

You don’t need to touch this file. It just works in the background. But if you’re curious about what it does, open it up and read the step names. They’re fairly self-explanatory.

Learn more:

Git Submodules: The Theme

The Weaver theme lives in themes/weaver/ as a git submodule, essentially a link to another git repository inside yours. This means you get theme updates without copying files around. It also means the theme’s code stays separate from your content.

You probably won’t need to think about submodules. If something goes wrong with the theme, ask your LLM tool for help.

Learn more:

The Most Important Thing

The resources above are here if you want them, but the best way to learn is to experiment. Change something in a blog post and see what happens. Edit hugo.toml and reload. Break something, then figure out how to fix it (or ask for help fixing it).

You have a safety net: git keeps a history of everything, so you can always get back to a working state. And the site rebuilds automatically, so you’ll see results quickly.

When you get stuck:

  • Ask your LLM coding tool. It can explain what went wrong and fix it.
  • More importantly, ask other people. Online communities like the Hugo Discourse forum, IndieWeb chat, and freeCodeCamp are full of people who remember what it was like to be new and are happy to help.

You don’t need permission to learn this stuff, and you don’t need to learn it all. Start with what’s interesting to you.