Editing this Handbook

Anyone in the troop can improve this handbook, and we’d like you to. This page explains what belongs here, how the site is put together, and how to make a change.

It’s written for two audiences: people editing a page, and AI coding agents working in the repository. Both are held to the same standard. If you’re an agent, read the whole page before making changes, and follow the checklist at the end.

Scope and Style

These rules decide what goes on the site. When a change conflicts with them, the change is wrong.

• This site is not a policy document, a set of troop bylaws, or a list of rules and regulations. It’s a reference guide — a “user’s manual” — used for training and for the continuity of knowledge.
• It does not replace resources like the Scout Handbook or the Troop Leader Guidebook by re-teaching skills or information those already cover adequately.
• It does not duplicate primary sources on requirements, policies, and the like. It gives a minimal summary of the key, unchanging information that everyone needs to know.
• It links to official and external resources frequently and preferentially, instead of restating their content.
• Everything here is either a basic summary of Scouting and its structure, or information specific to Troop 1607. Nothing else.
• Writing is clear, concise, and expository.
• It is kept lean and non-exhaustive in all circumstances, in the interest of maintainability, organization, and consumability.

That last point is the one most often broken. A page that answers the question in four sentences is better than a page that answers it in four paragraphs. Prefer cutting to adding.

For why a troop is better served by a reference guide than by a policy manual, read:

Troop Policy Manuals

The Handbook Sections

The Basics, Program, and Advancement together form the handbook proper. Their scope is an introductory explanation of how being a member of Troop 1607 works.

• Write in a voice that speaks directly to the scout. “You” always refers to the scout, unless stated otherwise.
• Keep it short and beginner-friendly. Assume some readers are brand new to Scouting and to the troop.
• Assume the reader will go cover-to-cover the first time, but will also skip around and reference individual pages later.
• Avoid jargon and acronyms. When one is unavoidable, spell it out on first use.
• Leave advanced and in-depth topics to the Appendix.

The Appendix

The Appendix holds the material that isn’t required reading for everyone: position manuals, playbooks for recurring troop jobs, and reference links. Pages here can be longer and more detailed, and can address adults and officeholders rather than a new scout. They still follow the scope rules above.

How to Edit

Content is written in Markdown — plain text files with a handful of formatting features such as headings, links, bold and italics, and images. If you’ve never used it, read Authoring Content in Markdown; it covers everything this site uses.

There are two ways in:

In the browser. Every page has an Edit page link at the bottom. It opens that page’s source on GitHub, where you can make your change and propose it. You need a free GitHub account and nothing else. This is the right path for fixing a typo, correcting a fact, or adding a paragraph.

Locally. Clone the repo if you’re adding pages, moving things around, or touching the site itself. The project uses pnpm; other package managers are blocked.

git clone https://github.com/kevin8181/1607docs.git
cd 1607docs
pnpm install
pnpm dev        # live-reloading preview at http://localhost:4321

Small changes can go straight to main. Anything larger, or anything from outside the troop, should come as a pull request. CI has to pass either way.

How the Site Is Organized

Pages live in src/content/docs, and the URL of a page is its path under that directory: src/content/docs/basics/money.md is served at /basics/money.

src/content/docs/
├── index.md              home page
├── basics/               The Basics — start here for new members
├── program/              how the troop's program runs
├── advancement/          ranks, merit badges, advancement
└── appendix/
    ├── youth-positions/  position manuals for scouts
    ├── adult-positions/  position manuals for adult volunteers
    ├── eagle/            Eagle Scout material
    └── playbooks/        how-to guides for recurring troop jobs

The sidebar is generated from the file tree — there is no sidebar list to update. Each directory has a _meta.yaml that names it and places it:

label: The Basics
order: 1
collapsed: true # optional; start the group collapsed

Within a group, pages are ordered by sidebar.order in their frontmatter. Leave gaps between numbers so a page can be inserted later without renumbering the whole group.

Everything outside src/content is the site itself — Astro and Starlight configuration in astro.config.ts, components in src/components, the content schema in src/content.config.ts. Content contributors never need to touch these.

Page Conventions

Follow the conventions already in the files. If a rule here disagrees with what most existing pages do, the existing pages win — and say something, so this page can be fixed.

Frontmatter. Every page opens with a YAML block. title is required, and it becomes the page’s <h1>; nothing else should be.

---
title: Expenses and Payment
sidebar:
  order: 5
---

Headings. The body starts at ##, because title already supplied the <h1>. Don’t skip levels.

Internal links are root-relative, with no file extension and no trailing slash: [Troop Structure](/basics/structure). The build fails on a broken internal link, so a typo here is caught, not shipped.

External links usually stand alone on their own line, as a labelled link rather than a bare URL:

[Merit Badges A-Z](https://www.scouting.org/skills/merit-badges/all/)

Asides call out something the reader shouldn’t miss. Use them sparingly; a page of asides is a page with no emphasis at all.

:::tip
If you're 18 or older, you can become a merit badge counselor!
:::

:::caution[Under construction!]
Some pages may be missing or incomplete.
:::

note, tip, and caution are the ones this site uses. The text in brackets is an optional custom title.

Images go in src/assets and are referenced by relative path, so the build can optimize them: ![Scout Uniform Class A](../../../assets/sbsauniform.jpg). Always write alt text.

Unfinished pages are marked with a bare todo line or an inline <!-- todo -->, and an outline of what the page should cover. A stub that says what’s missing is more useful than a page that quietly omits it.

Formatting is handled by Prettier — tabs, and its own line wrapping. Run pnpm format before committing rather than matching it by hand.

Position Pages

Pages under youth-positions/ and adult-positions/ are structured data, not free prose. Their frontmatter is validated against a schema in src/content.config.ts, and the fields are rendered into the “Position Facts” panel at the top of the page by a component. The panel already adds “Live by the Scout Oath and Law” and “Set a good example…” to every position, so don’t repeat them.

---
title: Chaplain Aide
type: position
level: youth # youth | adult
selection: Appointed by the Senior Patrol Leader, with approval of the Scoutmaster
reportsTo: Assistant Senior Patrol Leader
summary: |
  One or more paragraphs introducing the position. Blank lines separate
  paragraphs; the first one is also used as the blurb on the positions index.
responsibilities:
  - One responsibility per item, phrased as an action
  - At least one is required
attendance: 80% of all Courts of Honor, and 30% of all other troop meetings and outings
sidebar:
  order: 1 # for youth positions, stands in for seniority
---

Everything above renders automatically. Do not restate the summary, responsibilities, selection method, or attendance requirement in the body — the body is for the how-to material that makes the page a usable manual: what the job actually involves week to week, how to plan the things it’s responsible for, and where to go for more. chaplain-aide.md is the model to follow.

The lists of responsibilities come from Scouting America’s standard position descriptions; keep them recognizable rather than rewriting them from scratch, and add troop-specific duties as additional items.

Adding a position page is all that’s needed to list it — the index on /program/youth-positions picks it up from the collection.

Before You Commit

Run the checks. CI runs the same three on every push, and a failure blocks the change.

pnpm format        # rewrites files with Prettier
pnpm astro check   # types and content schema
pnpm knip          # unused files, exports, and dependencies
pnpm build         # also validates every internal link

pnpm check runs the first three together.

Then confirm the following:

• The change fits the scope rules — troop-specific or basic Scouting, summarized rather than duplicated, linked rather than restated.
• It’s in the right section, in the right voice for that section, and reachable from the sidebar.
• Facts are real. Names, dollar amounts, dates, and requirements are either verified against a primary source or left as todo. Never invent a troop detail to fill a gap — that’s worse than a blank page, because a reader can’t tell the difference. If you’re an agent and you don’t know, say so in the pull request and mark the spot.
• External links resolve, and point at the official source rather than a copy of it.
• Nothing unrelated changed. Keep the diff to the thing you set out to do.
• Content is factual for the troop as it is today, not as someone hopes it will be. Anything that reads like a rule or a policy belongs somewhere else.