Repository navigation
Description
Summary
Organize documentation around the developer's journey: start a project, understand what the skeleton includes, modify an example, add functionality, and resolve common failures. Provide enough context to complete these tasks without requiring developers to read framework source.
Branch baseline
Use theme-elementary-v2 as the base branch for this epic and every sub-issue. Document the functionality introduced on that branch and subsequent changes built on it; do not use main as the implementation reference. Before writing or validating a guide, check the latest relevant v2 changes and record the branch and commit tested in the documentation PR.
Documentation ownership
- Theme Elementary: what ships, where files belong, initialization, local workflows, integration examples, and troubleshooting specific to the skeleton.
- wp-framework: detailed class contracts, inherited methods, lifecycle, APIs, and full framework tutorials.
- wp-tooling: generic scaffold catalogue, engine behavior, and exhaustive command options.
Link directly to relevant, version-compatible upstream documentation. Do not reproduce those references locally or require developers to search upstream homepages.
Documentation map and sub-issues
| Document | Purpose | Issue |
|---|---|---|
README.md |
Brief overview and task-based navigation | 01 — README |
docs/getting-started.md |
One tested route to a running theme | 02 — Getting started |
docs/initialization.md |
Prompts, changes, cleanup, and later management | 03 — Initialization |
docs/local-development.md |
Daily editing, builds, checks, and troubleshooting | 04 — Local development |
docs/scaffolding.md |
One feature generated through CLI and AI | 05 — Scaffolding |
docs/features.md |
Built-in infrastructure, examples, and optional features | 06 — What is included |
DEVELOPMENT.md |
Short worked examples for extending the project | 07 — Extending the theme |
docs/internal/ |
Release validation and dependency development | 08 — Internal documentation |
- 01 — Make the README a concise documentation entry point.
- 02 — Add one verified route to a running theme.
- 03 — Explain initialization prompts, changes, and later management.
- 04 — Document the daily local-development workflow.
- 05 — Explain CLI and AI scaffolding through one feature.
- 06 — Explain what the skeleton includes.
- 07 — Document extending the theme with short worked examples.
- 08 — Separate maintainer procedures from developer onboarding.
Shared editorial requirements
- Give each page one task and a clear outcome; put advanced material behind links.
- Keep one canonical home for each procedure. Getting Started composes the minimum steps; reference pages provide detail.
- Each example answers: where does it go, what changes, how does it become active, and how is success checked?
- State the working directory and distinguish standalone setup from an existing WordPress/VIP repository. Link to project-level instructions for full VIP setup.
- Explain AI and CLI as alternative entry points; make their differing outputs and remaining work explicit.
- Use brief symptom → check → next action troubleshooting entries.
- Include review checkpoints after personalization and feature completion. Suggest separate baseline and feature commits without imposing a history policy.
- Verify commands against
theme-elementary-v2and subsequent work based on it; test the user journeys in a disposable project and record the tested commit. - Keep links valid when documents move or downstream cleanup removes files; update old entry points.
- Keep pilot workarounds separate and time-bound. Do not publish hypothetical stable commands as working instructions.
Acceptance criteria
- A first-time developer can start a project and see the theme running.
- They can identify supplied functionality, editable source files, and generated output.
- They can adapt an example and add a feature through a supported manual or assisted route.
- They can resolve representative setup, registration, and asset failures using the guides.
- These tasks do not require reading framework source or a complete class reference.
- Commands and links have been checked, with validation results recorded in the documentation PR.
- Any missing upstream documentation or implementation blocker has a linked follow-up issue.
Implementation dependencies and exclusions
Cleanup failures, dependency-install behavior, scaffold wrappers, test-script fixes, and CI automation belong in separate implementation issues. Link concrete dependencies where they prevent a documented journey from working; do not silently expand documentation tasks into code changes.
This epic does not prescribe dynamic versus static blocks, redesign framework APIs, or duplicate framework/tooling manuals.
Activity
Adi-ty commentedon Sep 22, 2026
I went back to the original pre-restructure docs and rebuilt the pages from that source restoring the fuller, more explanatory language flagged as lost. Changed stale/incorrect instructions that no longer match the current setup.
cc: @divyarajmasani
divyarajmasani commentedon Sep 24, 2026
I've reviewed the updated PR, and recommended a few minor changes. Please complete those and we can merge the PR.
Adi-ty commentedon Sep 24, 2026
Hi @divyarajmasani, all review feedback has been addressed. Just a couple of notes: the absolute URL in
.claude/skills/README.mdis intentionalnpm run initremoves.github/prompts/, so a relative link would break in initialized themes. It now points totheme-elementary-v2, since the prompts don't exist onmainyet. Haven't changed absolute URLs pointing totheme-elementary-v2for now will change it after it get merged tomain.Thanks 🚀
divyarajmasani commentedon Sep 25, 2026
@Adi-ty , updates looks good.
About the clean up step, I believe the
.github/promptsis something that user may want to keep. It would make sense to avoid removing it in cleanup? or asking user specifically 🤔Adi-ty commentedon Nov 3, 2026
The documentation for theme-elementary has been completed and merged as part of PR #787. All the required documentation changes are included in the merged PR.