Adding Documentation

The docs collection is for technical documentation, reference guides, and how-tos that don't age like articles. These live in src/content/docs/.

Docs vs Articles

Create Documentation

Documentation lives in folders to keep content and assets together. Create a folder with an index.md file:

src/content/docs/my-topic/
└── index.md

The folder name becomes the URL slug (e.g., /docs/my-topic).

---
title: "Antenna Theory Basics"
description: "Fundamental concepts for understanding antennas"
order: 1
category: "antennas"
---

Your documentation content here...

Fields

Organization

Folder Structure

Each doc lives in its own folder. Add images and other assets alongside the index.md:

src/content/docs/aprs-gateway/
├── index.md
├── diagram.png
└── config-example.txt

Use Categories

Group related documentation with the category field:

# antennas/antenna-theory.md
category: "antennas"
order: 1

# antennas/dipole-design.md  
category: "antennas"
order: 2

# digital/aprs-setup.md
category: "digital"
order: 1

Use Order for Sequencing

The order field controls sort order within a category. Use it for documentation that should be read in sequence:

1. order: 1 — Prerequisites
2. order: 2 — Basic setup
3. order: 3 — Advanced configuration

Writing Tips

• Be evergreen: Write docs that won't need constant updates. Avoid specific software versions unless necessary.
• Link liberally: Reference other docs and articles. Internal links use markdown: [text](/docs/other-doc)
• Include examples: Show real commands, configurations, and expected outputs.
• Use headings: Break content into scannable sections. H2 for main sections, H3 for subsections.

Complete Example

Here's a complete documentation page for a Raspberry Pi APRS gateway guide, annotated to explain each field:

---
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# REQUIRED: Title
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
title: "Raspberry Pi APRS Gateway"
# Descriptive title that tells users exactly what this doc covers.
# Keep it specific—"APRS Gateway" is too vague.

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# RECOMMENDED: Description for SEO and listings
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
description: >-
  Build an IGate or digipeater with a Raspberry Pi
  and Direwolf—from hardware selection to configuration.
# Multi-line string using >- for readability.
# Appears in search results and social shares.

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# OPTIONAL: Organization fields
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
category: "digital"
# Groups related docs together. Use lowercase, single word.
# Common categories: antennas, digital, operating, equipment

order: 1
# Sort order within the category. Lower numbers appear first.
# Use for sequential documentation (1 = read first).

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# OPTIONAL: Discoverability
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
tags:
  - aprs
  - raspberry-pi
  - direwolf
  - digital
# Keywords for search and filtering. Use lowercase with hyphens.

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# OPTIONAL: Publishing control
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
draft: false
# Set true while writing. Draft docs are hidden in production.
# Remove or set false when ready to publish.
---

Build a reliable APRS gateway using a Raspberry Pi. This guide covers
both IGate (internet gateway) and digipeater configurations.

## Prerequisites

Before starting, ensure you have:

- Raspberry Pi 3B+ or newer (Pi 4 recommended)
- 32GB+ microSD card
- 2m radio with data port (Baofeng with APRS cable works)
- USB sound card or dedicated TNC

## Hardware Setup

![Wiring diagram for Pi APRS gateway](./wiring-diagram.png)

Connect your radio's data port to the USB sound card:

| Radio Pin | Sound Card |
|-----------|------------|
| Audio Out | Line In    |
| Audio In  | Line Out   |
| PTT       | GPIO 17    |
| Ground    | Ground     |

## Installing Direwolf

```bash
sudo apt update
sudo apt install direwolf
```

See the [Direwolf documentation](https://github.com/wb2osz/direwolf)
for version-specific notes.

## Configuration

Create `/etc/direwolf.conf`:

```
MYCALL N0CALL-10
MODEM 1200
IGSERVER noam.aprs2.net
IGLOGIN N0CALL 12345
```

Replace `N0CALL` with your callsign and `12345` with your
[APRS-IS passcode](https://apps.magicbug.co.uk/passcode/).

## Troubleshooting

Common issues and solutions:

- **No packets decoded**: Check audio levels with `alsamixer`
- **PTT not keying**: Verify GPIO permissions and wiring
- **Not reaching APRS-IS**: Check internet and firewall settings

## Related Documentation

- [APRS Fundamentals](/docs/aprs-basics) — protocol overview
- [Audio Interface Guide](/docs/audio-interfaces) — sound card setup

Folder Structure

This doc lives in its own folder with co-located assets:

src/content/docs/raspberry-pi-aprs-gateway/
├── index.md              # The documentation above
└── wiring-diagram.png    # Referenced as ./wiring-diagram.png

Current Documentation

Existing docs for reference: