This article documents a working setup to develop a Hugo site on a Raspberry Pi and edit it from a laptop using VS Code Remote‑SSH. It covers:

• Running Hugo (Docker or native) on the Pi with remote access
• Editing with VS Code (Remote‑SSH)
• Where to put new posts
• Adding Giscus (GitHub Discussions) for comments, with a small “refresh comments” helper
• Pushing changes back to GitHub with SSH keys

You can reproduce this end‑to‑end on your own Pi.

Prerequisites

• Raspberry Pi 4 (or similar) running Linux
• SSH access to the Pi from your laptop
• Hugo site checked out on the Pi (hugo.toml at the repo root)
• Git installed on the Pi & a GitHub account

1. Development server on the Pi Create a small script on the Pi (project root) to run Hugo in Docker (recommended for identical builds) and listen on all interfaces so your laptop can access it:

dev-remote.sh #!/bin/bash

dev-remote.sh — Hugo development server for remote access

set -e

LOCAL_IP=$(hostname -I | awk ‘{print $1}’) echo “Starting Hugo server on http://${LOCAL_IP}:1313 — press Ctrl+C to stop”

docker run –rm -it
-v “$(pwd)”:/src
-p 1313:1313
hugomods/hugo:dart-sass
server -s /src
–bind 0.0.0.0
–baseURL “http://${LOCAL_IP}:1313/”
–buildDrafts
–disableFastRender
–poll 1s

Notes:

• –bind 0.0.0.0 is critical so the server is reachable from other machines on the LAN.
• –poll 1s helps file change detection when editing over network shares or remote connections.

Make it executable: chmod +x dev-remote.sh ./dev-remote.sh

Open your laptop browser to http://:1313 to preview.

2. Editing from your laptop with VS Code

• Install the Remote‑SSH extension in VS Code.
• Use Remote‑SSH → Connect to Host → user@pi-ip.
• Open the Hugo project folder on the Pi from that remote window.
• Terminal inside VS Code now runs on the Pi — use it to run ./dev-remote.sh.

This gives a seamless edit → save → rebuild → preview loop.

3. Where to put content (posts) Two common models:

A) Keep everything under content/post with subfolders: content/post/cycling/ content/post/motorcycles/ content/post/sql/

URLs: /post/cycling/your-slug/

B) Use top-level sections (recommended for clearer URLs): content/cycling/ content/motorcycles/ content/sql/

URLs: /cycling/your-slug/

If your theme only shows a specific section on the homepage, use mainSections in hugo.toml: [params] mainSections = [“post”,“motorcycles”,“sql”,“rpi”,“cycling”]

4. Adding Giscus (GitHub Discussions) comments — overview Giscus is free and uses GitHub Discussions as the backing store. Steps:

• Make the repo public (simplest path).
• Enable Discussions: repo → Settings → Features → enable Discussions.
• Install the Giscus GitHub App on that repository (from https://github.com/apps/giscus or via giscus.app).
• Use the generator at https://giscus.app to get the embed snippet or the data-* values.

5. Add a comments partial to your site Create a partial file on the Pi at layouts/partials/comments.html. Here is a safe partial that includes a small “Refresh comments” helper (useful because the first comment sometimes requires the embed to be reloaded):

Replace the placeholder values with the values from the giscus.app generator (repo, repo-id, category, category-id, theme, etc.).

layouts/partials/comments.html {{ if not .Params.disableComments }}

{{ end }}

6. Include the partial on single pages If your theme does not already call a comments partial, add it to your single templates. The easiest method is to copy the theme single.html into your site and insert the partial after the content:

• Create target dir and copy (if the theme has it): mkdir -p layouts/_default cp -v themes//layouts/_default/single.html layouts/_default/single.html

• In layouts/_default/single.html, find the {{ .Content }} line and immediately after it add: {{ partial “comments.html” . }}

If your theme uses baseof.html and block templates, create a single template that defines the “main” block and includes the partial. Test visually and revert if layout needs polishing.

7. Per-post control To disable comments per post:

---

title: “Internal notes” disableComments: true

8. SSH keys & GitHub push (quick) To push your changes from the Pi to GitHub via SSH:

• Generate key on Pi (if not already): ssh-keygen -t ed25519 -C “your-email@example.com”

accept defaults, optionally add passphrase

• Copy the public key content (~/.ssh/id_ed25519.pub) and add it to GitHub: Settings → SSH and GPG keys → New SSH key.
• Start ssh-agent and add the key: eval “$(ssh-agent -s)” ssh-add ~/.ssh/id_ed25519
• Verify: ssh -T git@github.com
• Add remote (if not set) and push: git remote add origin git@github.com:OWNER/REPO.git git push -u origin main # or master depending on your branch

9. Testing & troubleshooting

• Giscus may need an embed reload the first time a discussion is created; the Refresh helper solves this without reloading the whole page.
• Disable adblockers when testing — some block comment widgets.
• If the widget fails to load on the public site, check CSP and firewall rules and allow giscus.app and GitHub domains (avatars come from avatars.githubusercontent.com).
• If Hugo doesn’t rebuild on remote edits, ensure you use –poll with the server or edit locally on the Pi via Remote‑SSH.

10. Optional: keep config in hugo.toml Instead of hardcoding values in the partial, you can add a params.giscus section to hugo.toml and read .Site.Params.giscus values in the partial for easier editing.

Example: [params.giscus] repo = “OWNER/REPO” repo_id = “REPO_ID” category = “CATEGORY_NAME” category_id = “CATEGORY_ID” mapping = “pathname” theme = “dark” lang = “en”

Wrap up This setup provides a comfortable remote development workflow:

• Edit files in VS Code while they live on the Pi
• Hugo runs on the Pi and serves the preview at http://pi-ip:1313
• Comments are served by GitHub Discussions via Giscus, free and moderation‑friendly

Happy publishing!