wp-bootstrap/CLAUDE.md

WordPress Theme using Bootstrap 5

Author: Marco Graetsch Author URL: https://src.bundespruefstelle.ch/magdev Author Email: magdev3.0@gmail.com Repository URL: https://src.bundespruefstelle.ch/magdev/wp-bootstrap Issues URL: https://src.bundespruefstelle.ch/magdev/wp-bootstrap/issues

Project Overview

This WordPress-Theme is built from scratch employing Bootstrap 5. Build modern Websites using the state-of-the-art Framework. All basic WordPress components are converted and are fully working. The theme uses Twig for rendering. It is also a good starting point as base theme for complex WordPress websites.

Features

• All native WordPress theme files converted to Boostrap 5
• Works seemlessly on default WordPress installations
• Installable via WordPress admin

Frontend

• Fully responsive Design
• Supports darkmode

Administration

• Compatible with the Gutenberg-Editor
• Customizable with the Design-Editor

Key Fact: 100% AI-Generated

This project is proudly "vibe-coded" using Claude.AI - the entire codebase was created through AI assistance.

Temporary Roadmap

Note for AI Assistants: Clean this section after the specific features are done or new releases are made. Effective changes are tracked in CHANGELOG.md. Do not add completed versions here - document them in the Session History section at the end of this file.

Getting started (v0.0.1)

• Create a new Theme, use wp-core/wp-content/themes/twentytwentyfive/ as blueprint (but not as base-theme, we're building from scratch!).
• Include Bootstrap 5 (CSS/JS) (serve locally, not from CDN, use Yarn for install).
• Use SASS as Stylesheet language, use node-sass for compilation.
• Integrate custom stylesheets using SASS.
• Add Gitea CI/CD workflow to create WordPress compatible release packages. Perform as much as possible build tasks in the workflow.
• Create PLAN.md with a comprhensive plan to create the custom theme.
• Create README.md with current information.
• Create CHANGELOG.md with initial information
• Commit to main and dev, but don't tag yet. Push to origin.

Planning is moved to PLAN.md

Technical Stack

• Language: PHP 8.3.x
• PHP-Standards: PSR-4
• Framework: Latest WordPress Theme API
• Template Engine: Twig 3.0 (via Composer)
• Frontend: Bootstrap 5 Javascript & Vanilla JavaScript
• Styling: Bootstrap 5 & Custom CSS (if necessary)
• Dependency Management: Composer (PHP), Yarn (JS/CSS)
• Internationalization: WordPress i18n (.pot/.po/.mo files)
• Canonical Plugin Name: wp-bootstrap

Security Best Practices

• All user inputs are sanitized (integers for quantities/prices)
• Nonce verification on form submissions
• Output escaping in templates (esc_attr, esc_html, esc_js)
• Direct file access prevention via ABSPATH check
• XSS-safe DOM construction in JavaScript (no innerHTML with user data)

Translation Ready

All user-facing strings use:

__('Text to translate', 'wp-bootstrap')
_e('Text to translate', 'wp-bootstrap')

Text domain: wp-bootstrap

Translation Template

• Base .pot file created: languages/wp-bootstrap.pot
• Ready for translation to any locale
• All translatable strings properly marked with text domain

Available Translations

• en_US - English (United States) [base language - .pot template]
• de_CH - German (Switzerland, formal)

There is no need to compile translation to *.mo locally as it will be done in the Gitea CD/CI pipeline

Create Releases

Important Git Notes:

• Default branch while development is dev
• Create releases from branch main after merging branch dev
• Tags should use format vX.X.X (e.g., v1.1.22), start with v0.1.0
• Use annotated tags (-a) not lightweight tags
• ALWAYS push tags to origin - CI/CD triggers on tag push
• Commit messages should follow the established format with Claude Code attribution
• .claude/settings.local.json changes are typically local-only (stash before rebasing)

CRITICAL - Release Workflow:

On every new version, ALWAYS execute this complete workflow:

# 1. Commit changes to dev branch
git add <files>
git commit -m "Description of changes (vX.X.X)"

# 2. Merge dev to main
git checkout main
git merge dev --no-edit

# 3. Create annotated tag
git tag -a vX.X.X -m "Version X.X.X - Brief description"

# 4. Push everything to origin
git push origin dev main vX.X.X

# 5. Switch back to dev for continued development
git checkout dev

Never skip any of these steps. The release is not complete until all branches and the tag are pushed to origin.

---

For AI Assistants:

When starting a new session on this project:

1. Read this CLAUDE.md file first
2. Semantic versioning follows the MAJOR.MINOR.BUGFIX pattern
3. Check git log for recent changes
4. Verify you're on the dev branch before making changes
5. Run git submodule update --init --recursive if lib/ is empty (only if submodules present)
6. Run composer install if vendor/ is missing
7. Test changes before committing
8. Follow commit message format with Claude Code attribution
9. Update this session history section with learnings
10. Never commit backup files (*.po~, *.bak, etc.) - check git status before committing
11. Follow markdown linting rules (see below)

Always refer to this document when starting work on this project.

Markdown Linting Rules

When editing CLAUDE.md or other markdown files, follow these rules to avoid linting errors:

1. MD031 - Blank lines around fenced code blocks: Always add a blank line before and after fenced code blocks, even when they follow list items. Example of correct format:

   • Item label:

     (blank line here) ```php code example ``` (blank line here)

2. MD056 - Table column count: Table separators must have matching column counts and proper spacing. Use consistent dash lengths that match column header widths.

3. MD009 - No trailing spaces: Remove trailing whitespace from lines

4. MD012 - No multiple consecutive blank lines: Use only single blank lines between sections

5. MD040 - Fenced code blocks should have a language specified: Always add a language identifier to code blocks (e.g., txt, bash, php). For shortcode examples, use txt.

6. MD032 - Lists should be surrounded by blank lines: Add a blank line before AND after list blocks, including after bold labels like **Attributes:**.

7. MD034 - Bare URLs: Wrap URLs in angle brackets (e.g., <https://example.com>) or use markdown link syntax [text](url).

8. Author section formatting: Use a heading (### Name) instead of bold (**Name**) for the author name to maintain consistent document structure.