Skip to content

Commit f3e875b

Browse files
ashleyshawashleyshaw
committed
Add comprehensive documentation index for all folders
1 parent 0bb7a7f commit f3e875b

File tree

2 files changed

+846
-0
lines changed

2 files changed

+846
-0
lines changed

‎docs/README.md‎

Lines changed: 311 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,311 @@
1+
# Documentation
2+
3+
Comprehensive documentation for the {{theme_name}} block theme scaffold.
4+
5+
## Overview
6+
7+
```mermaid
8+
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1e4d78', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#15354f', 'lineColor': '#333333', 'secondaryColor': '#f0f0f0', 'tertiaryColor': '#e8e8e8', 'background': '#ffffff', 'mainBkg': '#1e4d78', 'textColor': '#333333', 'nodeBorder': '#15354f', 'clusterBkg': '#f8f9fa', 'clusterBorder': '#dee2e6', 'titleColor': '#333333'}}}%%
9+
flowchart TB
10+
subgraph Getting["Getting Started"]
11+
Generate["GENERATE-THEME.md<br/>Theme Generation"]
12+
Setup["SETUP-SUMMARY.md<br/>Setup Overview"]
13+
end
14+
15+
subgraph Development["Development"]
16+
Build["BUILD-PROCESS.md<br/>Build System"]
17+
Source["SRC-FOLDER-STRUCTURE.md<br/>Source Files"]
18+
I18n["INTERNATIONALIZATION.md<br/>Translations"]
19+
end
20+
21+
subgraph Tools["Tools & Configuration"]
22+
WPScripts["WP-SCRIPTS-*.md<br/>wp-scripts Docs"]
23+
ToolConfigs["TOOL-CONFIGS.md<br/>Tool Overview"]
24+
Config["config/<br/>Detailed Configs"]
25+
end
26+
27+
Generate --> Setup
28+
Setup --> Build
29+
Build --> Source
30+
Source --> I18n
31+
WPScripts --> ToolConfigs
32+
ToolConfigs --> Config
33+
```
34+
35+
## Quick Start
36+
37+
New to this scaffold? Start here:
38+
39+
1. 📖 [Theme Generation Guide](./GENERATE-THEME.md) - How to create a theme from this scaffold
40+
2. 🎯 [Setup Summary](./SETUP-SUMMARY.md) - Overview of what's configured
41+
3. 🏗️ [Build Process](./BUILD-PROCESS.md) - Understanding the build system
42+
43+
## Documentation Structure
44+
45+
### Getting Started
46+
47+
| Document | Description |
48+
|----------|-------------|
49+
| [GENERATE-THEME.md](./GENERATE-THEME.md) | Complete guide to generating a theme from this scaffold |
50+
| [SETUP-SUMMARY.md](./SETUP-SUMMARY.md) | Overview of completed setup tasks and configurations |
51+
52+
### Development Guides
53+
54+
| Document | Description |
55+
|----------|-------------|
56+
| [BUILD-PROCESS.md](./BUILD-PROCESS.md) | Complete build process documentation with webpack, Babel, and asset compilation |
57+
| [SRC-FOLDER-STRUCTURE.md](./SRC-FOLDER-STRUCTURE.md) | Source directory structure and file organization |
58+
| [INTERNATIONALIZATION.md](./INTERNATIONALIZATION.md) | Translation and localization guide |
59+
60+
### wp-scripts Documentation
61+
62+
Detailed documentation for `@wordpress/scripts` build system:
63+
64+
| Document | Description |
65+
|----------|-------------|
66+
| [WP-SCRIPTS-SUMMARY.md](./WP-SCRIPTS-SUMMARY.md) | Overview of wp-scripts configuration and features |
67+
| [WP-SCRIPTS-CONFIGURATION.md](./WP-SCRIPTS-CONFIGURATION.md) | Complete configuration guide for wp-scripts |
68+
| [WP-SCRIPTS-QUICK-REFERENCE.md](./WP-SCRIPTS-QUICK-REFERENCE.md) | Quick reference for common commands and patterns |
69+
70+
### Tool Configuration
71+
72+
| Document | Description |
73+
|----------|-------------|
74+
| [TOOL-CONFIGS.md](./TOOL-CONFIGS.md) | Overview of all development tools and their purposes |
75+
| [config/](./config/) | Detailed configuration guides for individual tools |
76+
77+
## Configuration Files
78+
79+
The `config/` directory contains detailed documentation for each tool:
80+
81+
```mermaid
82+
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1e4d78', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#15354f', 'lineColor': '#333333', 'secondaryColor': '#f0f0f0', 'tertiaryColor': '#e8e8e8', 'background': '#ffffff', 'mainBkg': '#1e4d78', 'textColor': '#333333', 'nodeBorder': '#15354f', 'clusterBkg': '#f8f9fa', 'clusterBorder': '#dee2e6', 'titleColor': '#333333'}}}%%
83+
flowchart LR
84+
subgraph Build["Build Tools"]
85+
Webpack["webpack.md"]
86+
Babel["babel.md"]
87+
PostCSS["postcss.md"]
88+
end
89+
90+
subgraph Quality["Code Quality"]
91+
ESLint["eslint.md"]
92+
Stylelint["stylelint.md"]
93+
Prettier["prettier.md"]
94+
NPMLint["npm-package-json-lint.md"]
95+
end
96+
97+
subgraph Testing["Testing Tools"]
98+
Jest["jest.md"]
99+
Playwright["playwright.md"]
100+
end
101+
102+
Build --> Quality
103+
Quality --> Testing
104+
```
105+
106+
### Available Configuration Guides
107+
108+
- [babel.md](./config/babel.md) - Babel transpilation configuration
109+
- [eslint.md](./config/eslint.md) - JavaScript linting rules
110+
- [jest.md](./config/jest.md) - JavaScript testing configuration
111+
- [npm-package-json-lint.md](./config/npm-package-json-lint.md) - Package.json validation
112+
- [playwright.md](./config/playwright.md) - End-to-end testing setup
113+
- [postcss.md](./config/postcss.md) - CSS processing and optimization
114+
- [prettier.md](./config/prettier.md) - Code formatting rules
115+
- [stylelint.md](./config/stylelint.md) - CSS/SCSS linting configuration
116+
- [webpack.md](./config/webpack.md) - Module bundling configuration
117+
118+
## Common Tasks
119+
120+
### Development Workflow
121+
122+
```bash
123+
# Install dependencies
124+
npm install
125+
126+
# Start development server with watch mode
127+
npm run start
128+
129+
# Build for production
130+
npm run build
131+
```
132+
133+
### Code Quality
134+
135+
```bash
136+
# Lint JavaScript
137+
npm run lint:js
138+
139+
# Lint CSS/SCSS
140+
npm run lint:css
141+
142+
# Format all files
143+
npm run format
144+
145+
# Run all linters
146+
npm run lint
147+
```
148+
149+
### Testing
150+
151+
```bash
152+
# Run all tests
153+
npm run test
154+
155+
# JavaScript unit tests
156+
npm run test:js
157+
158+
# End-to-end tests
159+
npm run test:e2e
160+
161+
# PHP tests
162+
npm run test:php
163+
```
164+
165+
### Internationalization
166+
167+
```bash
168+
# Generate .pot file for translations
169+
npm run makepot
170+
171+
# Generate JSON translations for JavaScript
172+
npm run make-json
173+
```
174+
175+
## Development Flow
176+
177+
```mermaid
178+
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1e4d78', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#15354f', 'lineColor': '#333333', 'secondaryColor': '#f0f0f0', 'tertiaryColor': '#e8e8e8', 'background': '#ffffff', 'mainBkg': '#1e4d78', 'textColor': '#333333', 'nodeBorder': '#15354f', 'clusterBkg': '#f8f9fa', 'clusterBorder': '#dee2e6', 'titleColor': '#333333'}}}%%
179+
sequenceDiagram
180+
participant Dev as Developer
181+
participant Files as Source Files
182+
participant Build as Build System
183+
participant Tests as Tests
184+
participant WP as WordPress
185+
186+
Dev->>Files: Edit src/ files
187+
Files->>Build: npm run start (watch mode)
188+
Build->>Build: Compile & Bundle
189+
Build->>WP: Output to build/
190+
Dev->>Tests: npm run test
191+
Tests->>Dev: Test results
192+
Dev->>Build: npm run build (production)
193+
Build->>WP: Optimized build/
194+
WP->>Dev: Theme ready
195+
```
196+
197+
## Build System Architecture
198+
199+
```mermaid
200+
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1e4d78', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#15354f', 'lineColor': '#333333', 'secondaryColor': '#f0f0f0', 'tertiaryColor': '#e8e8e8', 'background': '#ffffff', 'mainBkg': '#1e4d78', 'textColor': '#333333', 'nodeBorder': '#15354f', 'clusterBkg': '#f8f9fa', 'clusterBorder': '#dee2e6', 'titleColor': '#333333'}}}%%
201+
flowchart TB
202+
subgraph Source["Source Files (src/)"]
203+
JS["JavaScript<br/>.js"]
204+
CSS["Stylesheets<br/>.scss"]
205+
Assets["Assets<br/>images, fonts"]
206+
end
207+
208+
subgraph Build["Build Process"]
209+
Babel["Babel<br/>ES6+ → ES5"]
210+
Webpack["Webpack<br/>Bundle"]
211+
Sass["Sass<br/>SCSS → CSS"]
212+
PostCSS["PostCSS<br/>Optimize"]
213+
end
214+
215+
subgraph Output["Build Output (build/)"]
216+
JSOut["theme.js<br/>editor.js"]
217+
CSSOut["style.css<br/>editor.css"]
218+
AssetOut["Optimized Assets"]
219+
end
220+
221+
JS --> Babel
222+
Babel --> Webpack
223+
CSS --> Sass
224+
Sass --> PostCSS
225+
Assets --> Webpack
226+
Webpack --> JSOut
227+
PostCSS --> CSSOut
228+
Webpack --> AssetOut
229+
```
230+
231+
## Theme Architecture
232+
233+
```mermaid
234+
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1e4d78', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#15354f', 'lineColor': '#333333', 'secondaryColor': '#f0f0f0', 'tertiaryColor': '#e8e8e8', 'background': '#ffffff', 'mainBkg': '#1e4d78', 'textColor': '#333333', 'nodeBorder': '#15354f', 'clusterBkg': '#f8f9fa', 'clusterBorder': '#dee2e6', 'titleColor': '#333333'}}}%%
235+
flowchart TB
236+
subgraph Core["Core Files"]
237+
ThemeJSON["theme.json<br/>Theme Configuration"]
238+
Functions["functions.php<br/>Theme Setup"]
239+
StyleCSS["style.css<br/>Theme Header"]
240+
end
241+
242+
subgraph Templates["Templates"]
243+
TemplateFiles["templates/<br/>index.html, etc."]
244+
Parts["parts/<br/>header.html, footer.html"]
245+
Patterns["patterns/<br/>Block Patterns"]
246+
end
247+
248+
subgraph Assets["Compiled Assets"]
249+
BuildCSS["build/css/<br/>Stylesheets"]
250+
BuildJS["build/js/<br/>JavaScript"]
251+
BuildAssets["build/<br/>Images, Fonts"]
252+
end
253+
254+
subgraph PHP["PHP Files"]
255+
Inc["inc/<br/>Theme Functions"]
256+
BlockPatterns["inc/block-patterns.php"]
257+
BlockStyles["inc/block-styles.php"]
258+
end
259+
260+
ThemeJSON --> TemplateFiles
261+
Functions --> Inc
262+
Inc --> BlockPatterns
263+
Inc --> BlockStyles
264+
TemplateFiles --> Parts
265+
Parts --> Patterns
266+
BuildCSS --> TemplateFiles
267+
BuildJS --> TemplateFiles
268+
```
269+
270+
## Prerequisites
271+
272+
- **Node.js**: 18.0+ and npm 9.0+
273+
- **PHP**: 8.0+
274+
- **WordPress**: 6.4+
275+
- **Composer**: 2.0+ (for PHP dependencies)
276+
277+
## Support Resources
278+
279+
### Official WordPress Documentation
280+
281+
- [Block Theme Handbook](https://developer.wordpress.org/themes/block-themes/)
282+
- [Block Editor Handbook](https://developer.wordpress.org/block-editor/)
283+
- [Theme Developer Handbook](https://developer.wordpress.org/themes/)
284+
- [@wordpress/scripts Documentation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)
285+
286+
### WordPress Packages
287+
288+
- [@wordpress/scripts](https://www.npmjs.com/package/@wordpress/scripts)
289+
- [@wordpress/eslint-plugin](https://www.npmjs.com/package/@wordpress/eslint-plugin)
290+
- [@wordpress/stylelint-config](https://www.npmjs.com/package/@wordpress/stylelint-config)
291+
292+
## Contributing
293+
294+
When contributing to this scaffold:
295+
296+
1. Follow WordPress coding standards
297+
2. Update relevant documentation
298+
3. Test with the generation script
299+
4. Ensure all linters pass
300+
5. Update version numbers appropriately
301+
302+
## License
303+
304+
This scaffold is licensed under {{license}}. Generated themes inherit this license unless modified.
305+
306+
## Related Documentation
307+
308+
- [Main README](../README.md) - Repository root documentation
309+
- [Source Directory](../src/README.md) - Source files documentation
310+
- [Tests Directory](../tests/README.md) - Testing documentation
311+
- [Build Scripts](../bin/README.md) - Build script documentation

0 commit comments

Comments
 (0)