Repository navigation
docs: add Theme Elementary guides and Docusaurus workflow #778
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
Closed
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
0be9f46
docs: add guides and documentation workflow
Adi-ty 02ccaae
fix: update cleanup targets in scaffold config
Adi-ty 9a4a843
docs: address PR review feedback on documentation
Adi-ty 9f36e68
docs: address readability feedback across all documentation
Adi-ty 7f12283
docs: unify troubleshooting headings, fix inaccuracies, and tighten p…
Adi-ty cd0ea4f
docs: drop hard-wrapped lines, rebuild asset/hmr/tailwind docs from s…
Adi-ty 5fc0794
docs: address second-round review feedback
Adi-ty File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| name: Documentation | ||
|
|
||
| on: | ||
| push: | ||
| branches: [theme-elementary-v2] | ||
| paths: | ||
| - 'docs/**' | ||
| - 'README.md' | ||
| - 'DEVELOPMENT.md' | ||
| - 'CONTRIBUTING.md' | ||
| - '.github/workflows/documentation.yml' | ||
| pull_request: | ||
| branches: [theme-elementary-v2] | ||
| paths: | ||
| - 'docs/**' | ||
| - 'README.md' | ||
| - 'DEVELOPMENT.md' | ||
| - 'CONTRIBUTING.md' | ||
| - '.github/workflows/documentation.yml' | ||
| workflow_dispatch: | ||
|
|
||
| permissions: | ||
| contents: read | ||
|
|
||
| concurrency: | ||
| group: documentation-${{ github.event_name == 'pull_request' && github.ref || 'production' }} | ||
| cancel-in-progress: true | ||
|
|
||
| jobs: | ||
| build: | ||
| name: Build documentation | ||
| runs-on: ubuntu-latest | ||
| timeout-minutes: 15 | ||
| permissions: | ||
| contents: read | ||
| pages: read | ||
| steps: | ||
| - name: Checkout documentation | ||
| uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | ||
| with: | ||
| persist-credentials: false | ||
|
|
||
| - name: Read Pages configuration | ||
| id: pages | ||
| if: >- | ||
| (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && | ||
| github.ref_type == 'branch' && github.ref_name == 'theme-elementary-v2' | ||
| uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0 | ||
|
|
||
| - name: Build documentation | ||
| id: docs | ||
| uses: rtCamp/action-docusaurus-build@b671d6800c68a74da8913edb9321422fe8afaedc | ||
| with: | ||
| site-title: Theme Elementary | ||
| site-url: ${{ steps.pages.outputs.origin }} | ||
| base-url: ${{ steps.pages.outputs.base_url && format('{0}/', steps.pages.outputs.base_path) || '' }} | ||
| sidebar: >- | ||
| ["index", "getting-started", "initialization", "local-development", "features", "scaffolding"] | ||
|
|
||
| - name: Upload GitHub Pages artifact | ||
| if: >- | ||
| (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && | ||
| github.ref_type == 'branch' && github.ref_name == 'theme-elementary-v2' | ||
| uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 | ||
| with: | ||
| path: ${{ steps.docs.outputs.build-directory }} | ||
| include-hidden-files: true | ||
|
|
||
| deploy: | ||
| name: Deploy documentation | ||
| needs: build | ||
| if: >- | ||
| (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && | ||
| github.ref_type == 'branch' && github.ref_name == 'theme-elementary-v2' | ||
| runs-on: ubuntu-latest | ||
| timeout-minutes: 10 | ||
| permissions: | ||
| contents: read | ||
| pages: write | ||
| id-token: write | ||
| environment: | ||
| name: github-pages | ||
| url: ${{ steps.deployment.outputs.page_url }} | ||
| steps: | ||
| - name: Deploy to GitHub Pages | ||
| id: deployment | ||
| uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,43 +1,32 @@ | ||
| # Contributing to Theme Elementary | ||
|
|
||
| Thanks for your interest in improving Theme Elementary — a WordPress block | ||
| starter theme built on the `rtcamp/wp-framework` package. | ||
| Thanks for your interest in improving Theme Elementary — a WordPress block starter theme built on the `rtcamp/wp-framework` package. | ||
|
|
||
| ## Development setup | ||
|
|
||
| Requires the Node version in `.nvmrc` (`nvm use`) and PHP 8.2+. | ||
| Use [Getting started](docs/getting-started.md) for dependency installation — it installs PHP dependencies and tooling like PHPCS/PHPStan via Composer, and the build toolchain via npm. Then use [Local development](docs/local-development.md) for the daily environment, build, and verification workflow. The project requires the Node version in `.nvmrc` and PHP 8.2+. | ||
|
|
||
| ```bash | ||
| nvm use | ||
| composer install # PHP dependencies + tooling (PHPCS, PHPStan) | ||
| npm install # build toolchain | ||
| ``` | ||
| For release validation, local dependency work, and documentation publishing, use the [maintainer guidance](docs/internal/README.md). | ||
|
|
||
| ## Building assets | ||
|
|
||
| ```bash | ||
| npm start # watch build (blocks + assets) | ||
| npm start # watch build (assets + blocks) | ||
| npm run build:prod # production build | ||
| ``` | ||
|
|
||
| ## Before you open a PR | ||
| See [Local development](docs/local-development.md#edit-source-and-see-the-result) for watch-build details and [the delivery build](docs/local-development.md#build-for-delivery) for production output. | ||
|
|
||
| Run the checks — all must pass: | ||
| ## Before you open a PR | ||
|
|
||
| ```bash | ||
| npm run lint:all # PHP (PHPCS) + JS (ESLint) + CSS (Stylelint) | ||
| composer phpstan # static analysis | ||
| npm test # JS + PHP test suites (PHP runs via @wordpress/env) | ||
| ``` | ||
| Run the relevant focused tests and lint commands in [Local development](docs/local-development.md#check-a-change); all must pass. | ||
|
|
||
| ## Pull request checklist | ||
|
|
||
| - [ ] `npm run lint:all` and `composer phpstan` pass. | ||
| - [ ] `npm test` passes. | ||
| - [ ] The relevant focused tests and lint commands pass. | ||
| - [ ] New/changed behavior is covered by tests. | ||
| - [ ] Commits follow [Conventional Commits](https://www.conventionalcommits.org/). | ||
|
|
||
| ## License | ||
|
|
||
| By contributing, you agree that your contributions are licensed under the | ||
| project's [GPL-2.0-or-later](LICENSE) license. | ||
| By contributing, you agree that your contributions are licensed under the project's [GPL-2.0-or-later](LICENSE) license. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.