Site Editing Workflow

This is the repeatable process every contributor follows to make a change — whether it is a new blog post, a copy edit, a layout tweak, or a new project page. The loop is the same every time.

What you need installed

• VS Code with the recommended extensions (accept the prompt when you open the repo)
• Hugo Extended 0.163.3 — winget install Hugo.Hugo.Extended
• Node.js (for Decap CMS local server) — winget install OpenJS.NodeJS
• Git — winget install Git.Git
• GitHub Pull Requests extension — installed automatically from .vscode/extensions.json

Step 1 — Open the repo and start the dev environment

Open c:\Users\psean\Develop\hugo_trial (or your local clone) in VS Code, then press Ctrl+Shift+B.

This runs the default build task, which starts two servers in parallel:

Both run in the VS Code terminal panel. Leave them running for the whole session.

Step 2 — Create a branch for your change

Every change — no matter how small — gets its own branch. This keeps main clean and lets GitHub Actions validate the build before anything goes live.

In VS Code: click the branch name in the bottom-left status bar → Create new branch…

Name it descriptively:

You are now on your branch. Everything you edit here is isolated from main.

Step 3 — Make your change

For content (blog posts, project pages)

Go to http://localhost:1313/admin — this is Decap CMS.

• New post: click the collection (Blog Posts or Projects) → New → fill in the fields → Publish
• Edit existing: click the collection → click the post → edit → Publish

“Publish” in local mode means Decap writes the markdown file to disk. Hugo picks it up immediately and the preview at http://localhost:1313 updates.

For templates, layout, or styles

Edit files directly in VS Code. Hugo watches for changes and reloads the browser automatically. Key files:

• Site-wide config (brand, address, nav menu): hugo.toml
• Page templates: layouts/
• Styles: assets/scss/

Step 4 — Review locally

Open http://localhost:1313 and verify your change looks right. Check:

• The page you changed
• The home page (wave, ribbon, footer)
• The blog list and a post page (confirm nothing broke)

If you uploaded images through Decap CMS, make sure they appear correctly. Images land in static/images/uploads/ and are included in your commit automatically.

Step 5 — Commit

Open the Source Control panel in VS Code (the branch icon in the left sidebar, or Ctrl+Shift+G).

1. You will see a list of changed files. Click + next to each file you want to include (or + next to “Changes” to stage everything).
2. Type a short commit message in the text box at the top. Be specific: “Add project page: site editing workflow” is better than “update”.
3. Click the ✓ Commit checkmark.

Step 6 — Push and open a Pull Request

Push: click the Sync Changes button that appears in the Source Control panel (or the ↑ arrow in the status bar). VS Code pushes your branch to GitHub.

Open a PR: in the GitHub Pull Requests panel (left sidebar), click Create Pull Request. VS Code fills in the title from your commit message. Add a description if helpful, then click Create.

GitHub Actions immediately runs the Validate PR build workflow, which builds the full site with Hugo and Dart Sass. You will see a green ✓ or red ✗ on the PR within about a minute.

Step 7 — Review and merge

A second contributor (or yourself, after a fresh look) reviews the diff on GitHub or in the GitHub Pull Requests panel in VS Code.

When the build check is green and the reviewer is satisfied: click Merge pull request → Confirm merge.

Merging to main automatically triggers the Deploy Hugo site to GitHub Pages workflow. The live site at https://hitsainet.github.io/hitsai.net/ updates within about two minutes.

Step 8 — Clean up and repeat

After merging, switch back to main in VS Code (click the branch name → main) and pull the latest changes (Sync button). Delete your feature branch — VS Code or GitHub will offer this automatically after the merge.

Then go back to Step 2 for the next change.

Quick reference