Skip to content

[Docs] Document extending the theme with short worked examples #775

Open

Description

@divyarajmasani

Parent epic: #768 — Documentation epic

Base branch: theme-elementary-v2. Cover its functionality and subsequent changes based on it. Verify against the latest relevant v2 implementation and record the tested commit in the documentation PR.

Problem and scope

Developers need enough context to use the skeleton and add functionality without reading framework source. Refocus DEVELOPMENT.md on short practical examples. wp-framework owns detailed class documentation and full tutorials.

Proposed structure

  1. Before adding code: a small folder map, the project namespace, and the registration point.
  2. Adapt an included example: one focused change to a supplied feature, such as a shortcode or settings page.
  3. Add a feature: a minimal working class, its exact file location, required registration, and a focused verification example.
  4. Create a CPT and taxonomy: concise examples showing the relevant framework abstracts and integration steps; link to full framework tutorials.
  5. When it does not appear: checks for missing registration, namespace/autoload mismatch, missing build output, and errors.

Example requirements

Each example answers four questions:

  • Where does this code go?
  • What does the developer change?
  • How does it become active?
  • How does the developer verify it works?

Keep snippets small but usable. Explain only the framework conventions needed for that example; link to version-compatible documentation for inherited methods, class contracts, and lifecycle detail.

Identify CPT/taxonomy examples as companion-plugin work where persistence across theme switches is required. Name the destination and its actual registration mechanism; do not imply the theme's Main::CLASSES registers a companion plugin's classes.

Boundaries

  • No decision tree prescribing dynamic versus static blocks or other project-specific design choices.
  • No full framework API, abstract-class catalogue, or architecture manual.
  • Link to scaffolding for CLI/AI generation, features for the supplied inventory, and local development for full verification commands.
  • Use theme-local wiring only for theme examples and explicit plugin context for plugin examples.

Acceptance criteria

  • A developer can adapt an included example and add a small feature using this guide.
  • Feature, CPT, and taxonomy examples identify destination, activation, and verification.
  • Examples match the supported namespace/path/registration conventions for their respective project.
  • Framework details and full tutorials are linked directly upstream.
  • Common integration failures include concrete checks and next actions.
  • The guide remains focused on getting started and unblocking development.

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions