From 34216a064fc028a19af8033761845150b2cd4268 Mon Sep 17 00:00:00 2001 From: GotPop Date: Thu, 9 Jul 2026 17:44:06 +0100 Subject: [PATCH] Updating readme --- README.md | 99 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 59 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 2f5de4ea..4e3b1794 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@ -# Observata Theme - -Custom WordPress theme using Gutenberg blocks with Timber/Twig server-side rendering. - -![Screenshot](screenshot.jpg) +# Observata [![Lint](https://github.com/gotpop/observata/actions/workflows/lint.yml/badge.svg)](https://github.com/gotpop/observata/actions/workflows/lint.yml) [![Test](https://github.com/gotpop/observata/actions/workflows/test.yml/badge.svg)](https://github.com/gotpop/observata/actions/workflows/test.yml) [![PHPStan](https://github.com/gotpop/observata/actions/workflows/phpstan.yml/badge.svg)](https://github.com/gotpop/observata/actions/workflows/phpstan.yml) +Custom WordPress theme using Gutenberg blocks with Timber/Twig server-side rendering. + +![Screenshot](screenshot.jpg) + ## Stack - **Timber 2.x** — Twig templating for PHP @@ -16,7 +16,7 @@ Custom WordPress theme using Gutenberg blocks with Timber/Twig server-side rende - **Three.js + Shaders** — WebGPU/WebGL hero shader effects - No `theme.json` — all styling is hand-written CSS with custom properties -## Architecture +
Architecture All blocks are **server-rendered via Twig** (not PHP `render.php`). The render pipeline: @@ -57,24 +57,39 @@ Timber is configured with three loader paths (`inc/theme-setup.php`): Page-level templates live in `views/templates/`, extending `views/base.twig`. -### PHP Modules (`inc/`) - -| File | Responsibility | -| ------------------------ | ----------------------------------------------------------------- | -| `theme-setup.php` | Timber init, menus, theme supports | -| `enqueue-assets.php` | CSS inlining (SCRIPT_DEBUG gated), script deferral, font preloads | -| `block-renderer.php` | Twig render callback, inner block serialization, context builders | -| `blocks.php` | Block auto-discovery + registration, webpack runtime enqueue | -| `twig-filters.php` | Custom Twig filters (`strip_html`) | -| `seo.php` | Sitemap, robots.txt, canonical URLs | -| `analytics.php` | GA4, Leadfeeder, Cookiebot settings | -| `schema-markup.php` | Schema.org itemscope/itemprop | -| `speculation-rules.php` | Chrome navigation prefetch | -| `content-filters.php` | Title filters, read-more links | -| `device-detection.php` | UA-based HTML classes | -| `image-optimization.php` | WebP MIME, disables intermediate sizes | - -### Design Token System (3-Tier) +
+ +
PHP Modules (`inc/`) + +Each file handles **one concern**: + +| File | Responsibility | +| --------------------------- | -------------------------------------------------- | +| `theme-setup.php` | Timber init, menus, theme supports, env helpers | +| `enqueue-assets.php` | CSS inlining (SCRIPT_DEBUG gated), script deferral | +| `block-renderer.php` | Twig render callback + context injection helpers | +| `block-helpers.php` | Hero split, block serialization, template map | +| `blocks.php` | Block registration, editor runtime, allowed blocks | +| `breadcrumbs.php` | Breadcrumb trail builder | +| `twig-filters.php` | Custom Twig filters (`strip_html`) | +| `seo.php` | Sitemap, robots.txt, canonical URLs | +| `content-filters.php` | Title filters, read-more links | +| `device-detection.php` | UA-based HTML classes | +| `image-optimization.php` | WebP MIME, disables intermediate sizes | +| `schema-markup.php` | Schema.org itemscope/itemprop | +| `speculation-rules.php` | Chrome navigation prefetch | +| `theme-settings.php` | Theme Settings admin page + sections | +| `theme-settings-footer.php` | Footer content fields | +| `analytics-ga4.php` | GA4 registration + output | +| `analytics-leadfeeder.php` | Leadfeeder registration + output | +| `analytics-cookiebot.php` | CookieBot registration + output | + +All functions are **fully typed** (parameter + return types). PHPStan runs at +level 5 in CI to prevent type regressions. + +
+ +
Design Token System No `theme.json` — all styling uses hand-written CSS with a 3-tier custom property system: @@ -86,7 +101,9 @@ No `theme.json` — all styling uses hand-written CSS with a 3-tier custom prope Prefer utility classes in Twig templates, theme tokens in block CSS, and avoid base tokens directly. -## Development +
+ +
Development ```bash npm run start # webpack watch mode (blocks + client JS + global CSS) @@ -113,20 +130,15 @@ define( 'SCRIPT_DEBUG', true ); This switches CSS from inlined `