{"id":21813086,"url":"https://github.com/webdevstudios/wds-bt","last_synced_at":"2025-07-25T06:37:11.278Z","repository":{"id":242145449,"uuid":"763766271","full_name":"WebDevStudios/wds-bt","owner":"WebDevStudios","description":"A starter block theme from WebDevStudios.","archived":false,"fork":false,"pushed_at":"2025-03-25T16:13:41.000Z","size":7348,"stargazers_count":67,"open_issues_count":0,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-02T10:44:46.104Z","etag":null,"topics":["block-editor","block-theme","full-site-editing","scss","starter-theme","wordpress","wordpress-theme"],"latest_commit_sha":null,"homepage":"https://wdsbt.wdslab.com/","language":"SCSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WebDevStudios.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-26T22:03:44.000Z","updated_at":"2025-04-02T10:25:38.000Z","dependencies_parsed_at":"2024-07-08T21:25:12.441Z","dependency_job_id":"90e0b847-3486-4690-98ab-d15a966911d2","html_url":"https://github.com/WebDevStudios/wds-bt","commit_stats":{"total_commits":631,"total_committers":10,"mean_commits":63.1,"dds":0.4928684627575277,"last_synced_commit":"c6db2ea4e4b93d2c9b048f66466a0e4d9af129fb"},"previous_names":["webdevstudios/wds-bt"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebDevStudios%2Fwds-bt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebDevStudios%2Fwds-bt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebDevStudios%2Fwds-bt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebDevStudios%2Fwds-bt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebDevStudios","download_url":"https://codeload.github.com/WebDevStudios/wds-bt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248045231,"owners_count":21038553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["block-editor","block-theme","full-site-editing","scss","starter-theme","wordpress","wordpress-theme"],"created_at":"2024-11-27T14:27:09.517Z","updated_at":"2025-07-25T06:37:11.259Z","avatar_url":"https://github.com/WebDevStudios.png","language":"SCSS","readme":"# WDS BT\n\n## Version: 1.3.5\n\n[![WebDevStudios. Your Success is Our Mission.](https://webdevstudios.com/wp-content/uploads/2024/02/wds-banner.png)](https://webdevstudios.com/contact/)\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Code Quality](https://github.com/WebDevStudios/wds-bt/actions/workflows/assertions.yml/badge.svg)](https://github.com/WebDevStudios/wds-bt/actions/workflows/assertions.yml)\n[![Security](https://github.com/WebDevStudios/wds-bt/actions/workflows/security.yml/badge.svg)](https://github.com/WebDevStudios/wds-bt/actions/workflows/security.yml)\n\n\u003cdetails\u003e\n \u003csummary\u003e\u003cb\u003eTable of Contents\u003c/b\u003e\u003c/summary\u003e\n \u003ca name=\"back-to-top\"\u003e\u003c/a\u003e\n\n- [WDS BT](#wds-bt)\n  - [Overview](#overview)\n  - [Requirements](#requirements)\n  - [Getting Started](#getting-started)\n  - [Development](#development)\n    - [Theme Structure](#theme-structure)\n    - [Setup](#setup)\n    - [NPM Scripts](#npm-scripts)\n  - [Font Management](#font-management)\n    - [Font Organization](#font-organization)\n    - [Font Tools](#font-tools)\n    - [Font Workflow](#font-workflow)\n  - [Creating Blocks](#creating-blocks)\n  - [Customizations](#customizations)\n    - [Registering Block Styles](#registering-block-styles)\n    - [Overriding/Customizing Core Block Styles](#overridingcustomizing-core-block-styles)\n    - [Overriding/Customizing Third Party Block Styles](#overridingcustomizing-third-party-block-styles)\n    - [Creating Block Variations](#creating-block-variations)\n    - [Unregister Blocks and Variations](#unregister-blocks-and-variations)\n  - [Stylelint Configuration](#stylelint-configuration)\n    - [Extending WordPress Stylelint Rules](#extending-wordpress-stylelint-rules)\n    - [Running Stylelint](#running-stylelint)\n  - [PHP Linting Configuration](#php-linting-configuration)\n    - [PHP Compatibility](#php-compatibility)\n    - [Running PHP Linting](#running-php-linting)\n  - [JavaScript Linting Configuration](#javascript-linting-configuration)\n    - [ESLint Setup](#eslint-setup)\n    - [Running JavaScript Linting](#running-javascript-linting)\n  - [Dynamic Block Pattern Categories](#dynamic-block-pattern-categories)\n  - [Accessibility, Code Quality, and Security Checks](#accessibility-code-quality-and-security-checks)\n  - [Strict Lefthook Integration](#strict-lefthook-integration)\n  - [Cross-Platform Compatibility](#cross-platform-compatibility)\n  - [Contributing and Support](#contributing-and-support)\n  - [Acknowledgements](#acknowledgements)\n\n\u003c/details\u003e\n\n***\n\n## Overview\n\nWDS BT is a foundational WordPress block theme designed for maximum flexibility and customization. It integrates seamlessly with the native WordPress block editor, providing an intuitive and adaptable user experience. WDS BT is specifically developed as a foundational rather than parent theme, giving developers a clean and versatile base for advanced customizations.\n\n| Feature                                          | Description                                                                                         |\n|--------------------------------------------------|-----------------------------------------------------------------------------------------------------|\n| Native Block Support                             | Built for native WordPress blocks and site editor integration.                                      |\n| Responsive Design                                | Ensures optimal display and functionality across devices.                                           |\n| Foundation Theme                                 | Flexible base theme optimized for extensive customization.                                          |\n| Automated Code Quality                           | Modern linting configurations with PHP 8.3 compatibility, WordPress coding standards, and automated quality checks. |\n| Third-party Block Style Overrides                | Conditionally enqueue and override third-party block styles for efficient asset delivery.           |\n| Accessibility Compliance                         | Built-in WCAG 2.2 compliance with automated Pa11y checks.                                           |\n| Enhanced Webpack Configuration                   | Refined Webpack setup for improved dependency resolution and optimized asset management.            |\n| Block Creation Script Enhancements               | Options for static, dynamic, or interactive blocks; automatically includes `view.js` for rendering. |\n| LeftHook Integration                             | Required for pre-commit hooks and automated code quality checks.                                           |\n\n## Requirements\n\n- WordPress 6.4+\n- PHP 8.2+ (fully tested with PHP 8.3)\n- [NPM](https://npmjs.com) (v10+)\n- [Node](https://nodejs.org) (v20+)\n- [Composer 2+](https://getcomposer.org/)\n- License: [GPLv3](https://www.gnu.org/licenses/gpl-3.0.html)\n\n## Getting Started\n\n1. Clone this repository to your WordPress theme directory (`wp-content/themes/`).\n2. Activate WDS BT from your WordPress admin panel under Appearance \u003e Themes.\n3. Run `npm run setup` to install dependencies and perform an initial build.\n\n## Development\n\n[🔝 Back to Top](#wds-bt)\n\n\u003cdetails closed\u003e\n  \u003csummary\u003e\u003cb\u003eTheme Structure\u003c/b\u003e\u003c/summary\u003e\n \u003cpre\u003e\n  \u003ccode\u003e\n└── 📁wds-bt\n └── 📁assets\n  └── 📁fonts\n  └── 📁images\n   └── 📁icons\n  └── index.js\n  └── 📁js\n   └── 📁block-filters\n    └── buttons.js\n    └── index.js\n   └── 📁block-variations\n    └── index.js\n   └── editor.js\n   └── 📁global\n    └── header.js\n    └── index.js\n    └── table.js\n   └── index.js\n   └── 📁templates\n    └── index.js\n  └── 📁scss\n   └── _index.scss\n   └── 📁abstracts\n    └── _index.scss\n    └── mobile-only-mixins.scss\n    └── responsive-mixins.scss\n    └── utility.scss\n   └── 📁base\n    └── _index.scss\n    └── forms.scss\n    └── global.scss\n    └── pagination.scss\n   └── 📁blocks\n    └── 📁core\n    └── 📁third-party\n   └── editor.scss\n   └── 📁patterns\n    └── _index.scss\n   └── 📁template-parts\n    └── _index.scss\n    └── footer.scss\n    └── header.scss\n   └── 📁templates\n    └── _index.scss\n    └── 404.scss\n    └── archive.scss\n    └── search.scss\n └── 📁inc\n  └── 📁block-template\n   └── 📁block\n    └── edit.js.mustache\n    └── editor.scss.mustache\n    └── index.js.mustache\n    └── render.php.mustache\n    └── style.scss.mustache\n    └── view.js.mustache\n   └── index.js\n   └── 📁plugin\n    └── .editorconfig.mustache\n    └── .eslintrc.mustache\n    └── .gitignore.mustache\n    └── $slug.php.mustache\n    └── readme.txt.mustache\n   └── README.md\n  └── 📁functions\n   └── back-to-top.php\n   └── custom-logo-svg.php\n   └── security.php\n  └── 📁hooks\n   └── enqueue-block-stylesheet.php\n   └── enqueue-third-party-block-stylesheet.php\n   └── register-block-categories.php\n   └── register-block-filters.php\n   └── register-block-pattern-categories.php\n   └── register-block-patterns.php\n   └── register-block-styles.php\n   └── register-block-variations.php\n   └── restrict-block-patterns.php\n  └── 📁setup\n   └── scripts.php\n   └── setup.php\n   └── style-script-version.php\n └── 📁pa11y-ci-report\n └── 📁parts\n  └── comments.html\n  └── footer.html\n  └── header.html\n  └── post-meta.html\n └── 📁patterns\n  └── comments.php\n  └── footer-default.php\n  └── header-default.php\n  └── post-hero.php\n  └── primary-category.php\n └── 📁styles\n  └── dark.json\n └── 📁templates\n  └── 404.html\n  └── archive.html\n  └── index.html\n  └── page-blank.html\n  └── page-no-title.html\n  └── page.html\n  └── search.html\n  └── single.html\n └── .editorconfig\n └── .env\n └── .eslintignore\n └── .eslintrc.js\n └── .gitignore\n └── .markdownlintignore\n └── .nvmrc\n └── .prettierignore\n └── .prettierrc.js\n └── .stylelintignore\n └── .stylelintrc.json\n └── a11y.cjs\n └── babel.config.json\n └── composer.json\n └── composer.lock\n └── CONTRIBUTING.md\n └── functions.php\n └── lefthook.yml\n └── LICENSE.md\n └── package-lock.json\n └── package.json\n └── phpcs.xml.dist\n └── postcss.config.js\n └── README.md\n └── readme.txt\n └── screenshot.png\n └── style.css\n └── theme.json\n └── updateVersion.js\n └── webpack.config.js\n  \u003c/code\u003e\n \u003c/pre\u003e\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eSetup\u003c/b\u003e\u003c/summary\u003e\n\nFrom the command line, change directories to your new theme directory:\n\n```bash\ncd /wp-content/themes/your-theme\n```\n\nThe command below will remove `node_modules`, `vendor`, `build`, `package-lock.json`, and `composer.lock` files. Install theme dependencies and trigger an initial build.\n\n\u003eNote: You will need to have Composer 2 and NPM 10 installed first.\n\n```bash\nnpm run setup\n```\n\n\u003c/details\u003e\n\n## NPM Scripts\n\n[🔝 Back to Top](#wds-bt)\n\n*From the command line, type any of the following to perform an action:*\n\n|     | Command                     | Description                                             |\n|-----|-----------------------------|-------------------------------------------------------- |\n| 🌐   | `npm run a11y`              | Run accessibility tests (Pa11y-CI).                     |\n| 🛠️  | `npm run build`             | Build the theme assets.                                 |\n| 🔨  | `npm run create-block`      | Scaffold a new block with various configurations.       |\n| 📝  | `npm run format`            | Format all code files (JS, SCSS, PHP).                  |\n| 🎨  | `npm run format:css`        | Format SCSS files.                                      |\n| 🐘  | `npm run format:php`        | Format PHP files.                                       |\n| 🔤  | `npm run fonts`             | Process fonts and update theme.json.                    |\n| 🔍  | `npm run fonts:detect`      | Detect and list all available fonts.                    |\n| 🔧  | `npm run fonts:generate`    | Generate theme.json with detected fonts.                |\n| 🔍  | `npm run lint`              | Run all linting scripts.                                |\n| 🎨  | `npm run lint:css`          | Lint CSS files.                                         |\n| 🚀  | `npm run lint:js`           | Lint JavaScript files.                                  |\n| 🐘  | `npm run lint:php`          | Lint PHP files.                                         |\n| 🔄  | `npm run packages-update`   | Update dependencies defined in `package.json`.          |\n| 🛠️  | `npm run setup`             | Reset, install dependencies, and build the theme.       |\n| ▶️  | `npm run start`             | Start the development server.                           |\n| 🔖  | `npm run version-update`    | Update the theme version based on environment variable. |\n\n## Font Management\n\n[🔝 Back to Top](#wds-bt)\n\nWDS BT includes an automated font management system that organizes fonts by purpose and automatically generates the necessary files for optimal font loading and WordPress integration.\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eFont Organization\u003c/b\u003e\u003c/summary\u003e\n\nFonts are organized by their purpose/role for easy swapping and management:\n\n```\nassets/fonts/\n├── headline/\n│   ├── Inter.woff2\n│   └── Poppins-Bold.woff2\n├── body/\n│   ├── Oxygen-Regular.woff2\n│   └── OpenSans-Regular.woff2\n└── mono/\n    └── RobotoMono-Regular.woff2\n```\n\n**Benefits:**\n\n- **Easy font swapping**: Just replace files in each folder\n- **Clear purpose**: Each folder has a specific role\n- **Standardized slugs**: Automatically generates `headline`, `body`, `mono` slugs in theme.json\n- **Consistent paths**: CSS custom properties always use the same slugs\n\n**How it works:**\n\n1. Place fonts in the appropriate purpose folder (`headline/`, `body/`, `mono/`)\n2. The processor detects the purpose from the folder name\n3. Maps to standardized slugs in theme.json\n4. Generates correct CSS custom properties: `var(--wp--preset--font-family--headline)`, `var(--wp--preset--font-family--body)`, `var(--wp--preset--font-family--mono)`\n\n**To change fonts:**\n\n- **Headlines**: Replace files in `headline/` folder\n- **Body text**: Replace files in `body/` folder\n- **Code/mono**: Replace files in `mono/` folder\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eFont Tools\u003c/b\u003e\u003c/summary\u003e\n\n### Font Processor (`npm run fonts`)\n\nThe main font processing tool that:\n\n- Scans `assets/fonts/` for font files\n- Copies fonts to `build/fonts/` maintaining folder structure\n- Generates preload links in `inc/setup/font-preload.php`\n- Updates `theme.json` with detected font families\n\n**Usage:**\n\n```bash\nnpm run fonts\n# or\nphp tools/font-processor.php\n```\n\n### Font Detection (`npm run fonts:detect`)\n\nLists all available fonts in your theme for debugging and inspection.\n\n**Usage:**\n\n```bash\nnpm run fonts:detect\n# or\nphp tools/font-detection.php\n```\n\n**Output:**\n\n- Lists all fonts found in `assets/fonts/` and `build/fonts/`\n- Shows font family, weight, and style information\n- Helps identify what fonts are available\n\n### Font Generator (`npm run fonts:generate`)\n\nAdvanced font processing with optimization and subsetting capabilities.\n\n**Usage:**\n\n```bash\nnpm run fonts:generate\n# or\nphp tools/font-generator.php\n```\n\n**Features:**\n\n- Font subsetting for smaller file sizes\n- Multiple format generation (WOFF2, WOFF)\n- CSS generation with @font-face declarations\n- Preload link generation\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eFont Workflow\u003c/b\u003e\u003c/summary\u003e\n\n### Adding New Fonts\n\n1. **Organize by purpose**: Place font files in the appropriate folder:\n   - `assets/fonts/headline/` for heading fonts\n   - `assets/fonts/body/` for body text fonts\n   - `assets/fonts/mono/` for monospace/code fonts\n\n2. **Run the font processor**:\n\n   ```bash\n   npm run fonts\n   ```\n\n3. **Verify the results**:\n   - Check `build/fonts/` for copied fonts\n   - Check `inc/setup/font-preload.php` for preload links\n   - Check `theme.json` for font family definitions\n\n### Using Fonts in Your Theme\n\nFonts are automatically available as CSS custom properties:\n\n```scss\n.heading {\n  font-family: var(--wp--preset--font-family--headline);\n}\n\n.body-text {\n  font-family: var(--wp--preset--font-family--body);\n}\n\n.code {\n  font-family: var(--wp--preset--font-family--mono);\n}\n```\n\n### Font File Naming\n\nThe system automatically detects font properties from filenames:\n\n- **Family detection**: From folder name or filename patterns\n- **Weight detection**: From filename patterns (e.g., `-300`, `-bold`, `-700`)\n- **Style detection**: From filename patterns (e.g., `-italic`, `-oblique`)\n\n**Supported patterns:**\n\n- Weights: `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`\n- Styles: `normal`, `italic`, `oblique`\n- Families: `Inter`, `Oxygen`, `Roboto Mono`, `Open Sans`, `Lato`, `Poppins`, etc.\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eFont Debugging\u003c/b\u003e\u003c/summary\u003e\n\n### Debug Information\n\nWhen `WP_DEBUG` is enabled, font detection debug information is displayed in the WordPress admin on the WDSBT Settings page.\n\n**To enable debug:**\n\n1. Set `WP_DEBUG = true` in your `wp-config.php`\n2. Visit the WDSBT Settings page in WordPress admin\n3. Look for the \"Font Detection Debug\" notice\n\n**Debug information includes:**\n\n- Number of fonts found in build and assets directories\n- List of detected font families with variant counts\n- Individual font variant details (weight, style, file path)\n\n### Troubleshooting\n\n**Fonts not appearing in theme.json:**\n\n1. Check that fonts are in the correct folders (`headline/`, `body/`, `mono/`)\n2. Verify font file extensions are supported (`.woff2`, `.woff`, `.ttf`, `.otf`)\n3. Run `npm run fonts:detect` to see what fonts are detected\n4. Check for any error messages in the font processor output\n\n**Preload links not working:**\n\n1. Ensure `inc/setup/font-preload.php` exists and is properly generated\n2. Check that the file is being included in your theme\n3. Verify the font paths in the preload links are correct\n\n**CSS custom properties not available:**\n\n1. Check that `theme.json` contains the font family definitions\n2. Verify the font slugs are correct (`headline`, `body`, `mono`)\n3. Ensure WordPress is generating the CSS custom properties\n\n\u003c/details\u003e\n\n## Version Management\n\n[🔝 Back to Top](#wds-bt)\n\nThe theme includes an automated version update system that ensures consistency across all files that reference the theme version.\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eHow to Update the Theme Version\u003c/b\u003e\u003c/summary\u003e\n\n**Method 1**: Using the .env file (Recommended)\n\n1. **Update the `.env` file** with the new version:\n\n   ```bash\n   echo \"VERSION=1.4.0\" \u003e .env\n   ```\n\n2. **Run the version update script**:\n\n   ```bash\n   npm run version-update\n   ```\n\n**Method 2**: Using environment variable directly\n\n```bash\nVERSION=1.4.0 npm run version-update\n```\n\n**Method 3**: Using dotenv-cli (if installed globally)\n\n```bash\nnpx dotenv -e .env -- npm run version-update\n```\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eWhat Gets Updated\u003c/b\u003e\u003c/summary\u003e\n\nThe version update script automatically updates the version in:\n\n- `style.css` (theme header)\n- `package.json` (NPM package version)\n- `composer.json` (Composer package version)\n- `README.md` (documentation version)\n\n#### Complete Workflow Example\n\n```bash\n# 1. Set the new version in .env file\necho \"VERSION=1.4.0\" \u003e .env\n\n# 2. Run the version update script\nnpm run version-update\n\n# 3. Verify the changes\ngit diff\n\n# 4. Commit the version bump\ngit add .\ngit commit -m \"WDSBT-XXX - bump version to 1.4.0\"\n\n# 5. Tag the release (optional)\ngit tag -a v1.4.0 -m \"Release version 1.4.0\"\ngit push origin v1.4.0\n```\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eRelease Types and Workflows\u003c/b\u003e\u003c/summary\u003e\n\n**Patch Release (Bug Fixes)**\nFor small bug fixes and minor updates (e.g., 1.4.0 → 1.4.1):\n\n```bash\n# 1. Create a patch branch\ngit checkout -b patch/1.4.1\n\n# 2. Make your bug fixes\n# ... make changes ...\n\n# 3. Update version to patch\necho \"VERSION=1.4.1\" \u003e .env\nnpm run version-update\n\n# 4. Commit changes\ngit add .\ngit commit -m \"WDSBT-XXX - fix [specific issue]\"\n\n# 5. Commit version bump\ngit add .\ngit commit -m \"WDSBT-XXX - bump version to 1.4.1\"\n\n# 6. Create pull request\ngit push origin patch/1.4.1\n# ... create PR and merge ...\n\n# 7. Tag the release\ngit checkout main\ngit pull origin main\ngit tag -a v1.4.1 -m \"Patch release 1.4.1 - [brief description]\"\ngit push origin v1.4.1\n```\n\n**Minor Release (New Features)**\nFor new features and enhancements (e.g., 1.4.0 → 1.5.0):\n\n```bash\n# 1. Create a feature branch\ngit checkout -b feature/1.5.0\n\n# 2. Add new features\n# ... implement features ...\n\n# 3. Update version to minor\necho \"VERSION=1.5.0\" \u003e .env\nnpm run version-update\n\n# 4. Update CHANGELOG.md (if maintained)\n# ... document new features ...\n\n# 5. Commit changes\ngit add .\ngit commit -m \"WDSBT-XXX - add [new feature]\"\n\n# 6. Commit version bump\ngit add .\ngit commit -m \"WDSBT-XXX - bump version to 1.5.0\"\n\n# 7. Create pull request and tag release\n# ... same as patch workflow ...\n```\n\n**Major Release (Breaking Changes)**\nFor major updates with breaking changes (e.g., 1.4.0 → 2.0.0):\n\n```bash\n# 1. Create a major release branch\ngit checkout -b release/2.0.0\n\n# 2. Implement breaking changes\n# ... make breaking changes ...\n\n# 3. Update version to major\necho \"VERSION=2.0.0\" \u003e .env\nnpm run version-update\n\n# 4. Update documentation for breaking changes\n# ... update README, CHANGELOG, etc. ...\n\n# 5. Test thoroughly\nnpm run build\nnpm run lint\nnpm run a11y\n\n# 6. Commit changes\ngit add .\ngit commit -m \"WDSBT-XXX - breaking: [description of breaking changes]\"\n\n# 7. Commit version bump\ngit add .\ngit commit -m \"WDSBT-XXX - bump version to 2.0.0\"\n\n# 8. Create pull request and tag release\n# ... same as patch workflow ...\n```\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eAutomated Patch Workflow\u003c/b\u003e\u003c/summary\u003e\n\nFor quick patches, you can use a streamlined workflow:\n\n```bash\n# Quick patch workflow\ngit checkout -b hotfix/1.4.1\n# ... make quick fix ...\necho \"VERSION=1.4.1\" \u003e .env \u0026\u0026 npm run version-update\ngit add . \u0026\u0026 git commit -m \"WDSBT-XXX - hotfix: [issue description]\"\ngit push origin hotfix/1.4.1\n# ... create PR, merge, tag ...\n```\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003ePre-release Versions\u003c/b\u003e\u003c/summary\u003e\n\nFor beta, alpha, or release candidate versions:\n\n```bash\n# Beta release\necho \"VERSION=1.4.0-beta.1\" \u003e .env\nnpm run version-update\n\n# Alpha release\necho \"VERSION=1.4.0-alpha.1\" \u003e .env\nnpm run version-update\n\n# Release candidate\necho \"VERSION=1.4.0-rc.1\" \u003e .env\nnpm run version-update\n```\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eTroubleshooting\u003c/b\u003e\u003c/summary\u003e\n\n**Version not updating in all files:**\n\n1. Check that the `.env` file exists and contains the `VERSION` variable\n2. Ensure the version format is correct (e.g., `1.4.0`, not `v1.4.0`)\n3. Run `npm run version-update` with verbose output to see any errors\n\n**Permission errors:**\n\n1. Ensure you have write permissions to all theme files\n2. Check that no files are locked by other processes\n\n**Script not found:**\n\n1. Verify that `updateVersion.js` exists in the theme root\n2. Ensure Node.js is installed and accessible\n3. Run `npm install` to ensure all dependencies are installed\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eVersion Update Process Details\u003c/b\u003e\u003c/summary\u003e\n\nThe version update script (`updateVersion.js`) reads the `VERSION` environment variable from the `.env` file and updates all version references across the project. This ensures consistency across all files that reference the theme version.\n\n**How it works:**\n\n1. Reads the `VERSION` environment variable\n2. Scans specific files for version patterns\n3. Updates version references while preserving formatting\n4. Provides feedback on what was updated\n\n**Supported version formats:**\n\n- Semantic versioning: `1.4.0`, `2.0.0`, `1.4.0-beta.1`\n- WordPress version format: `1.4.0`\n\n**Files processed:**\n\n- `style.css` - WordPress theme header\n- `package.json` - NPM package metadata\n- `composer.json` - Composer package metadata\n- `README.md` - Documentation version references\n\n\u003c/details\u003e\n\n## Creating Blocks\n\n[🔝 Back to Top](#wds-bt)\n\n1. Run the Block Creation Script\n   Navigate to your project root in the terminal and run the following command to create a new block:\n\n```bash\nnpm run create-block\n```\n\nFollow the prompts to configure your new block. The script will scaffold a new block structure inside assets/blocks/.\n\n2. Build your block\n   After editing and configuring your block, build your project to compile assets using webpack:\n\n```bash\nnpm run build\n```\n\nThis will process JavaScript, SCSS, optimize images, and generate necessary files for each custom block in the `./blocks` directory.\n\n## Customizations\n\n[🔝 Back to Top](#wds-bt)\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eRegistering Block Styles\u003c/b\u003e\u003c/summary\u003e\n\n1. Open the `inc/hooks/register-block-styles.php` file in your theme directory.\n\n2. Add a new block style entry with the following mandatory properties:\n\n- **Name:** The identifier used to compute a CSS class for the style.\n\n- **Label:** A human-readable label for the style.\n\n Example:\n\n ```php\n 'block_name' =\u003e array(\n  'name' =\u003e __( 'label', 'wdsbt' ),\n ),\n ```\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eOverriding/Customizing Core Block Styles\u003c/b\u003e\u003c/summary\u003e\n\n1. Navigate to the `assets/scss/blocks/core` directory within your theme.\n\n2. Create an SCSS file with the exact filename as the block name you want to customize. This file will house your custom styles for that specific block.\n\n3. Files within the `assets/scss/blocks/core/` directory are automatically enqueued, simplifying the integration of your custom styles into the WordPress block editor. Do not import these files into the main `index.scss`\n\n4. After adding your custom SCSS file, run the following command to compile and apply your changes:\n\n ```bash\n npm run build\n ```\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eOverriding/Customizing Third Party Block Styles\u003c/b\u003e\u003c/summary\u003e\n\n1. **Place Your Override SCSS Files**: Add your third‑party override SCSS files in `assets/scss/blocks/third-party/`.\n   - **Naming Convention:** Name each file using the block's slug (the part after the namespace). For example, to override the `wdsbt/test` block, name the file `test.scss`.\n\n2. **Third-Party Block Styles**: Files within the `assets/scss/blocks/third-party/` directory are automatically enqueued. Do not import these files into your main `index.scss`.\n\n3. **Compile Your Changes**: After adding or updating your custom SCSS file, run the following command to compile and apply your changes:\n\n ```bash\n npm run build\n ```\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eCreating Block Variations\u003c/b\u003e\u003c/summary\u003e\n\n1. In the `assets/js/block-variations` directory within your theme, create a new JavaScript file. This file will contain the definition of your block variation.\n\n2. Import the newly created file into the `assets/js/block-variations/index.js` file. This step ensures that your variation is included in the build process.\n\n3. Use the `wp.blocks.registerBlockVariation()` function to officially register your block variation. This function takes the name of the original block and an object defining the variation.\n\n Example:\n\n ```javascript\n // In your variations JavaScript file\n wp.blocks.registerBlockVariation('core/paragraph', {\n  name: 'custom-variation',\n  title: __('Custom Variation', 'wdsbt'),\n  attributes: { /* Define your custom attributes here */ },\n  // Add more variation settings as needed\n });\n ```\n\n **Original Block Name**: Provide the name of the original block for which you are creating the variation.\n **Variation Object**: Define the properties of your block variation, including the name, title, attributes, and any additional settings.\n\n\u003e ***NOTE:*** To find the correct block name, open the block editor, launch the browser console and type `wp.blocks.getBlockTypes()`. You will see the complete list of block names (from core or third-party).\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eUnregister Blocks and Variations\u003c/b\u003e\u003c/summary\u003e\n\nThis functionality allows you to unregister and disable specific core Gutenberg blocks, styles, and variations that are not needed on your WordPress website. By removing these unused blocks and variations, you can streamline the Gutenberg editor and improve the overall performance of your site.\n\n#### Implementation\n\nThe script in `assets/js/editor.js` loops through a list of unused blocks and variations, unregistering them from the Gutenberg editor. Additionally, it keeps only the specified embed variations for the core/embed block.\n\n\u003cb\u003eExample\u003c/b\u003e\n\n```javascript\n// List of Gutenberg blocks to unregister\nconst unusedBlocks = [\n 'core/file',\n 'core/latest-comments',\n 'core/rss',\n // Add more unused blocks as needed\n];\n\n// List of Gutenberg block variations to unregister\nconst unregisterBlockVariations = [\n // Example:\n // {\n //     blockName: 'core/group',\n //     blockVariationName: 'group-stack',\n // },\n];\n\n// Keep only the necessary embed variations\nconst keepEmbeds = [\n 'twitter',\n 'wordpress',\n 'spotify',\n // Add more necessary embed variations as needed.\n];\n```\n\n\u003c/details\u003e\n\n## Mixins\n\n[🔝 Back to Top](#wds-bt)\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eResponsive Mixins\u003c/b\u003e\u003c/summary\u003e\n\nThis SCSS file `assets/scss/abstracts/responsive-mixins.scss` provides mixins for creating responsive media queries with both minimum and maximum width conditions. The file promotes modular and maintainable styling by allowing the easy application of responsive styles based on screen width.\n\nTo use the responsive mixin, include it in your SCSS code and customize it according to your project's breakpoints. Here's an example:\n\n```scss\n// Usage examples\n.my-element {\n  width: 100%;\n\n  // Apply styles when the screen width is 600px or more\n  @include responsive-mixins.responsive-min(600px) {\n /* Your responsive styles for min-width: 600px */\n  }\n\n  // Apply styles when the screen width is up to 600px\n  @include responsive-mixins.responsive-max(600px) {\n /* Your responsive styles for max-width: 600px */\n  }\n\n  // Apply styles when the screen width is between 600px and 1200px\n  @include responsive-mixins.responsive-range(600px, 1200px) {\n /* Your responsive styles for a range of widths */\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eMobile Only Mixins\u003c/b\u003e\u003c/summary\u003e\n\nThis SCSS file `assets/scss/abstracts/_mobile-only-mixins.scss` contains a mixin called `mobile-only` designed to visually hide elements for accessibility (a11y) while making them visible on mobile devices.\n\nInclude the `mobile-only` mixin in your SCSS file where you want to hide elements on desktop but make them visible on mobile:\n\n```scss\n// Example usage:\n.my-element {\n  @include mobile-only-mixins.mobile-only;\n}\n```\n\n\u003c/details\u003e\n\n## Stylelint Configuration\n\n[🔝 Back to Top](#wds-bt)\n\nThis theme uses a modern `stylelint.config.js` configuration that extends the [WordPress Stylelint Config](https://www.npmjs.com/package/@wordpress/stylelint-config) with additional custom rules to maintain code consistency and enforce best practices.\n\n### Extending WordPress Stylelint Rules\n\nThe configuration extends the base WordPress stylelint ruleset, ensuring that all SCSS follows the WordPress coding standards while incorporating additional theme-specific preferences and PHP 8.3 compatibility.\n\n### Running Stylelint\n\nTo check your SCSS files for linting errors, run:\n\n```bash\nnpm run lint:css\n```\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eCustom Rules\u003c/b\u003e\u003c/summary\u003e\n\n- **`declaration-no-important: true`**\n  Prohibits the use of `!important` to maintain specificity control.\n\n- **`no-descending-specificity: null`**\n  Allows selectors with descending specificity to prevent conflicts with deeply nested components.\n\n- **`selector-class-pattern: null`**\n  Disables restrictions on class naming conventions to support custom project structures.\n\n- **`at-rule-no-unknown`**\n  Allows SCSS directives and WordPress-specific at-rules:\n  - `apply`, `layer`, `variants`, `responsive`, `screen`\n  - `use`, `include`, `each`, `if`, `else`, `for`, `while`\n  - `function`, `return`, `mixin`, `content`, `extend`\n  - `warn`, `error`, `debug`\n\n- **`declaration-property-unit-allowed-list`**\n  Restricts certain CSS properties to specific units:\n  - `font-size`: `em`, `rem`\n  - `line-height`: No units (unitless for better scaling)\n  - `border`: Only `px` allowed\n  - `margin`: `em`, `rem`\n  - `padding`: `em`, `rem`\n\n- **`no-invalid-double-slash-comments: null`**\n  Allows SCSS-style double-slash comments (`//`).\n\n- **`comment-no-empty: null`**\n  Allows empty comments for documentation purposes.\n\n\u003c/details\u003e\n\n## PHP Linting Configuration\n\n[🔝 Back to Top](#wds-bt)\n\nThis theme uses PHP_CodeSniffer with WordPress coding standards and PHP 8.3 compatibility checks.\n\n### PHP Compatibility\n\n- **PHP Version**: Fully tested with PHP 8.2+ and PHP 8.3\n- **WordPress Standards**: Follows WordPress-Extra and WordPress-Docs coding standards\n- **Compatibility**: Uses PHPCompatibilityWP for version-specific checks\n\n### Running PHP Linting\n\nTo check your PHP files for coding standard violations, run:\n\n```bash\nnpm run lint:php\n```\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003ePHP Configuration\u003c/b\u003e\u003c/summary\u003e\n\n- **Configuration File**: `phpcs.xml.dist`\n- **Test Version**: PHP 8.2-8.3 compatibility\n- **Standards**: WordPress-Extra, WordPress-Docs\n- **Custom Rules**:\n  - Allows array short syntax\n  - Allows short prefixes for theme-specific functions\n  - Excludes deprecated sniffs for compatibility\n  - Theme-specific prefix validation: `WebDevStudios\\wdsbt`, `wds`, `wdsbt`\n  - Text domain validation: `wdsbt`\n\n\u003c/details\u003e\n\n## JavaScript Linting Configuration\n\n[🔝 Back to Top](#wds-bt)\n\nThis theme uses ESLint with WordPress coding standards for JavaScript files.\n\n### ESLint Setup\n\n- **Configuration**: Uses `.eslintrc.json` format for WordPress compatibility\n- **Standards**: WordPress ESLint plugin with recommended rules\n- **Version**: ESLint 8.x for full WordPress tooling compatibility\n\n### Running JavaScript Linting\n\nTo check your JavaScript files for coding standard violations, run:\n\n```bash\nnpm run lint:js\n```\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eJavaScript Configuration\u003c/b\u003e\u003c/summary\u003e\n\n- **Configuration File**: `.eslintrc.json`\n- **Standards**: WordPress ESLint plugin recommended rules\n- **Special Handling**: Webpack configuration files use Node.js environment\n- **Compatibility**: Optimized for WordPress block editor development\n\n\u003c/details\u003e\n\n## Dynamic Block Pattern Categories\n\n[🔝 Back to Top](#wds-bt)\n\nThis theme automatically registers block pattern categories based on subfolders in the `patterns/` directory. To add a new pattern category:\n\n1. Create a new subfolder inside `patterns/` (e.g., `patterns/cards/`).\n2. Place your pattern PHP files in that subfolder.\n3. In each pattern file, set the `Categories` header to the folder name (e.g., `Categories: cards`).\n\nThe category will be registered automatically and available in the block editor. No manual code changes are needed to add new pattern categories.\n\n## Accessibility, Code Quality, and Security Checks\n\n[🔝 Back to Top](#wds-bt)\n\nWDS BT integrates automated workflow actions to maintain high standards of code security, quality, and accessibility. Accessibility checks are built into the development process, ensuring that websites developed with WDS BT comply with WCAG 2.2 standards. This proactive approach reflects WDS BT's commitment to inclusivity and usability for all users.\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eAccessibility Test (npm run a11y)\u003c/b\u003e\u003c/summary\u003e\n\n- **Purpose**: To ensure compliance with Web Content Accessibility Guidelines (WCAG).\n- **Running the A11y Test Script**:\n  - Accessibility tests utilize `pa11y-ci`, which can be run using:\n\n  ```bash\n  npm run a11y\n  ```\n\n- **How It Works**:\n  - **URL Prompt**: The script prompts you for a site URL. Leaving it blank defaults to \u003chttps://wdsbt.local\u003e.\n  - **Sitemap Detection**: It checks for a sitemap at `[URL]/wp-sitemap.xml`.\n  - **Running Tests**:\n    - If a sitemap is found, `pa11y-ci` runs on each sub-sitemap.\n    - If no sitemap is found, `pa11y-ci` runs on the main page.\n\n  **Example Output:**\n\n  ```bash\n  $ npm run a11y\n  Please enter the URL to test for accessibility (leave blank to use your local: https://wdsbt.local):\n  \u003e https://example.com\n  Sitemap found at https://example.com/wp-sitemap.xml. Running pa11y-ci on the sitemap...\n  [output from pa11y-ci]\n  ```\n\n  If no sitemap is found:\n\n  ```bash\n  $ npm run a11y\n  Please enter the URL to test for accessibility (leave blank to use your local: https://wdsbt.local):\n  \u003e https://example.com\n  No sitemap found at https://example.com/wp-sitemap.xml. Running pa11y-ci on the main page...\n  [output from pa11y-ci]\n  ```\n\n- **Reporting**: Any accessibility violations are displayed in the console for immediate review.\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eSecurity Check (security.yml)\u003c/b\u003e\u003c/summary\u003e\n\n- **Purpose**: Detect vulnerabilities in dependencies.\n- **Implementation**: Uses `symfonycorp/security-checker-action@v5` for security scans.\n- **Concurrency**: Ensures only one check runs per branch at a time, canceling previous runs.\n- **Execution Conditions**:\n  - Runs unless:\n    - It is a scheduled event (`schedule`), and\n    - The repository owner is \"webdevstudios.\"\n\n\u003c/details\u003e\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eCode Quality Check (assertions.yml)\u003c/b\u003e\u003c/summary\u003e\n\n- **Purpose**: Enforce adherence to WordPress coding standards.\n- **Configuration**: Quality checks run based on `assertions.yml`.\n- **Requirement**: All detected violations must be fixed before commits are accepted.\n- **Report Visibility**: Reports appear in the command-line interface (CLI) during checks.\n\n\u003c/details\u003e\n\n## Strict Lefthook Integration\n\n[🔝 Back to Top](#wds-bt)\n\nWDS-BT enforces strict Lefthook integration with pre-commit, pre-receive, pre-push, and push hooks. These ensure that all automated quality checks (linting, formatting, security, accessibility) are executed before commits and pushes.\n\n- **Pre-Commit Hook**: Runs quality checks before allowing a commit.\n- **Pre-Receive Hook**: Ensures compliance before WDS-BT accepts the push.\n- **Pre-Push Hook**: Runs additional validations before pushing changes to remote.\n- **Push Hook**: Enforces project-wide integrity checks before finalizing a push.\n\nBypassing Lefthook (`--no-verify`) is strictly prohibited, ensuring that all enforced checks are properly executed.\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\u003cb\u003eIntegration Process with LeftHook\u003c/b\u003e\u003c/summary\u003e\n\n1. **Commit Changes**: Modify code as needed.\n2. **Automated Checks on Commit**: LeftHook triggers accessibility and code quality checks automatically.\n3. **Review Reports**: Examine any violations or issues reported.\n4. **Fix Issues**: Resolve identified problems before proceeding.\n5. **Recommit**: Once issues are fixed, recommit changes.\n6. **Passing Commit**: Commits must pass all checks before acceptance.\n7. **Create a Pull Request (PR)**: When creating a PR, checks run on the PR branch.\n8. **Review PR Checks**: Ensure all checks pass before merging.\n\n\u003c/details\u003e\n\n## Cross-Platform Compatibility\n\n[🔝 Back to Top](#wds-bt)\n\nThis project uses [rimraf](https://www.npmjs.com/package/rimraf) in npm scripts instead of `rm -rf` to ensure compatibility across Windows, macOS, and Linux. All contributors can use the provided npm scripts without needing Git Bash or WSL on Windows.\n\nIf you add new scripts that need to remove files or directories, please use `rimraf` instead of `rm -rf`.\n\n## Contributing and Support\n\nYour contributions and [support tickets](https://github.com/WebDevStudios/wds-bt/issues) are welcome. Please see our [contributing guidelines](https://github.com/WebDevStudios/wds-bt/blob/main/CONTRIBUTING.md) before submitting a pull request.\n\nWDS BT is free software, and is released under the terms of the GNU General Public License version 2 or any later version. See [LICENSE.md](https://github.com/WebDevStudios/wds-bt/blob/main/LICENSE.md) for complete license.\n\n***\n\n## Acknowledgements\n\nThe WDS-BT theme was initially inspired by the [Powder](https://github.com/bgardner/powder) theme. We acknowledge and thank the creators of Powder for their work.\n\n***\n\n[🔝 Back to Top](#wds-bt)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebdevstudios%2Fwds-bt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebdevstudios%2Fwds-bt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebdevstudios%2Fwds-bt/lists"}