Skip to content

Photo Publishing

How to add photos to the film gallery and publish them. Everyday publishing needs only Windows Explorer and one desktop shortcut.

Publishing photos

All paths are under \\wsl.localhost\Ubuntu\home\dnewling\photos\. The Photo Albums desktop shortcut opens content\.

  1. New roll: copy the lab's folder into scans\. Treat it as a permanent archive: never edit, rename or delete anything there.
  2. Pick photos: copy your picks from scans\ into content\<album name>\. Create a new folder for a new album; the folder name becomes its title.
  3. Publish: double-click Publish Photos on the desktop.
  4. Check the preview that opens in your browser at http://localhost:1313/. It only works while the window is asking the question below.
  5. Type yes in the window to publish publicly. Anything else stops without publishing, and your files stay in place.

Setting the order

Each album has an order.txt listing its filenames in display order, one per line. It's created on the first run, starting in filename order.

  • Reorder: move lines in Notepad, then run Publish Photos again. The preview doesn't pick up order.txt until the next run.
  • Add photos: drop them in the album. New photos go to the end of the list.
  • Remove photos: delete the file. Its line is removed for you.
  • Cover: the top line, unless a filename contains feature.

Filenames never need to change to reorder, so share links stay stable. Choose a good name before a photo is first published. If you rename a photo later, its link breaks and it moves to the end of the list.

What the shortcut does

For photos that are new to git only, so published links stay stable:

  • Makes filenames URL-safe, e.g. 6056-0016~2.jpg becomes 6056-0016-2.jpg.
  • Converts TIFF and PNG to JPEG at quality 95, because Hugo keeps the source format and browsers can't display TIFF.
  • Converts non-sRGB images to sRGB, which fixes the darkened B&W problem.

It also removes Zone.Identifier files, creates index.md for new albums, applies each order.txt, and builds the site. After you type yes, it commits, pushes to Forgejo (which mirrors to GitHub), and deploys to Cloudflare.

Common tasks

Task How
Choose photos faster Run scripts/contact-sheets.sh from WSL for per-roll sheets in contact-sheets\. Explorer thumbnails also work
Choose an album cover Move it to the top of order.txt
Fix a sideways photo Rotate the copy in content\, or run scripts/rotate.sh 90 <file> from WSL. Rotating in Windows hasn't been tested, so check the preview
Remove a photo Delete it from content\ and publish. It stays in scans\ and in git history
Remove an album Delete its folder from content\ and publish
Rename an album Rename the folder and edit title in its index.md. Its URL changes, which breaks shared links
Change the site name Edit title in hugo.toml (tab title, share cards, top-left button) and content\_index.md (home page heading), then publish. Commit the hugo.toml change from WSL; the shortcut only saves content\ and scans\
Add album text Add description: Some text to index.md
Hide an album from the home page Add params: with private: true to index.md, and remove menus: main. It's still public to anyone with the link
Feature an album Add params: with featured: true to index.md for the large home page banner. Also add private: true under params: so it doesn't show a second, normal card; this also drops it from the RSS feed and sitemap. snaps is set up this way
Change the hamburger menu Albums are listed through menus: main in their index.md, added automatically for new albums. Remove that line to leave one out. The home entry and any other links are in hugo.toml

Share links use filenames and album names

A photo's link looks like https://<domain>/<album>/#<filename>.jpg. Renaming either one breaks links you've already sent.

If it stops

Every "STOPPED" message means nothing was published.

Message Fix
unsupported file Use JPEG, PNG or TIFF. The theme warns against WebP
albums can only be one folder deep Move the photos directly into content\<album>\
files are not inside an album folder Move them into an album folder
files in scans/ were changed, renamed or deleted If you renamed a file, change it back to the name shown; git restore alone would leave a duplicate. Otherwise run git restore scans/ from ~/photos. To name a photo, rename its copy in content\
sets its own 'sort_by' (or resources, sort_order) Remove that line from index.md; order.txt controls the order and cover
two photos would share the name Rename one of them
this batch is ... too large A batch can't exceed about 1.8 GiB, because GitHub rejects pushes over 2 GB. Move some new rolls out of scans\, publish, then add them back and publish again
domain mismatch See changing the domain
CLOUDFLARE_API_TOKEN ... missing See first-time setup

If the push succeeds but the Cloudflare step fails, run Publish Photos again. It will report no file changes and retry the deploy once you type yes.

To undo a bad deploy, run npx wrangler rollback from ~/photos with Node 22 on PATH. Cloudflare's docs don't say whether static assets roll back too, so check the live site afterwards. Publishing a fixed version also works.

First-time setup

Do this once.

  1. Create a Cloudflare token: in the dashboard, go to My Profile → API Tokens → Create Token and use the Edit Cloudflare Workers template. Scope it to your account and the newling.cloud zone.
  2. Save the token and account ID, without pasting them into a chat or scrollback:

    nano ~/.config/homelab/credentials.env
    
    CLOUDFLARE_API_TOKEN=<token>
    CLOUDFLARE_ACCOUNT_ID=<account id>
    
  3. Check Access: confirm no Cloudflare Access policy covers the hostname, since the site must be public.

  4. Publish with the shortcut. The first deploy creates the DNS record and certificate.
  5. Check it from cellular or another network, including one per-photo link.

Changing the domain

The site is at snap.newling.cloud. The domain is set in two places in ~/photos, and publish.sh stops if they disagree:

  • baseURL in hugo.toml
  • pattern under routes in wrangler.jsonc

The domain must be an active zone on the same Cloudflare account, and the token must cover that zone. Don't create a CNAME for the hostname: Cloudflare creates the record itself and refuses a hostname that already has one.

After the site is live, changing the domain breaks every shared link unless the old one redirects.

Maintenance

  • Keep Hugo pinned at 0.169.0. The theme uses features Hugo has deprecated (libsass, Image.Exif), so a newer version may break it. Test with scripts/publish.sh --check before upgrading.
  • After updating the theme, recheck the 2400px override in layouts/partials/gallery.html, which is a copy of the theme's file.
  • Requirements: the shortcut needs this PC, with WSL's Ubuntu distro and ~/photos in place. Its source is in scripts/windows/.
  • Checking without publishing: scripts/publish.sh --check prepares files and builds, but never commits or deploys.