Github pages

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 — just-the-docs flat variant; game pages grouped under a Games parent, a game-agnostic feature page (Play-time tracking) at top level, and a Development page with the data-flow reference nested under it via front matter.

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
  _includes/
    footer_custom.html        # empty — drops the "This site uses Just the Docs" footer line
  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.

Footer attribution

just-the-docs renders "This site uses Just the Docs, a documentation theme for Jekyll." in the page footer — that text is the default content of the theme's _includes/footer_custom.html, not a config option. Remove it by default by shadowing that include with an empty docs/_includes/footer_custom.html (Jekyll resolves local _includes/ before the remote theme, same precedence as the _sass/ overrides). The rest of the footer (search, "back to top") is untouched. To carry a copyright line instead of nothing, put that markup in the same file.

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.>*

<Context paragraph: what kind of thing this is (form factor, supported platforms) plus the one or two core capabilities a visitor sees first — not a features rundown; those stay in the list below.>

<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  (omit when a dedicated Installation page leads the Next steps list below)

<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/<feature>.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/<feature>/<sub>.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. Context paragraph — copy from docs/index.md (form factor, platforms, the one or two headline capabilities). Must match word for word.
4. Cover screenshot: ![<descriptive alt>](docs/screenshots/<cover>.png) — alt text matches docs/index.md for consistency.
5. Features bulleted list — copy from docs/index.md Features section. Bullets must match exactly (same set, same wording, same order). Capabilities already named in the context paragraph don't get a bullet — each feature lives in exactly one of the two.
6. Install — one-line pointer to wherever install instructions live (Developer guide or a dedicated Installation page). Omit entirely when the docs site has a dedicated Installation page sitting at the top of the footer list below — a pointer one line above its own footer link is duplication.
7. 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 shares the tagline with README.md and docs/index.md, word for word. Beyond the tagline the surfaces diverge: README and index carry the Features bullet list (see below), while the About dialog carries its own short what-it-does prose — a couple of sentences, not required to mirror README/index paragraphs and never a bullet list.

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 tagline, dialog-own 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. Also create an empty docs/_includes/footer_custom.html to drop the theme's footer attribution (see Footer attribution).
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).
   • Context paragraph matches between README.md and docs/index.md, word for word, and no capability appears in both the paragraph and a Features bullet.
   • Features bullets match between README.md and docs/index.md (set, wording, order). When a Features page exists, the list covers the same topics (it may skip lesser, plumbing-level sections like configuration mechanics or naming details) but need not share its order: the summary list is a highlight reel and may rank bullets by impact, while the reference page keeps a logical build-up order — that divergence is deliberate, not drift.
   • 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.