A community-driven resource for amateur radio enthusiasts

How It Works

Understanding how the site works helps you contribute effectively and troubleshoot issues. This page explains the technology, deployment process, and implications of being a public repository.

Technology overview

This site is built with Astro, a modern static site generator. "Static" means the site is pre-built at deploy time—there's no server running PHP or Node.js. The result is a collection of HTML, CSS, and JavaScript files that any web server can serve.

Astro

Builds the site from Markdown content and Astro components. Handles routing, content collections, and page generation.

GitHub

Hosts the source code, manages collaboration through pull requests, and runs the build process.

GitHub Pages

Serves the built static files to visitors. Free, fast, and automatically handles SSL certificates.

The build process

When you push changes to the main branch:

  1. GitHub Actions starts — A workflow is triggered automatically
  2. Dependencies install — npm install downloads required packages
  3. Astro builds — npm run build generates static files to dist/
  4. Files deploy — The dist/ folder is pushed to GitHub Pages
  5. Site updates — Changes appear at https://microhams.com/ within minutes

The entire process typically takes 2-3 minutes.

Public repository

This is a public repository. That has specific implications:

What "public" means

  • Anyone can view the source — All code, content, and history is visible to the world
  • Anyone can fork — Others can copy the repository (but can't push to ours)
  • Search engines index it — Content appears in GitHub search and Google
  • Draft content is visible — Even unpublished work in progress can be seen
  • Commit history is permanent — Deleted content remains in git history

What this means for contributors

Don't commit secrets

Never commit passwords, API keys, personal phone numbers, or home addresses. Once pushed, they're in git history forever.

Drafts are visible

Work-in-progress content is visible even before it's "published." Don't put embarrassing notes in your drafts.

Write for the public

Anything you write could be read by anyone. Keep it professional and assume the world is watching.

What makes content live

Content appears on the live site when:

  1. It's merged to the main branch
  2. It passes the build process (valid frontmatter, no errors)
  3. For events: the event date is in the future or recent past

There's no separate "publish" button—merging to main is publishing.

When things break

Sometimes deployments fail. Here's how to diagnose and fix common issues.

Build failures

If the build fails, the previous version of the site stays live. Common causes:

Symptom Likely cause Fix
"Invalid frontmatter" YAML syntax error or missing required field Check your frontmatter against the Schema Reference
"Cannot find module" Missing import or typo in file path Check import statements, verify file exists
"Type error" TypeScript type mismatch Run npm run type-check locally
ESLint errors Code style violations Run npm run lint:fix

Checking build status

To see if a build succeeded or failed:

  1. Go to the Actions tab on GitHub
  2. Find the most recent workflow run
  3. Green check = success, red X = failure
  4. Click into a failed run to see the error log

Validating locally

Before pushing, run the same checks that CI runs:

# Full CI pipeline (lint, type-check, tests, build)
npm run ci

# Quick validation
npm run lint && npm run type-check

# Just the build
npm run build

If it passes locally, it should pass on GitHub.

Development workflow

Local development

# Start dev server with hot reload
npm run dev

# Preview production build
npm run build && npm run preview

The dev server runs at http://localhost:4321 and updates instantly when you save changes.

Testing

# Unit tests
npm test

# E2E tests
npm run test:e2e

# All tests
npm run test:all

Pre-push validation

A git hook runs validation before you push. If it fails, fix the issues before pushing:

# Auto-fix what can be fixed
npm run pre-push:fix

Who gets notified

When builds fail, GitHub sends notifications to:

  • The person who pushed the commit
  • Anyone who configured GitHub notifications for the repository
  • Repository admins (if configured)

To configure your notifications: GitHub → Settings → Notifications → Actions

Getting help

If you're stuck:

  1. Check the Actions tab for error messages
  2. Read the error carefully—it usually says exactly what's wrong
  3. Search the error message online
  4. Ask in the club's communication channels
  5. Open an issue on GitHub describing the problem