| name | github-pages-content-architecture |
| description | Plan or restructure the content architecture of a GitHub Pages documentation site, repository website, wiki, or project landing page. Use for Pages-specific content inventories, reader journeys, page hierarchy, navigation labels, documentation copy, and static local-search behavior. Do not use for generic product information architecture, marketing content programs, user-research studies, or non-Pages websites. |
GitHub Pages Content Architecture
Turn repository evidence into a small, findable Pages site whose structure matches real reader tasks.
Stay inside the Pages boundary
- Establish the repository's readers, public URL shape, existing routes, documentation sources, and first successful task before proposing structure.
- Treat README files, maintained docs, examples, schemas, changelogs, contribution guidance, security policy, and license as evidence. Do not invent missing content.
- Prefer links or generated imports over copied canonical facts.
- Design for static generation and client-side behavior. Do not prescribe server search, personalization, accounts, or analytics unless another authorized system provides them.
- Preserve existing public routes and anchors; content reorganization does not authorize URL breakage.
- When the request also requires implementing framework, route, build, or deployment changes, hand those concerns to
create-github-pages and keep this skill focused on the content model.
Read the contract
Read references/pages-content-contract.md before designing or restructuring the site's content, navigation, labels, or search.
Produce a reviewable content plan
Record:
- intended readers and their priority tasks;
- source-of-truth files for each proposed page or section;
- current and proposed page hierarchy;
- global, local, utility, and contextual navigation;
- route and anchor preservation decisions;
- content gaps, duplicates, and unsupported claims;
- search behavior when the content scale justifies it;
- concise copy rules derived from repository terminology and branding.
Omit empty destinations. Prefer one complete page over a shallow collection of placeholders.
If repository evidence or the current route inventory is unavailable, label the result provisional. Provide the smallest useful candidate structure plus the exact files, routes, or configuration needed to turn it into a verified plan; do not present guessed pages or mappings as final.
Verify the result
- Every page must serve a named reader task and trace material claims to repository evidence.
- Navigation labels must predict their destinations and remain consistent with headings and search terms.
- A reader must be able to complete the primary task without guessing prerequisites or crossing broken links.
- Search, when present, must be local or explicitly authorized, keyboard reachable, and tested with representative repository terms.
- Report unresolved content ownership, freshness, route, and terminology questions rather than guessing.
