wp-bootstrap/README.md

WP Bootstrap

A modern WordPress Block Theme built from scratch with Bootstrap 5. Features responsive design, dark mode support, Twig template rendering, and full compatibility with the WordPress Site Editor.

Features

• Bootstrap 5 Frontend -- Proper Bootstrap 5 HTML (navbar, cards, pagination, grid) rendered via Twig templates
• Dark Mode -- Toggle with localStorage persistence and prefers-color-scheme support
• Full Site Editing -- Compatible with the WordPress Site Editor for admin editing
• Style Variations -- 15 color schemes (7 light, 7 dark, plus default) with live Design Editor customization
• Block Patterns -- 41 patterns across 11 categories (hero, features, CTA, testimonials, pricing, contact, text, layout, components, navigation, pages)
• Bootstrap Icons -- 2,000+ icons available via CSS classes (bi bi-*)
• Block Styles -- 17 custom styles mapping Bootstrap components to WordPress blocks
• Custom Templates -- Landing (no header/footer), full-width, hero, sidebar page templates
• Header/Footer Variations -- Default, centered, transparent headers; default, minimal, multi-column footers
• Navigation Styles -- Dark navbar, offcanvas mobile navigation
• Widget Area -- Sidebar widget area manageable via WordPress admin, with built-in fallback
• Accessibility -- Skip-to-content link, ARIA labels, aria-current on active items, screen reader announcements
• RTL Support -- Right-to-left language support with logical CSS properties
• Translation Ready -- Full i18n support with en_US, de_CH, and fr_FR translations
• Responsive -- Mobile-first design with Bootstrap's responsive grid

Requirements

• WordPress 6.7 or higher
• PHP 8.3 or higher
• Composer
• Node.js 20+

Installation

From Release Package

1. Download the latest .zip from Releases
2. Go to WordPress Admin > Appearance > Themes > Add New > Upload Theme
3. Upload the ZIP file and activate

From Source

git clone ssh://git@src.bundespruefstelle.ch:2022/magdev/wp-bootstrap.git
cd wp-bootstrap
composer install
npm install
npm run build

Activate the theme in Appearance > Themes in the WordPress admin.

Development

Prerequisites

• Node.js 20+
• npm
• Composer
• PHP 8.3+

Build Commands

Command	Description
npm run build	Full production build (copy JS, compile SCSS, minify CSS)
npm run dev	Watch SCSS files and recompile on changes
npm run scss	Compile SCSS only
npm run postcss	Minify CSS with Autoprefixer and cssnano
composer install	Install PHP dependencies (Twig)

Build Pipeline

1. copy:js -- Copy Bootstrap JS bundle from node_modules to assets/js/
2. copy:theme-js -- Copy theme JS (dark-mode.js) from src/js/ to assets/js/
3. copy:icons -- Copy Bootstrap Icons font files (.woff, .woff2) to assets/fonts/
4. scss -- Compile SCSS (src/scss/) to CSS (assets/css/)
5. scss:rtl -- Compile RTL stylesheet (assets/css/rtl.css)
6. postcss -- Autoprefixer + cssnano minification to assets/css/style.min.css

Architecture

Frontend Rendering

The theme uses a dual-rendering approach:

• Site Editor (admin): FSE block templates in templates/ and parts/ for visual editing
• Frontend (public): Twig templates in views/ render Bootstrap 5 HTML via the template_redirect hook

The TemplateController intercepts frontend requests and renders the appropriate Twig template with data gathered by ContextBuilder. Plugins can hook into the wp_bootstrap_should_render_template filter to prevent rendering for specific requests (e.g., when a plugin handles its own custom post types). FSE templates remain untouched for the WordPress admin editor.

Style Variation Bridge

WordPress style variation colors are bridged to Bootstrap CSS custom properties at runtime. When a variation is selected in the Design Editor, the theme reads the active palette via wp_get_global_settings() and outputs inline CSS that overrides Bootstrap's compiled defaults. This works for both light and dark mode.

Key PHP Classes

Class	Purpose
TwigService	Singleton Twig environment with WordPress functions and globals
TemplateController	Hooks template_redirect, resolves and renders Twig templates
ContextBuilder	Gathers WordPress data (posts, menus, pagination, comments, sidebar)
NavWalker	Converts flat menu items to nested tree for Bootstrap dropdowns

Navigation Menus

Register menus in Appearance > Menus:

• Primary Navigation -- Displayed in the Bootstrap navbar with dropdown support
• Footer Navigation -- Displayed in the footer

If no menu is assigned, the primary location falls back to listing published pages.

Widget Areas

The theme registers a Sidebar widget area. When widgets are assigned via Appearance > Widgets, they replace the default sidebar content. When no widgets are assigned, the sidebar displays recent posts, a search form, and a tag cloud.

Project Structure

wp-bootstrap/
+-- assets/           Compiled CSS, JS, fonts
+-- inc/
|   +-- Template/     TemplateController, ContextBuilder, NavWalker
|   +-- Twig/         TwigService singleton
+-- languages/        Translation files (.pot, .po)
+-- patterns/         Block patterns (PHP)
+-- parts/            FSE template parts (header, footer, sidebar, variants)
+-- src/
|   +-- js/           Source JavaScript
|   +-- scss/         Source SCSS
+-- styles/           Style variations (JSON)
+-- templates/        FSE templates (HTML)
+-- views/            Twig templates (Bootstrap 5 HTML)
|   +-- base.html.twig
|   +-- pages/        Page templates (index, single, page, archive, search, 404)
|   +-- partials/     Reusable parts (header, footer, pagination, sidebar, etc.)
|   +-- components/   UI components (post card, post loop)
+-- functions.php     Theme bootstrap
+-- style.css         Theme metadata
+-- theme.json        Design tokens and settings

Technology Stack

• PHP 8.3+ with PSR-4 autoloading
• Twig 3.0 via Composer
• Bootstrap 5.3+ CSS & JS (served locally)
• Dart Sass for SCSS compilation
• PostCSS with Autoprefixer and cssnano

License

GPL-2.0-or-later. See http://www.gnu.org/licenses/gpl-2.0.html.

Author

Marco Graetsch - https://src.bundespruefstelle.ch/magdev