OpenStreetMap Utah

Source for the OpenStreetMap Utah community website, built with Hugo and deployed as static files over SSH.

Initial setup

Install mise, then install the pinned Hugo Extended, Dart Sass, Just, and rumdl versions:

mise install

Run the local development server:

just dev

Build the static site:

just build

Format Markdown files:

just fmt

The build output is written to public/.

Deployment over SSH

Deployment is intentionally simple: build the site, then sync public/ to the web server with rsync over SSH.

Pass the destination directory on the server as the target argument:

just deploy user@server:/opt/osmutah/www/

The deploy recipe runs:

hugo --gc --minify
rsync -az --delete public/ "user@server:/opt/osmutah/www/"

--delete makes the server match the local Hugo build exactly. Use a destination directory dedicated to this site.

Before deploying, make sure:

• SSH access to the server works.
• The target directory exists and is writable by the SSH user.
• The web server serves that directory for the production domain.
• TLS and redirects are handled by the server or its reverse proxy.

For a Caddy-based server, see Caddyfile.example. It serves /opt/osmutah/www for osmutah.org and redirects www.osmutah.org to the apex domain.

Giving another maintainer deploy access

A maintainer needs only SSH access to the deployment target.

1. Add their public SSH key to the deploy user on the server.

2. Confirm they can connect:

   ssh user@server
   

3. Confirm they can write to the site directory:

   ssh user@server 'test -w /opt/osmutah/www'
   

4. They can deploy with:

   just deploy user@server:/opt/osmutah/www/
   

Do not give contributors direct server access unless they are trusted to deploy production changes. Blog contributors can submit changes through the repository instead.

Updating the next Map Night

The most common site update is changing the next Map Night date in content/our-map-nights.md.

To update it to the next upcoming second Tuesday, build-check it, commit the change, and push:

just update-map-night

Example Map Night update commit: 92c3999eb8d799ee75f562bb5acf3ffc34c5ce71.

Publishing a new blog post

Blog posts are Hugo leaf bundles: one directory containing index.md and any images used by that post.

1. Create the post directory

Use a stable, lowercase, hyphen-separated slug:

mkdir -p content/blog/my-new-post

Create content/blog/my-new-post/index.md:

---
title: "My New Post"
date: 2026年06月03日 12:00:00
author: "your-name"
slug: "my-new-post"
categories:
 - "news"
tags:
 - "openstreetmap"
summary: "One sentence summary for cards and feeds."
image: "cover-image.png"
---
Post body goes here.
![](inline-image.png)

image: is optional. If present, it is used by list cards and the post header.

2. Add images next to the post

Put post images in the same directory as index.md:

content/blog/my-new-post/
 index.md
 cover-image.png
 inline-image.png

Reference images by filename in Markdown:

![](inline-image.png)

Reference the card/header image by filename in front matter:

image:"cover-image.png"

Hugo copies these images into the generated public/ output during the build.

3. Build and check locally

Run:

just build

Format Markdown files before submitting:

just fmt

Then preview locally if desired:

just dev

Open the post and confirm:

• the title/date/author are correct;
• the summary looks good on list pages;
• all images load;
• links point to the intended targets.

4. Submit or deploy

Blog contributors should commit the post directory and open a pull request or patch through the repository workflow.

Maintainers can deploy after review:

just deploy user@server:/opt/osmutah/www/

Site structure

• content/ — pages and blog posts.
• content/blog/<slug>/index.md — blog post content.
• content/blog/<slug>/*.{jpg,jpeg,png,gif,svg,webp} — images for that post.
• layouts/ — Hugo templates and partials.
• assets/scss/ — site styles.
• static/ — files copied directly into the published site, including shared images and map assets.

What not to commit

Do not commit generated local output:

• public/
• resources/_gen/
• .hugo_build.lock

Images that are part of posts or shared site design should be committed with the content they support.

License

Original written content in this repository is licensed under the Creative Commons Attribution 4.0 International license. See LICENSE.

Third-party code, map data, imagery, logos, generated map assets, and dependency-provided files remain under their respective licenses. OpenStreetMap data is © OpenStreetMap contributors and is available under the Open Database License.