github-pages

name	github-pages
description	Arrange a project's README and GitHub Pages documentation into a consistent user-first layout: short README that links out, just-the-docs Jekyll site with a user-facing index, one page per user-facing feature (split into child pages when long), and a developer guide with technical sub-pages. TRIGGER when: setting up docs/ for a new project, adding a GitHub Pages site, writing or restructuring a README that will link to GH Pages, adding a new user-facing feature page, or asked to align docs with this project or bga-assistant. DO NOT TRIGGER when: editing unrelated docs outside docs/, working on a project that already has an incompatible docs framework (Docusaurus, MkDocs, VitePress, etc.).
allowed-tools	Read, Edit, Write, Glob, Grep, Bash(git rev-parse:*)

GitHub Pages Documentation Layout

Context

• Repo root: !git rev-parse --show-toplevel 2>/dev/null || pwd

Working directory

All README.md, docs/, docs/index.md, docs/pages/, docs/_config.yml, docs/screenshots/ paths in this skill are relative to Repo root from Context. The cwd may be a subdirectory — prefix every Read/Edit/Write/Grep/Glob with the Repo root value. Bare paths are cwd-relative and will silently miss the actual root.

Use this skill when organizing project-level documentation into a README plus a GitHub Pages Jekyll site running the just-the-docs theme. The goal is a consistent shape across repos: the README sells the project in under a screen, every user-facing capability gets its own sidebar entry, and developers get a single Developer guide that may itself have technical child pages.

Reference implementations:

• jsonl-logs-intellij-plugin — modern just-the-docs reference. Single product with deep splitting (Usage parent + 6 children, Development parent + 2 children).
• chrome-assistant — monorepo variant (one product per subfolder under docs/pages/).
• bga-assistant — earlier flat variant.

Read the target repo's README.md, docs/index.md, docs/_config.yml, and one or two child pages before writing new docs — copy their tone and shape.

Core principles

1. Single source of truth lives on GitHub Pages. The README is an entry point, not a manual. If something takes more than a paragraph, it belongs on a page and the README links to it.
2. User perspective by default. Every page outside the Developer guide is written for someone using the thing, not building it. No build commands, no internal module names, no architecture diagrams — those live under development.
3. One Developer guide. The Developer guide may have child pages (Architecture, Extension points, etc.) — split when the parent page exceeds ~200 lines or covers distinct reference topics.
4. Theme-driven navigation. The sidebar is generated by just-the-docs reading front matter (nav_order, parent, has_children). Do not write manual nav strips on pages — the theme renders them.
5. Screenshots live in docs/screenshots/ and are referenced from every page that needs them.

File layout

Flat variant (single product, several user-facing capabilities):

README.md
docs/
  _config.yml
  index.md                    # nav_order: 1, the homepage
  pages/
    usage.md                  # nav_order: 2, has_children: true (parent stub)
    usage/
      <feature-a>.md          # parent: Usage, nav_order: 1
      <feature-b>.md          # parent: Usage, nav_order: 2
      ...
    development.md            # nav_order: 3, has_children: true
    development/
      architecture.md         # parent: Development, nav_order: 1
      extending.md            # parent: Development, nav_order: 2
    privacy.md                # if the product handles user data
  screenshots/
    *.png

Monorepo variant (several products sharing one docs site):

README.md
docs/
  _config.yml
  index.md
  pages/
    <product-a>.md            # nav_order: 2, has_children: true
    <product-a>/
      <feature>.md            # parent: <Product A>, nav_order: 1
    <product-b>.md            # nav_order: 3, has_children: true
    <product-b>/
      <feature>.md
    development.md            # nav_order: 99 (last), has_children: true
    development/
      <product-a>-architecture.md
      <product-b>-architecture.md
  screenshots/
    *.png

Splitting heuristic: a single page becomes a parent + children once it grows past ~200 lines OR has 5+ distinct H2 sections that read as separate references rather than a continuous narrative.

docs/_config.yml

Minimal Jekyll config using just-the-docs as a remote theme:

title: <Project Name>
description: <same tagline used in README / index.md>
remote_theme: just-the-docs/just-the-docs
baseurl: /<repo-name>
plugins:
  - jekyll-remote-theme
color_scheme: light
search_enabled: true
heading_anchors: true

exclude:
  - plans/                    # internal planning docs, if any

Content width

The default content width (~1100px) is conservative. For projects with wide code blocks or tables, override via _sass/custom/setup.scss (variable overrides, loaded before CSS):

$content-width: 87.5rem; // ~1400px at 16px base

The value must be in rem — GitHub Pages uses sass 3.x which rejects mixed px/rem arithmetic.

Do NOT use _sass/custom/custom.scss with .main-content { max-width: ... } — that class does not exist in just-the-docs. The actual class is .main, driven by $content-width.

Front matter cheat sheet

Key	When to use
layout: default	Required on every page
title: <Name>	Sidebar label; required
nav_order: N	Sidebar order — local to the level (top-level or within a parent's children)
parent: <Title>	Marks a page as a child; must match the parent's title: exactly
has_children: true	On a parent page; expands the disclosure arrow in the sidebar
nav_exclude: true	Hide a page from the sidebar entirely (rare — prefer parent/child structure)

docs/index.md shape

The homepage (nav_order: 1). Mirrors the README but lives inside the site.

---
layout: default
title: Home
nav_order: 1
---

*<One-line tagline — same as README, italicized.>*

<a href="screenshots/<cover>.png"><img src="screenshots/<cover>.png" alt="<descriptive alt>" width="1000"></a>

## Example  (optional — if a concrete before/after illustrates the value)

<Input → output illustration.>

## Features

- **<Feature 1>** — one-line user-visible description
- **<Feature 2>** — ...

## Install

<One-line pointer to the Developer guide or distribution channel.>

## Next steps

- **[Usage](pages/usage)** — <one-line description of what the user finds there>
- **[Developer guide](pages/development)** — <one-line description>

index.md does NOT contain a usage walkthrough or screenshots beyond the cover — those live in the user-facing pages. Keep it focused: what is this, what does it do, where do I learn more.

docs/pages/.md — parent stub (when split into children)

When a feature is large enough to need children, the parent page is a brief landing:

---
layout: default
title: <Feature Name>
nav_order: 2
has_children: true
---

<One-paragraph intro for the whole topic.>

<a href="../screenshots/<hero>.png"><img src="../screenshots/<hero>.png" alt="..." width="1000"></a>

## <Onboarding section, e.g. Installation>

<Brief content — anything that's "before you start using the feature".>

The parent doesn't repeat content from its children. just-the-docs auto-renders a child list at the bottom of the parent, so users can navigate into details from the parent body or from the sidebar.

docs/pages//_{.md — child page}

---
layout: default
title: <Sub-feature Name>
parent: <Feature Name>
nav_order: 1
---

<Direct content — no nav strip, no top-bar, the theme handles navigation.>

![<Alt>](../../screenshots/<file>.png)

Image path conventions:

Page location	Path to docs/screenshots/foo.png
docs/index.md	screenshots/foo.png
docs/pages/<feature>.md	../screenshots/foo.png
docs/pages/<feature>/<sub>.md	../../screenshots/foo.png

Internal link conventions (no .md extension, no leading ./):

Source → Target	Link form
Sibling at same level	[Other](other)
Parent's sibling (one level up)	[Other](../other)
Child of a sibling	[Other](../other-feature/sub)
Anchor within a sibling	[Section](other#anchor)

After restructuring, watch for stale anchors — #section-name references break silently when the target H2 is renamed or moved.

docs/pages/development.md

The Developer guide. Same parent-stub pattern when it grows children.

---
layout: default
title: Development
nav_order: 3
has_children: true
---

## Setup

### Prerequisites

- <runtime versions>

### Install / Build from source

<commands in a code fence>

## Commands

<Table or bulleted list of common dev commands.>

## Architecture

<Short rationale — 2-4 paragraphs of design principles. The full deep-dive lives in the Architecture child page.>

See the [Architecture reference](development/architecture) for the full domain model, data flow, and component breakdown.

## Project structure

<Annotated source tree.>

## Testing

<How to run tests.>

## Extension points

For step-by-step recipes, see the [Extension points reference](development/extending).

Children of development.md:

• development/architecture.md — long technical deep-dive (domain model, data flow, components, persistence, live-update path, etc.)
• development/extending.md — recipes for adding filters, colours, settings toggles, etc.
• More as needed.

Rules for the developer page:

• The parent's ## Architecture section is a brief rationale + link to the child reference. Do not duplicate content between parent and child.
• Likewise for Extension points: parent has a one-line pointer; the child has the recipes.
• Each child is reachable both from the sidebar (via parent: Development) and from a link inside development.md.

docs/pages/privacy.md (if applicable)

Required when the product reads, stores, or transmits user data. Follow the bga-assistant shape: what is / isn't collected, how the extension works, a permissions table, contact. Set nav_order to slot it into the sidebar at the appropriate position (typically last among top-level pages).

README.md shape

Keep it short enough to read on one screen. Structure, in order:

1. H1 project title.
2. One-line italicized tagline — must match docs/index.md's tagline byte-for-byte (excluding the *…* italics).
3. Cover screenshot: ![<descriptive alt>](docs/screenshots/<cover>.png) — alt text matches docs/index.md for consistency.
4. Features bulleted list — copy from docs/index.md Features section. Bullets must match exactly (same set, same wording, same order).
5. Install — one-line pointer to the Developer guide on GH Pages.
6. Footer block listing every page in the docs site:

---

See full project documentation at **[<org>.github.io/<repo>](https://<org>.github.io/<repo>/)**:

- [<Top-level page A>](https://<org>.github.io/<repo>/pages/<a>)
  - [<Child A.1>](https://<org>.github.io/<repo>/pages/<a>/<sub>)
  - ...
- [<Top-level page B>](https://<org>.github.io/<repo>/pages/<b>)
  - [<Child B.1>](https://<org>.github.io/<repo>/pages/<b>/<sub>)

Indentation must match the actual parent/child hierarchy. Every existing page must appear; no listed page may be missing on disk.

The README never contains setup, build, architecture, or API content. If you catch yourself writing any of that in the README, move it to development.md and leave a link.

In-app About dialog (if present)

Some projects (desktop apps, browser extensions, IDE plugins) ship an in-app About dialog. When one exists, treat it as a third surface that carries the same descriptive prose as README.md and docs/index.md: the tagline plus the short what-it-does description must match across all three, word for word. Pick one source of truth and propagate edits to the other two.

The About dialog additionally carries two things the README/home page handle elsewhere, and which belong only in the dialog:

• Version and release date — the running build's version (and its release date if available).
• A link to the project documentation — pointing at the GitHub Pages home page.

So the rule is: shared descriptive prose, dialog-only version/date + docs link. Do not copy screenshots, Features bullets, Install pointers, or the docs footer into the About dialog — those stay on the README/site.

Writing process

Follow these steps whenever creating or restructuring docs.

1. Inventory. List the user-facing capabilities. Decide which top-level pages exist (Home, Usage, Development, optional Privacy) and what children each has. A long page splits into one child per major section once it exceeds ~200 lines / 5+ H2 headings.
2. Set up _config.yml. Use the just-the-docs template above. baseurl must match the GitHub repo name.
3. Write docs/index.md. Tagline + hero screenshot + (optional Example) + Features bullets + Install pointer + Next steps. Do not include a usage walkthrough — push that to the Usage page tree.
4. Write child pages. One sub-capability per file under docs/pages/<feature>/. Each gets parent: <Feature> + a local nav_order. No nav strips.
5. Write the parent stub for each feature. Brief intro + has_children: true. The parent doesn't repeat children's content.
6. Write development.md the same way: parent for the dev tree, with children for Architecture, Extension points, etc.
7. Write README.md last. Lift the tagline and Features bullets from index.md. Footer lists every existing page hierarchically. Verify each footer URL resolves.
8. Verify cross-consistency.
   • Tagline matches across README.md, docs/index.md, _config.yml description, and the in-app About dialog (if present).
   • Descriptive prose (tagline + what-it-does paragraphs) matches across README.md, docs/index.md, and the About dialog (if present), word for word.
   • Features bullets match between README.md and docs/index.md (set, wording, order).
   • Hero-screenshot alt text matches across README.md and docs/index.md.
   • Footer in README.md lists every docs/pages/**.md (excluding nav-excluded pages); no listed page is missing on disk.
   • Internal links: bare names for siblings, .. for cross-level — and search for stale #anchor-name references after any section rename.

Out of scope

• Do NOT write manual nav strips ([Home] | [Usage] | …) on pages — just-the-docs renders the sidebar from front matter.
• Do NOT add more than one Developer-guide entry at the top level — technical deep-dives become children of development.md, not separate top-level pages.
• Do NOT mix this layout with another docs framework. If a project already uses Docusaurus, MkDocs, VitePress, Astro Starlight, etc., do not migrate — defer.
• Do NOT create CONTRIBUTING.md, CHANGELOG.md, or other root-level docs unless asked — they are not part of this layout.
• Do NOT inline screenshots, blurbs, or feature walkthroughs into the README beyond what's prescribed (tagline, hero, Features, Install, footer). Anything more belongs on the docs site.