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:

```php
__('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:

```bash
# 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.