docs: add Theme Elementary guides and Docusaurus workflow by Adi-ty · Pull Request #778 · rtCamp/theme-elementary

Adi-ty · 2026-09-15T08:52:21Z

Description

Create a clear documentation journey for Theme Elementary and publish it through the shared Docusaurus workflow.

Technical Details

Reworked README.md, DEVELOPMENT.md, and CONTRIBUTING.md as concise entry points.
Added Getting Started, Initialization, Local Development, Features, and Scaffolding guides.
Replaced the old Quick Start and internal-testing documentation with structured internal maintainer guidance.
Added cleanup validation, dependency-development procedures, temporary-procedure tracking, and validation-result recording.
Added Graphify maintainer guidance.
Updated asset, HMR, and Tailwind documentation links and behavior.
Added the shared Docusaurus documentation workflow, pinned to a reviewed revision.
Configured the supported theme-elementary-v2 branch and documentation sidebar.

Checklist

Provide a primary Getting Started path.
Document acquisition, initialization, local development, checks, and production builds.
Catalogue built-in, example, and optional functionality.
Document manual extension and companion-plugin CPT/taxonomy examples.
Keep maintainer-only procedures under docs/internal/.
Add documentation build automation.
Remove stale Quick Start and internal-testing references.
Verify documentation links and anchors.

Fixes/Covers Issue

Fixes #768

Covers #769, #770, #771, #772, #773, #774, #775, #776

Consolidate onboarding, development, feature, and maintainer guidance, and build the documentation site through the shared workflow.

divyarajmasani

@Adi-ty

I reviewed the PR, I believe the documentation could you more user friendly language. We need not make every paragraph as short as possible.

Also, there were some good documentation overridden by a short version as well, let's revisit these changes again and ensure we do not introduce changes where it doesn't require.

divyarajmasani · 2026-09-17T14:13:14Z

+Use this starter to create a named WordPress block theme. It provides the theme
+structure, examples, asset pipeline, checks, and optional development features
+needed for a new project.


Suggested change

Use this starter to create a named WordPress block theme. It provides the theme

structure, examples, asset pipeline, checks, and optional development features

needed for a new project.

This is a starter WordPress blocks theme. It provides the

structure, examples, asset pipeline, checks, and optional development features

needed for building a new blocks theme.

divyarajmasani · 2026-09-17T14:22:55Z

+Runtime abstractions ship separately in the
+[`rtcamp/wp-framework`](https://github.com/rtCamp/wp-framework) Composer package.
+The init and feature-scaffolding workflows use
+[`@rtcamp/wp-tooling`](https://github.com/rtCamp/wp-tooling).


This sentence could be more direct,

Suggested change

Runtime abstractions ship separately in the

[`rtcamp/wp-framework`](https://github.com/rtCamp/wp-framework) Composer package.

The init and feature-scaffolding workflows use

[`@rtcamp/wp-tooling`](https://github.com/rtCamp/wp-tooling).

This theme uses ⁠[`rtcamp/wp-framework`](https://github.com/rtCamp/wp-framework) as a runtime dependency and ships with [`@rtcamp/wp-tooling`](https://github.com/rtCamp/wp-tooling) for streamlined project initialization and feature scaffolding.

divyarajmasani · 2026-09-17T14:46:31Z


-## AI tooling
+- **Claude Code:** retained skills in [`.claude/skills/`](.claude/skills/) — `/init`, `/scaffold`, and `/setup`.
+- **GitHub Copilot:** `/init` and `/scaffold` prompts are available while setting up this source repository; initialization removes `.github` from the resulting project.


I believe this would not be the expected outcome, to remove .github means it will also remove default issue templates, workflows and more.

Please, confirm and we could look are updating this behaviour so to retain necessary defaults.

Yes this is the current behaviour cleanup.targets in bin/scaffold.config.js lists .github wholesale, and the shared cleanup step does a recursive delete on it, so init does remove all of .github today, not just the Copilot prompts.

That said, you're right that it's not the ideal outcome — issue templates, PULL_REQUEST_TEMPLATE.md, dependabot.yml, release.yml, and the workflows get removed along with the AI files. We can narrow the cleanup target so only the AI-specific paths

divyarajmasani · 2026-09-17T14:56:55Z

 				devDependencies: {
-					'@rtcamp/tailwind-config': '^0.1.0',
+					'@rtcamp/tailwind-config':
+						'github:rtCamp/wp-tooling#npm/tailwind-config',


I believe this change is temporary and will be removed once the package is published. Is that true?

If so, need to add a section specifically for such changes, or libs that are using internal repos.

Yes, that's correct this is temporary. @rtcamp/tailwind-config isn't published to npm yet, so pinning ^0.1.0 would fail to resolve; pointing at the wp-tooling GitHub ref is the only way --enable=tailwind actually works right now. Once the package is published, we'll switch this back to a normal semver range.

Went with this over documenting a manual separate-download step for tailwind-config because that would push extra setup work onto every user enabling Tailwind, and we'd have to keep the /init skill and initialization.md/tailwind.md in sync with a manual step that's only needed until publishing happens more moving parts for something that resolves itself once the package ships.

divyarajmasani · 2026-09-17T15:08:27Z

+name: Documentation
+
+on:
+  push:


The documentation action was updated, check the final workflow here,

https://github.com/rtCamp/wp-framework/blob/main/.github/workflows/documentation.yml

divyarajmasani · 2026-09-17T17:47:13Z

+Create an **Acme Blog** theme, activate it in local WordPress, and see a source
+edit on the frontend. Run commands from the theme directory unless a step says


This paragraph should read more natural and informative to the user, for what they can expect or what this is about.

The sentence structure looks incomplete and short.

divyarajmasani · 2026-09-17T17:48:03Z

+Have Git, Composer 2, PHP 8.2+, Node and npm matching [`.nvmrc`](../.nvmrc), and a
+running Docker installation for the recommended `wp-env` route. Use `nvm` or
+another Node version manager to select the version in `.nvmrc`.
+
+```bash
+git --version
+composer --version
+php --version
+node --version
+npm --version
+docker info
+```


Could become a pre-requisite section, may not need the commands. Though if any particular version is needed can add that.

divyarajmasani · 2026-09-17T17:49:20Z

+At this point, `vendor/autoload.php` and `node_modules/@rtcamp/wp-tooling` should
+exist. Resolve installation errors before continuing; see


I think the first sentence is redundant,

Suggested change

At this point, `vendor/autoload.php` and `node_modules/@rtcamp/wp-tooling` should

exist. Resolve installation errors before continuing; see

Resolve installation errors before continuing; see

divyarajmasani · 2026-09-17T17:55:54Z

I find the previous wording in the documentation to be more user friendly, only check the asset-building-process for the correctness and add what's missing.

divyarajmasani · 2026-09-17T17:59:07Z

Most of the previous document content seems to be removed, please review the wording. and document flow. Do not remove any information that is simple to understand by the users.

docs: add guides and documentation workflow

0be9f46

Consolidate onboarding, development, feature, and maintainer guidance, and build the documentation site through the shared workflow.

Adi-ty added this pull request to stack #779 September 15, 2026 08:52

Adi-ty requested review from aryanjasala and divyarajmasani September 15, 2026 08:52

Adi-ty marked this pull request as ready for review September 15, 2026 08:57

divyarajmasani requested changes Sep 17, 2026

View reviewed changes

Adi-ty added 2 commits September 18, 2026 10:52

fix: update cleanup targets in scaffold config

02ccaae

docs: address PR review feedback on documentation

9a4a843

Adi-ty requested a review from divyarajmasani September 18, 2026 06:53

Navigation Menu

docs: add Theme Elementary guides and Docusaurus workflow - #778

docs: add Theme Elementary guides and Docusaurus workflow#778
Adi-ty wants to merge 3 commits into
feat/init-devtoolsfrom
docs/theme-elementary-v2

Adi-ty commented Sep 15, 2026

Uh oh!

divyarajmasani left a comment

Uh oh!

divyarajmasani Sep 17, 2026

Uh oh!

divyarajmasani Sep 17, 2026

Uh oh!

divyarajmasani Sep 17, 2026

Uh oh!

Adi-ty Sep 17, 2026

Uh oh!

divyarajmasani Sep 17, 2026

Uh oh!

Adi-ty Sep 17, 2026

Uh oh!

divyarajmasani Sep 17, 2026

Uh oh!

divyarajmasani Sep 17, 2026

Uh oh!

divyarajmasani Sep 17, 2026

Uh oh!

divyarajmasani Sep 17, 2026

Uh oh!

divyarajmasani Sep 17, 2026

Uh oh!

divyarajmasani Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		Create an Acme Blog theme, activate it in local WordPress, and see a source
		edit on the frontend. Run commands from the theme directory unless a step says

		At this point, `vendor/autoload.php` and `node_modules/@rtcamp/wp-tooling` should
		exist. Resolve installation errors before continuing; see

	At this point, `vendor/autoload.php` and `node_modules/@rtcamp/wp-tooling` should
	exist. Resolve installation errors before continuing; see
	Resolve installation errors before continuing; see

Conversation

Adi-ty commented Sep 15, 2026

Description

Technical Details

Checklist

Fixes/Covers Issue

Uh oh!

divyarajmasani left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants