The command ddev build produces a complete static site in under a minute. But what actually happens? 10 distinct steps, each one a design decision. Here is the full pipeline — every command, every config file, every design choice.

The 10-step pipeline#

Step 1: Seed local/#

Before anything compiles, the build ensures a working local/ directory exists. If it is empty or missing, the build copies docs/demo/ into it:

cp -r docs/demo/. local/

If local/ already has real content, the build skips this step. Passing --bare seeds from docs/bare/ instead — a minimal wireframe theme with no content, useful for starting fresh. Passing --demo forces a re-seed even if content exists, backing up the old local/ to local-{TIMESTAMP}/ first.

The build also copies assets/images/og-default.jpg into local/assets/images/ if it is missing — the fallback Open Graph image that renders when a page has no featured image.

Step 2: Composer install#

composer install --optimize-autoloader --no-interaction

Standard Symfony step. The --optimize-autoloader flag produces a classmap for faster autoloading — important because every sub-request in the build creates fresh service containers.

Step 3: Clear dart-sass binary#

rm -rf var/dart-sass

The sass:build command downloads an architecture-specific dart-sass binary. Clearing it before each build ensures the correct binary for the current platform. Essential for cross-platform workflows — developing on ARM64 (Raspberry Pi 5), running CI/CD on x86_64 (GitHub Actions), deploying to ARM64 again.

Step 4: Cache clear#

php bin/console cache:clear

Produces the compiled Symfony dependency injection container. The warm cache improves sub-request performance during the static build.

Step 5: SCSS compilation#

php bin/console sass:build

Compiles assets/styles/app.scss into var/sass/app.css. The core SCSS import cascade, in order:

_tokens.scss    ← CSS custom properties (--bg, --text, --accent, ...)
_variables.scss ← SCSS compile-time constants ($font, $sp-*, $radius-*, ...)
_base.scss      ← reset, box-sizing, body defaults
_layout.scss    ← .container, .content-layout, .site-header/footer
_nav.scss       ← navigation, hamburger, dropdown, .skip-link
_components.scss ← post-card, pagination, badges, buttons, alerts, widgets
_prose.scss     ← .prose class for rendered Markdown
_pages.scss     ← homepage sections, hero, CTA
_blog.scss      ← reading progress bar, code-copy button
_styleguide.scss ← sg-* scaffold classes
_utilities.scss ← atomic utility classes

Local themes override _tokens.scss and _variables.scss — everything else inherits the new values through the cascade. Change --accent from #2563EB to #FFA040, and every component, button, and link updates without touching component SCSS.

Step 6: Asset-map compile#

rm -rf public/assets
php bin/console asset-map:compile

First clears previously compiled assets, then compiles everything mapped by Symfony AssetMapper:

• assets/app.js → public/assets/app-{contenthash}.js
• var/sass/app.css → public/assets/app-{contenthash}.css
• local/assets/**/* → public/assets/local/**/* (if local/assets/ exists)

The {contenthash} is a fingerprint derived from file contents. Changing one character in SCSS produces a completely different hash, busting CDN and browser cache automatically. No version query parameters — the filename itself is the version.

After compilation, the sensiolabs_minify bundle minifies all CSS and JS files. The importmap.php file defines which entrypoints exist:

return array_filter([
    'app' => [
        'path' => './assets/app.js',
        'entrypoint' => true,
    ],
    'app-local' => file_exists(__DIR__ . '/local/assets/app.js')
        ? [
            'path' => './local/assets/app.js',
            'entrypoint' => true,
          ]
        : null,
]);

Two entrypoints: app (always — core CSS + JS) and app-local (conditional — only if local/assets/app.js exists). Both are entrypoint: true, so Twig's {{ importmap('app') }} and {{ importmap('app-local') }} load them independently. app-local loads after app in the template, giving local CSS the last word on specificity ties without !important.

Step 7: Static HTML build#

php bin/console app:build -v

This is the core magic. The -v flag enables verbose output, showing every rendered URL. Five sub-steps execute in sequence:

7a. Invalidate content cache

The build clears the app.content cache pool for every configured locale. The cache stores parsed ContentTree objects — invalidating it forces a full re-parse of all Markdown files, ensuring the static build reflects the current content state. In development, the cache uses an in-memory array adapter. In production builds, it uses a filesystem adapter under var/cache/.

7b. Collect routes

The collectRoutes() method gathers every URL the site serves. For each locale:

• Home page (home_{locale})
• Blog listing (blog_list_{locale})
• Paginated blog pages (pages 2 through ceil(postCount / postsPerPage))
• Every published post URL ($post->url())
• Every scheduled post URL (renders a "coming soon" page with noindex)
• Every category page (blog_category_{locale})
• Every tag page (blog_tag_{locale})
• Every archive month (blog_archive_{locale} with year + month parameters)
• Every archive year (blog_archive_year_{locale} — a separate route from months)
• Every static page (non-dynamic, non-empty URL, not the home URL)
• Search page (search_{locale})

The result is deduplicated with array_unique(). For a site with 4 locales and ~40 content items per locale, this produces around 500 URLs including pagination, archives, tags, and feeds.

7c. Render pages

Each URL is rendered via a Symfony sub-request:

$request = Request::create($url, Request::METHOD_GET);
$request->attributes->set('_static_build', true);

$response = $this->httpKernel->handle(
    $request,
    HttpKernelInterface::SUB_REQUEST,
    false,
);

The _static_build attribute signals to controllers, services, and templates that they are running inside a build, not serving a real HTTP request. Themes and local extensions can branch on it to vary output between live serving and the static build. (Draft/scheduled visibility itself is decided by the absence of the dev-only preview session toggles — the CLI has no session, so the build always renders the published view.)

The response body is written to disk as {outputDir}/{url}/index.html. The root URL / becomes index.html at the output root. Any URL returning HTTP 400 or higher is caught as an error and skipped (the page is counted as skipped but the build continues).

After rendering all content pages, the build renders feed URLs:

• robots_{locale} — written as {outputDir}/robots.txt
• sitemap_{locale} — written as {outputDir}/sitemap.xml (or index.xml for slash-ending URLs)
• rss_{locale} — written as {outputDir}/rss.xml (or index.xml)

Then error pages are rendered via sub-request:

• error_404_{locale} → {prefix}404.html
• error_500_{locale} → {prefix}500.html

Where {prefix} is the non-default locale path (e.g. pl/404.html). These are pre-rendered so nginx can serve them directly without waking PHP-FPM.

The sub-request approach matters for correctness: the same controllers and Twig templates used in development mode produce the static output. What you see at ddev start is what ships to production. No separate rendering code path. No "dev mode vs build mode" template discrepancies.

7d. Copy media files

Symfony Finder locates every files/ directory under the content tree and mirrors them into the output:

{contentDir}/{postDir}/files/  →  {outputDir}/media/{postDir}/

This is a brute-force mirror — no hashing, no deduplication, no tree-shaking. Content authors control what is in files/. Delete a file there, it disappears from the next build. The simplicity is intentional: no asset graph, no build manifest, no reference counting.

7e. Optimise originals and generate responsive variants

Two ImageMagick passes run on the mirrored media directory:

Optimisation on every .webp file (excluding existing variants identified by the -{width}w suffix pattern):

$this->imageResizer->optimize($path);
// → exec('magick convert input.webp -quality 82 -strip -define webp:method=6 output.webp')

Quality defaults to 82, configurable in _site.yaml. The -strip flag removes metadata (EXIF, ICC profiles). The webp:method=6 flag uses the slowest but most efficient WebP encoder.

Responsive variant generation for every .webp original:

$width = getimagesize($path)[0];
$variantWidths = $this->responsiveImageService->getVariantWidths($width);
// [640, 960] filtered from config — only widths < source width

foreach ($variantWidths as $variantWidth) {
    $this->imageResizer->resize($path, $dir . '/' . $baseName . '-' . $variantWidth . 'w.webp', $variantWidth);
}

For a 1280px source image with configured variant widths of [640, 960], this produces image-640w.webp and image-960w.webp. The original image.webp serves as the 1280w fallback.

Step 8: Copy favicon#

cp local/assets/favicon.ico public/

If local/assets/favicon.ico does not exist, falls back to assets/images/favicon.ico from core. The favicons Twig block in base.html.twig can be overridden in local templates to reference different icon paths.

Step 9: Pagefind index#

npx pagefind --site public/static --output-path public/pagefind

Pagefind scans the pre-rendered HTML for data-pagefind-body regions, builds per-language WASM binary search indexes, and writes ~437 files into public/pagefind/. This step runs separately from the PHP build because it requires Node.js. The PHP layer has no Node dependency — keeping Pagefind as a separate orchestration step means the entire PHP application works without node_modules.

The production deploy script (scripts/rebuild-content.sh) pins Pagefind to version @1.5.0:

docker compose run --rm php npx --yes pagefind@1.5.0 --site public/static --output-path public/pagefind

Later Pagefind versions ship a jemalloc-linked ARM64 binary that crashes on hosts with 16K-page kernels (Raspberry Pi 5). The error is "<jemalloc>: Unsupported system page size". Pinning to 1.5.0 avoids this. The DDEV-local build command does not pin — it runs on x86_64 where all versions work correctly.

Step 10: Nginx serves it#

After all steps complete, public/ contains three directories:

public/
├── assets/        ← fingerprinted JS/CSS (immutable, long cache)
├── static/        ← all HTML + RSS + sitemap + media/
└── pagefind/      ← search index (WASM + metadata)

Nginx try_files resolves every incoming request to a pre-rendered file:

location / {
    try_files /static$uri/index.html /static$uri /static$uri.html =404;
}

PHP-FPM is only called for the contact form endpoint:

location ~ ^/(api|pl/api)/ {
    fastcgi_pass php:9000;
}

The entire site except the contact form is static files on disk. No PHP runtime. No database. No application server.

Pipeline summary#

Design decisions#

Why sub-requests?#

Sub-requests reuse the same controllers and Twig templates used in development mode. No separate rendering code path. What you see in ddev start is what you get in production. The _static_build attribute is the only signal that differs — everything else runs identically. This eliminates the most common static site generator bug: dev mode rendering differently from build output.

Why separate SCSS and asset-map steps?#

sass:build produces raw CSS — useful in development watch mode where you recompile on file changes but do not want to re-fingerprint on every save. asset-map:compile fingerprints and minifies — a production-only concern. Separation means these two concerns stay independent.

Why brute-copy media?#

Content authors control what is in files/. No build manifest. No tree-shaking. No asset graph. Delete from files/, gone from the build. The simplicity is worth the disk space — and disk space for WebP images on a static site is trivial.

Why ImageMagick CLI, not GD or Imagick?#

exec('magick convert ...')

GD cannot reliably handle all WebP variants (lossless, animation, alpha). Imagick has PHP extension compatibility issues across PHP versions. ImageMagick CLI is always available in the Docker container and is the most portable option across architectures.

Why Pagefind as a separate step?#

Node.js dependency. The PHP build does not need Node for anything else. Keeping Pagefind as a separate orchestration step means the entire PHP layer works without node_modules — a significant simplification for deployment and development setup.

Performance#

The full pipeline runs in under 60 seconds for a ~170-page site (4 locales, ~40 content items each). The bottlenecks:

• ImageMagick — 100+ image optimisations and variant generations. Currently sequential — a single-threaded PHP loop through every file. Parallelising this (multiple exec() calls) would be the biggest single improvement.
• Sub-request rendering — ~1ms per request, ~500 total including pagination. Symfony's compiled container makes this fast. The main cost is Twig template compilation, not I/O.
• Pagefind — 2–5 seconds, dominated by WASM compilation from Rust source, not HTML parsing. Scales linearly with page count.

Where to customise#

The pipeline has five deliberate injection points for local overrides:

• local/assets/styles/ — override SCSS partials (_tokens.scss, _variables.scss)
• local/assets/ — add custom JS (becomes app-local entrypoint when app.js exists)
• local/templates/ — override any Twig template (falls through to core via namespace priority)
• local/content/_site.yaml — change variant widths, image quality, Magick flags, post counts
• local/src/ — add custom Twig extensions or service decorators (auto-discovered by Symfony)

No config files to edit. No registration step. No framework plugin system. Copy a file into local/, edit it, build. That is the whole model.

Part 7 walks through building a complete production theme on top of this pipeline — Twig blocks, SCSS tokens, custom components, local JS, and service decoration. Part 8 dives deep into Pagefind: the two search UIs, the data-pagefind-* contract, production deployment, and the ARM64 version-pinning war story.

I spent a month preparing my personal website's codebase for open-source release. Not because I expected thousands of contributors — but because going public forced me to write the docs, add the tests, fix the security issues, and make the architecture actually reusable. The code that's good enough to show strangers is better code than the code that isn't.

Here's the complete checklist.

Why Open-Source a Personal Project?#

Accountability — code you'll show the world is better code. Documentation discipline — you write docs when strangers might read them. And the ultimate refactoring exercise: would you be proud to show this code?

notACMS is a Symfony-based static site generator with no database, no CMS, and no PHP involved in serving content, licensed under Apache 2.0. If someone else can use it, that validates the architecture.

The Audit: 9.5/10 Readiness Score#

What Was Missing (and How I Fixed It)#

GitHub Actions CI/CD — .github/workflows/ci.yml: PHP 8.5, composer install, validate, audit, Twig lint, Rector dry-run, CS Fixer, PHPStan, PHPUnit. Nothing ships unless all checks pass.

CONTRIBUTING.md — DDEV setup, code style standards, PR process, commit conventions. The barrier to contribution should be one command: ddev start.

SECURITY.md — Supported versions, vulnerability reporting (private disclosure), security update policy. Even for a one-person project, having a defined process matters.

CHANGELOG.md — Keep a Changelog 1.1.0 format, initial release entry. Future releases will track what changed.

Issue/PR templates — Bug report, feature request, PR guidelines. Good templates reduce the cognitive load for both the reporter and the maintainer.

CODEOWNERS — Code ownership tracking. It's one person, but it's good practice and signals that the project is maintained.

Test suite — 368 tests across Unit and Integration, covered in part 1 of this series.

Rector as Automated Refactoring#

Rector uses withPreparedSets(codeQuality: true, codingStyle: true, deadCode: true, typeDeclarations: true, symfonyCodeQuality: true) plus withPhpSets(php85: true). Dry-run in CI, --fix in ddev code-fix. What it catches: redundant null checks, array simplification, modern PHP 8.5 syntax, dead code, type declarations. What it skips: ControllerMethodInjectionToConstructorRector — the ErrorController needs runtime values that can't be injected via constructor.

What I Skipped (and Why)#

Code of Conduct — It's a one-person project. No community to govern. If that changes, this changes.

Third-party license notices — MIT dependencies don't require attribution in source. Maybe later if the project grows.

100% test coverage — The remaining ~20% is email sending, media copy paths, error controller __invoke. High complexity to trigger, low ROI. 80% covers all public APIs, main code paths, and edge cases.

The Deploy Pipeline#

ddev code-check   # Composer validate + audit, Twig lint, Rector, CS Fixer, PHPStan
ddev test         # 368 tests, 490 assertions
./deploy.sh --prod

The quality gate: nothing ships unless all checks pass. The deploy script runs inside the production PHP container where the correct CPU architecture is known. After the build, nginx is already serving the new static files.

The Result: notACMS#

A Symfony-based static site generator, Apache 2.0 licensed, with docs, tests, CI, and a local override pattern. Not a framework — a project template you can clone, customise via local/, and deploy. The entire codebase, content, and configuration fits in a single git repository. Backup is git push.

This series started with 368 tests, went through an AI code review, security fixes, and the local override pattern. After shipping, the next posts cover the build pipeline internals, building a production theme, and search with Pagefind. The original WordPress to Symfony series tells the story of how this codebase came to exist.

You want to share a Symfony project template. Every user needs to customise it — different colours, different homepage, different navigation. Forking means they can't pull upstream updates. Configuration files can't handle template changes. Themes are too rigid.

The solution I built for notACMS is a local/ directory that merges on top of the base project at build time. Users customise local/, the rest stays untouched, and when the upstream changes they pull and merge like any other git operation.

The Problem#

Three scenarios that configuration files can't solve:

• User A wants different CSS colours and a custom homepage layout
• User B wants to override just the navigation component
• User C wants to add their own translation strings

Forking is the traditional answer. But forking means every upstream update is a manual merge. For a project that gets regular improvements, that's a maintenance burden that kills adoption.

The Solution: A Merge Layer#

local/ sits alongside the base project. At build time, paths resolve with priority: local/ first, base second. Three override types:

Full override — Replace an entire file. local/templates/base.html.twig replaces templates/base.html.twig completely.

Block override — Extend and override specific Twig blocks:

{% extends 'base.html.twig' %}

{% block stylesheets %}
    {{ parent() }}
    <link rel="stylesheet" href="{{ asset('styles/custom.css') }}">
{% endblock %}

Translation override — local/translations/messages.en.yaml merges with base translations, adding or replacing keys:

# local/translations/messages.en.yaml
site.title: "My Custom Site"
nav.home: "Home"

CSS Ordering: Two-Entrypoint Importmap#

The trickiest part. Local styles must load after base styles to override them via cascade:

// importmap.php
->add('app', 'assets/app.js')           // base: imports app.scss
->add('local', 'assets/local/app.js')   // local: imports local.scss

local.scss is imported after app.scss, so CSS cascade works correctly. No !important needed. The import map registers both entrypoints; the browser loads them in order.

Template Resolution#

Kernel::build() checks for local/templates/ files and copies them to the output, overriding base templates. The local/ directory is gitignored in the user's project, but .gitkeep placeholders ensure fresh clones have the structure:

local/
├── assets/
│   └── styles/
│       └── .gitkeep
├── templates/
│   └── .gitkeep
└── translations/
    └── .gitkeep

Boilerplates in docs/examples/#

Copy-paste starting points for different customisation levels:

What's Tracked in Git#

.gitkeep files in local/ placeholder dirs so the structure exists in fresh clones. The actual override files are gitignored — they're the user's customisations. docs/examples/ contains the copy-paste templates that users start from.

Why Not a Framework?#

notACMS isn't a framework. Users don't composer install notacms/core. They clone the repo, customise local/, and deploy. The pattern is simple enough to understand in 5 minutes, powerful enough to handle any customisation. The entire customisation surface is one directory.

The next post covers the full open-source release checklist — everything from the previous four posts leading to the final launch.

"Static sites are secure." It's the most common thing people say when you tell them you replaced WordPress with static HTML. And it's true — as long as "static" means "no database and no user accounts." The moment a static site has a contact form, a search function, or any JavaScript that renders user content, the attack surface isn't zero. It's just different.

Here are the vulnerabilities I found in mine.

XSS in search.js — and why the obvious fix was wrong#

Pagefind returns search results as JSON. The JavaScript renders them with innerHTML. The initial instinct after a code review was to escape the excerpt:

// "Fixed" in 1.1.2
'<p class="post-card-excerpt">' + esc(r.excerpt) + '</p>'

It passed review. Shipped. Then someone searched for something and noticed the highlighted match wasn't bold anymore — it showed as literal text:

…results for <mark>notacms</mark> in…

Pagefind injects <mark> tags into excerpts at query time to highlight matched terms. esc() escaped those tags along with everything else. The "security fix" silently broke search highlighting.

The revert:

// Current
'<p class="post-card-excerpt">' + r.excerpt + '</p>'

This isn't leaving a vulnerability in place. r.excerpt isn't user input — it's generated by pagefind from your own pre-indexed static HTML. The only HTML it contains is the <mark> tags pagefind itself injects. The real rule isn't "always escape before innerHTML" — it's know who controls the string. Every other field (r.url, r.meta.title, r.meta.category, tags) is escaped, because those come from frontmatter that could in theory contain anything.

The naive escape was worse than no fix: it introduced a regression, and gave a false sense that the XSS surface had been addressed.

Open Redirect via Referer Header#

The draft and scheduled preview controllers toggle visibility and redirect back:

// Vulnerable (pre-1.1.x)
return $this->redirect($request->headers->get('referer', '/'));

The Referer header is user-controlled. An attacker can craft a link that takes a user through the preview toggle and then redirects them to an arbitrary external site. The 1.1.x fix validated that the redirect target is a local path:

// Fixed in 1.1.x
$referer = $request->headers->get('referer', '/');
if ($referer && str_starts_with($referer, '/') && !str_starts_with($referer, '//')) {
    return $this->redirect($referer);
}
return $this->redirect('/');

1.2.0 tightened this further. The str_starts_with check operates on the raw header string — defensible, but fragile against malformed or unusual inputs. The improved version uses parse_url() to extract host and path separately, then validates each component explicitly, and redirects to the path only (never the full header value):

// Improved in 1.2.0
$referer = (string) $request->headers->get('referer', '');
$refererParts = parse_url($referer);
$refererHost = is_array($refererParts) ? ($refererParts['host'] ?? null) : null;
$refererPath = is_array($refererParts) ? ($refererParts['path'] ?? '') : '';

if (
    (null === $refererHost || $request->getHost() === $refererHost)
    && str_starts_with($refererPath, '/')
    && !str_starts_with($refererPath, '//')
) {
    return $this->redirect($refererPath);
}
return $this->redirect('/');

Path Traversal in MediaController#

The variant cache serves resized images. The variant filename comes from the URL:

$variantPath = $this->cacheDir . '/' . $variantFilename;

Without a realpath() guard, a crafted URL like ../../etc/passwd could escape the cache directory. The fix is a single check:

$realCacheDir = realpath($this->cacheDir);
if (false === $realCacheDir || !str_starts_with(dirname($variantPath), $realCacheDir)) {
    throw new NotFoundHttpException('Invalid variant path');
}

CSRF on Pre-rendered Contact Forms#

This one is architectural, not a bug. Symfony's CSRF tokens are tied to the user's session. But static pages don't have sessions — the HTML is generated once at build time. Every visitor would get the same token, baked into the static file, which can't validate against their own session.

The real defenses are different:

1. Turnstile CAPTCHA — replaces the bot-prevention layer with server-side verification
2. X-Requested-With: XMLHttpRequest — blocks simple form submissions from non-JS clients
3. nginx restriction — PHP-FPM only reachable at ^/(api|pl/api)/

Cookie Secure Flag — the flag that breaks dev silently#

The locale redirect sets a lang cookie client-side. ; Secure was in the code from day one:

document.cookie = COOKIE + '=' + encodeURIComponent(value) + '; path=/; SameSite=Lax; Secure';

Then during development on DDEV over HTTP, the locale redirect stopped working. Clicking the language switcher did nothing. The cookie just wasn't there.

; Secure tells the browser to only set the cookie on HTTPS origins. On HTTP it silently does nothing — no error, no warning, no console message. The locale mechanism was completely non-functional on any HTTP origin.

The fix is to make it conditional:

var secure = window.location.protocol === 'https:' ? '; Secure' : '';
document.cookie = COOKIE + '=' + encodeURIComponent(value) + '; path=/; SameSite=Lax' + secure;

Production is always HTTPS, so ; Secure is always added there. Dev over HTTP gets a working cookie without it. The cookie banner uses unconditional ; Secure — consent doesn't need to persist on HTTP dev, so that one is fine as-is.

The lesson isn't "remember to add ; Secure." It's that security flags which silently fail are a class of their own. You add them, feel good, and don't find out they broke something until you're deep into debugging an unrelated problem.

What "Static" Actually Protects You From#

SQL injection — no database. Server-side template injection — templates are compiled at build time. File upload attacks — no uploads. Brute-force login attacks — no login page.

What it doesn't protect you from: client-side XSS, open redirects, path traversal in dynamic endpoints, CSRF on forms, missing security headers, JavaScript that trusts untrusted data.

The Contact Form: The Only Dynamic Endpoint Is the Most Attacked#

nginx restricts PHP-FPM to a single pattern:

location ~ ^/(api|pl/api)/ {
    fastcgi_pass $php_upstream;
}

Everything else is served from disk. The contact form has Turnstile verification, a tight CSP that only permits challenges.cloudflare.com as an external domain, and no 'unsafe-inline' or 'unsafe-eval' in script-src:

add_header Content-Security-Policy
    "default-src 'self';
     script-src  'self' challenges.cloudflare.com;
     style-src   'self' 'unsafe-inline';
     img-src     'self' data:;
     frame-src   challenges.cloudflare.com;
     connect-src 'self' challenges.cloudflare.com;"
    always;

The 'unsafe-inline' in style-src is a deliberate compromise: Turnstile's widget injects inline styles that can't be avoided without a CSP nonce. Everything else is locked down.

The next post covers the local override pattern — how notACMS lets users customise templates, CSS, and translations without forking.

The code passed PHPStan level 6. PHP CS Fixer had nothing to complain about. Rector's dry-run was clean. I had reviewed every file myself. I was ready to open-source it.

Then I asked an AI to audit it against a 200-line instruction file. It found 79 issues.

The Setup: AGENTS.md as an Audit Manual#

Not "review my code" — that produces generic feedback about error handling and edge cases. Instead, a detailed checklist in AGENTS.md:

• Architecture principles — final classes only, interface segregation, value objects over associative arrays
• Naming conventions — XxxInterface → Xxx, public const in interfaces
• Security patterns — path traversal guards, redirect validation, input sanitisation
• Code style rules — Yoda conditions, blank line before return, strict types
• Documentation sync — service tables matching src/, variable tables matching _variables.scss

The AI didn't guess what to look for. It followed instructions. The difference is the same as between a code review from someone who knows your project and one from someone who doesn't.

What AI Caught That I Missed#

Mutable cached state — ContentTree::setIncludeDrafts() was mutating a cached object. The same tree instance was shared across requests, so toggling drafts on one request affected the next. A race condition waiting to happen. The fix: make ContentTree immutable and move draft filtering to the service layer.

SOLID violations — SiteConfigServiceInterface had 16 methods. The project rule is max 5. ContentTree had 20+ methods doing data structure, query engine, and recommendation scoring — three jobs in one class. The fix: extract RelatedPostsService (73-line scoring algorithm → separate service with its own interface).

Duplicated logic — readingTime() and excerpt() both doing strip_tags + str_word_count on the same HTML content. Extracted to a shared getPlainText() method.

Accessibility gaps — Nested <label> elements in the contact form (invalid HTML), missing role="alert" on error spans, aria-current="true" instead of "page". Each a one-line fix, but invisible without a checklist.

Documentation rot — docs/STYLEGUIDE.md listing Bootstrap blue (#0d6efd) instead of the actual green (#2d8a4e). docs/ARCHITECTURE.md referencing phantom files: tagline.js, contact_widget.html.twig, _header.scss — none of which existed.

What AI Got Wrong (False Positives)#

CSRF on the contact form — flagged as a vulnerability, but actually intentional. Static pre-rendered forms can't use session-bound CSRF tokens — the token is baked into the HTML at build time, tied to the build server's session. Every visitor gets the same token. Turnstile + X-Requested-With header provide the real defense.

User input in 404 error messages — flagged as enumeration risk, but these messages only appear during the static build, not to visitors. Symfony's production error pages don't expose exception messages.

"Non-yoda" comparisons — flagged variable-vs-method-call patterns like $page->directoryKey() === $directoryKey, but the real yoda rule is about literals (null, false, strings) on the left. Variable-vs-variable comparisons don't need flipping.

What I Changed vs What I Accepted#

About 60 issues fixed. About 19 accepted as-is:

• Duplicate preview services — DraftPreviewService and ScheduledPreviewService are nearly identical, but each is 3 lines. Parameterizing them would require a ServiceLocator, enum injection, and custom serialization on the data collector. More complexity than the original. Accepted.
• Wide SiteConfigServiceInterface — 16 methods, but it's a config object, not a business service. Splitting it touches 20 files for annotation tidiness only. Accepted.

The fixes that mattered:

// Before: mutable cached tree
$tree->setIncludeDrafts(true);  // mutates shared instance

// After: immutable tree, filtering at service layer
$posts = $this->contentService->getPosts($locale, includeDrafts: true);

// Before: 73-line scoring algorithm in ContentTree
public function getRelatedPosts(ContentItem $post, int $limit = 3): array
{
    // ... 73 lines of tag/category/series scoring
}

// After: separate service
final class RelatedPostsService implements RelatedPostsServiceInterface
{
    public function findRelated(ContentItem $post, ContentTree $tree, int $limit = 3): array
    {
        // ... same logic, but isolated
    }
}

The Lesson#

"Review my code" produces generic feedback. "Audit against these 200 lines of project standards" produces specific, actionable findings. AGENTS.md isn't just for building — it's for reviewing too. The AI caught things I'd looked at dozens of times because it was checking against rules, not relying on familiarity.

The next post covers the security vulnerabilities among those 79 issues: XSS in search, open redirects, and path traversal on a "static" site.

The content is Markdown files. The templates are Twig. The styles are SCSS. There is no database, no API, no user accounts. What exactly is there to test?

Quite a lot, as it turns out. The logic that parses frontmatter, builds the content tree, computes translation maps, generates responsive srcsets, and resolves localized routes is pure PHP — and it's as bug-prone as any other codebase. Most static site generators have zero tests. notACMS has 368.

Why Test a Static Site?#

The content files don't need testing. The pipeline that processes them does: ContentTreeBuilder scanning directories, MarkdownParser extracting frontmatter, ContentService caching results, TranslationMapBuilder computing locale-to-URL maps, LocalizedRouteLoader generating routes from _routes.yaml. All of this is pure logic with no database dependency — ideal for unit tests.

The test pyramid for a content-driven application looks different from a typical web app:

• Unit tests — ContentItem, ContentTree, Value Objects. No mocks, no kernel. Frontmatter arrays go in, expected properties come out.
• Unit tests with stubs — SiteConfigService, TagTranslationService, SrcsetExtension. Interface stubs for dependencies, temp directories for filesystem operations.
• Integration tests — controllers, commands, services with booted Symfony kernel. HTTP smoke tests for key routes.

The Numbers#

368 tests, 490 assertions, ~80% line coverage, ~82% method coverage. Three phases:

Phase 1: Pure unit tests (191 tests) — ContentItem with its isDraft, isScheduled, isPinned, readingTime, excerpt, and dozens of frontmatter parsing cases. ContentTree filtering by category, tag, archive month, pagination. Value Objects: AdjacentPosts, ArchiveMonth, CategoryCount, ParsedMarkdown, ParsedVariant, RenderResult, SidebarData, TagCount. No mocks, no kernel, no filesystem.

Phase 2: Unit tests with interface stubs (49 tests) — SiteConfigService reading YAML from temp directories, TagTranslationService translating tags between locales, SrcsetExtension generating srcset attributes. createStub() for interfaces that don't need expects(), TmpDirTrait for filesystem cleanup.

Phase 3: Integration tests (127 tests) — BlogController returning 200 for valid pages and 404 for nonexistent ones, ContactController handling form submissions, BuildStaticSiteCommand completing without errors, LocalizedRouteLoader generating the right routes. The Symfony kernel boots, the content tree builds, the HTTP client makes requests.

What's Worth Testing#

ContentItem::isScheduled() detecting future dates correctly — including the boundary case where the date is exactly now (right-open interval: the post is already published at the boundary). ContentTree::getPaginatedPosts() slicing correctly across pages. LocalizedRouteLoader generating routes for every locale. BuildStaticSiteCommand completing without errors.

What's NOT worth testing: the email sending path in ContactController (requires mocking the mailer, testing infrastructure I don't own), media file copy operations in BuildStaticSiteCommand (requires real filesystem with images), ErrorController::__invoke (hard to trigger via HTTP client). High complexity to trigger, low ROI.

Testing Conventions That Matter#

ContentItemFactory for all fixtures — Never construct ContentItem directly in tests. The factory provides sensible defaults and named constructors:

$post = ContentItemFactory::publishedPost([
    'title' => 'Test Post',
    'tags'  => ['testing', 'php'],
], 'test-post', '/blog/test-post/');

XPath assertions, not CSS selectors — symfony/css-selector is not installed, so $crawler->filter('.class') throws LogicException. Use filterXpath():

$meta = $crawler->filterXpath('//meta[@name="robots"]/@content');
self::assertGreaterThan(0, $meta->count());
self::assertStringContainsString('noindex', $meta->text());

createStub() vs createMock() — PHPUnit 13 triggers notices for mocks that don't have expects() calls. Use createStub() in setUp() for interfaces where you only need return values. Create createMock() locally only in tests that verify method call counts:

// setUp() — no expects, use createStub()
$this->config = $this->createStub(SiteConfigServiceInterface::class);
$this->config->method('getPostsPerPage')->willReturn(10);

// Individual test — has expects, use createMock()
$mock = $this->createMock(MarkdownParserInterface::class);
$mock->expects(self::once())->method('parse')->willReturn($parsed);

declare(strict_types=1) on every test file — Same as production code. Yoda conditions in assertions. Blank line before return.

CI Integration#

ddev test runs the full suite with testdox output. GitHub Actions runs the Unit suite on every push:

- name: PHPUnit
  run: vendor/bin/phpunit --testsuite Unit

Integration tests need the full kernel and content files — viable locally via DDEV, but Unit-only in CI is the right trade-off. The Unit suite catches regressions in the core logic; Integration tests catch wiring issues that only appear with the full stack.

The Payoff#

When I deliberately broke ContentItem::isDraft(), the test suite caught it immediately — 12 tests failed with clear messages about which property was wrong. Before the test suite, that kind of regression would only surface when someone noticed a draft post on the live site.

368 green tests means confidence to refactor. Extracting RelatedPostsService from ContentTree, making the tree immutable, moving constants to interfaces — all of that happened with the safety net of tests that would catch anything that broke.

The next post covers what happened next: an AI audit found 79 issues in code that had already passed PHPStan, CS Fixer, and manual review. Tests only catch what you think to test. An audit catches what you forgot to think about.

A few months ago I wrote about running an AI audit on notACMS and finding 79 bugs. 1.2.0 is the follow-up: another full pass, but this time with the project in better shape and with more context in AGENTS.md to guide the review. The process found obvious things and non-obvious things. Here are the ones worth talking about.

The nginx bug that broke contact forms silently#

The most frustrating find: a contact form that worked perfectly in every environment except Docker production.

The nginx config used a regex location to route the contact API:

location ~ ^/[a-z]{2}/api/contact$ {

Except it didn't. Nginx regex syntax treats {2} as a literal string in some contexts — the quantifier was being matched literally, not as "exactly two characters". The regex never matched, so POST /pl/api/contact never reached PHP. Every non-default locale got a silent 404 on form submission.

It worked fine in DDEV (which has its own nginx config) and in development (where PHP handles routing directly). Docker production, which used the committed nginx.conf.template, was broken from the start. One character fix: quote the braces.

locale-redirect: being helpful was harmful#

The locale-redirect.js script reads the browser's language preference and redirects first-time visitors to their locale. Sensible idea, but the logic had a gap.

When someone lands on /pl/ for the first time with no lang cookie — say, following a link — the script read navigator.language, found en-US, set the cookie to en, and redirected them away from the page they'd explicitly navigated to.

The fix is obvious in retrospect: if the current URL is already on a non-default locale, the URL itself is the preference. Set the cookie to match and stop. No redirect. This also covers the HTTP dev case — the Secure cookie flag was silently dropping the cookie in non-HTTPS environments (DDEV's default), making the whole mechanism non-functional until you switched to HTTPS.

I also added a guard for a scenario I hadn't considered: a stale cookie for a locale that no longer exists on the site. Without it, removing a language from _site.yaml would redirect every visitor with an old cookie into an infinite redirect loop to a 404.

Search excerpts and double-escaping#

The 1.1.2 security review found an XSS in search: pagefind excerpts were being inserted into innerHTML without escaping. Fixed by wrapping them in esc().

Except pagefind excerpts contain <mark> highlight tags — that's how pagefind shows what matched. The fix broke highlights, turning <mark>term</mark> into literal <mark>term</mark> text. The right answer: pagefind content is author-controlled static HTML, not user input. The <mark> tags are injected by the search engine at build time, not by visitors. Remove esc() from the excerpt specifically, keep it everywhere else. Invisible until you notice the highlights aren't highlighting.

Security and hardening#

ImageMagick now runs through Symfony\Process with argv arrays instead of shell strings — exec() is gone. Turnstile validates the hostname in the siteverify response against your configured base_url, so tokens minted on a test or staging domain can't be replayed against production. JSON-LD output is hex-escaped, meaning </script> in a post title can no longer terminate the script block. The nginx security headers (X-Frame-Options, CSP, etc.) were missing from /assets/ and /media/ responses — location-level add_header was suppressing the inherited server-level headers.

/llms.txt#

A small addition: a /llms.txt route included in the static build, listing the most recent posts in a machine-readable format per locale. Configurable via llms_limit in _site.yaml, overridable per-theme via the @base Twig namespace. Static sites aren't traditionally easy for LLMs to navigate — this is a low-effort way to provide context to whoever (or whatever) reads it.

Breaking changes#

A few things changed in ways that require a one-line migration in local/src/:

• ContentItem::directoryKey() returns the full content path (pages/about not about), fixing silent URL collisions between same-named directories in different sections
• getTree() moved to ContentTreeProviderInterface — off ContentServiceInterface
• structured_data().blogPosting() takes a named map (was 13 positional arguments)
• lang_switch_url context key removed — use lang_switch
• docs/customization/old-template/ removed from the repo — retrieve from a v1.1.x tag if needed

Full migration guide: UPGRADE-1.2.md.

Links#

Full changelog: CHANGELOG.md.

Repository: GitHub / holas1337/notACMS — Apache 2.0.

Part 5 covered how Claude Code was used during the initial build — AGENTS.md as the AI's instruction manual, generating services and templates from conventions, translating content. This post covers what happens after: the site works, the build passes, but the architecture has rough edges. Three rounds of quality improvements, component extraction, and namespace reorganization — all driven by AI-assisted review cycles.

Why Iterate?#

The first working version prioritizes shipping. Get the content online, make the build pass, deploy to the Raspberry Pi. Technical debt accumulates naturally along the way: methods return associative arrays instead of value objects, services are injected as concrete classes instead of interfaces, templates grow into monoliths.

On a team, code review catches these patterns. On a solo project, there's nobody to review your pull requests. AI fills that gap — not as a rubber stamp, but as a systematic reviewer that reads every file and reports issues with line numbers.

The iteration cycle:

1. Ask the AI to audit for specific patterns (strict types, SOLID violations, DRY issues)
2. AI reads every PHP file, reports issues with file paths and line numbers
3. Plan the fixes in a .plans/ file with checkboxes
4. Implement phase by phase, verify with ddev code-check after each
5. Repeat with the next quality focus

Each round has a specific scope. Trying to fix everything at once leads to noisy diffs and missed regressions. Focused rounds produce reviewable, verifiable changes.

Round 1 — Value Objects Over Arrays#

The first round targeted the project's own rule: "Never return associative arrays for complex data."

The Problem#

MarkdownParser::parse() returned an array:

// Before
public function parse(string $markdown): array
{
    // ...
    return [
        'frontMatter' => $frontMatter,
        'html' => $html,
    ];
}

// Consumer
$result = $this->parser->parse($content);
$frontMatter = $result['frontMatter'];  // no type safety
$html = $result['html'];               // typo = silent bug

Same pattern for adjacent post navigation — ContentTree::getAdjacentPosts() returned ['prev' => $post, 'next' => $post].

The issues: no type safety, no IDE autocomplete, PHPStan can't catch a typo in $result['htlm'].

The Fix#

final readonly class ParsedMarkdown
{
    /** @param array<string, mixed> $frontMatter */
    public function __construct(
        public array $frontMatter,
        public string $html,
    ) {
    }
}

final readonly class AdjacentPosts
{
    public function __construct(
        public ?ContentItem $prev,
        public ?ContentItem $next,
    ) {
    }
}

Now the parser returns ParsedMarkdown, the consumer accesses $parsed->frontMatter and $parsed->html, and PHPStan catches any property name typo at analysis time.

Seven value objects were created or moved in this round:

All are readonly, use constructor property promotion, and live in src/Content/ValueObject/.

Round 2 — Interfaces for Everything#

The second round enforced another project rule: "Every injectable class in src/Service/ must have a corresponding interface."

The Problem#

Two services were injected as concrete classes:

// Before
public function __construct(
    private readonly ContentTreeBuilder $builder,
    private readonly MarkdownParser $parser,
) {
}

This worked, but it violated the dependency inversion principle. The rest of the codebase already injected via interfaces (ContentServiceInterface, ImageResizerInterface). These two were the exceptions.

The Fix#

interface MarkdownParserInterface
{
    public function parse(string $markdown): ParsedMarkdown;
}

interface ContentTreeBuilderInterface
{
    public function build(string $locale): ContentTree;
}

// After
public function __construct(
    private readonly ContentTreeBuilderInterface $builder,
    private readonly MarkdownParserInterface $parser,
) {
}

The concrete classes implement the interfaces. Symfony's autowiring handles the binding. The rule is now enforced everywhere: 12 service interfaces across 4 subdirectories.

src/Service/
├── Content/
│   ├── ContentServiceInterface + ContentService
│   ├── ContentTreeBuilderInterface + ContentTreeBuilder
│   ├── MarkdownParserInterface + MarkdownParser
│   ├── SidebarDataProviderInterface + SidebarDataProvider
│   └── TranslationMapBuilderInterface + TranslationMapBuilder
├── Image/
│   ├── ImageResizerInterface + ImageResizer
│   └── ResponsiveImageServiceInterface + ResponsiveImageService
├── Preview/
│   ├── DraftPreviewServiceInterface + DraftPreviewService
│   └── ScheduledPreviewServiceInterface + ScheduledPreviewService
├── SiteConfigServiceInterface + SiteConfigService
└── TurnstileValidatorInterface + TurnstileValidator

A secondary rule from this round: constants belong in the interface, not the concrete class. The concrete class inherits them via self::CONSTANT_NAME.

Round 3 — Eliminating Hardcoded Values#

The third round targeted a subtler problem: values that work today but drift tomorrow.

Hardcoded URLs in Templates#

The language switcher had hardcoded archive paths:

{# Before — breaks if routing changes #}
{% set url = locale is same as('pl') ? '/archive/' : '/pl/archiwum/' %}

{# After — uses named routes #}
{% set url = path('blog_archive_' ~ other, {year: archive_year, month: '%02d'|format(archive_month)}) %}

Same pattern in BlogController for cross-locale tag switching — hardcoded /pl/tag/ and /blog/ replaced with $this->generateUrl('blog_tag_'.$otherLocale, ...).

Hardcoded Image Breakpoints#

The responsive image template had srcset widths hardcoded as strings. If the IMAGE_VARIANT_WIDTHS environment variable changed, the template would reference files that don't exist:

{# Before — template must match env config manually #}
srcset="...640w.webp 640w, ...960w.webp 960w, ..."

The fix: inject variant widths as a Twig global from SiteConfigExtension, then generate srcset dynamically. One source of truth for breakpoints.

Magic Numbers#

Response::HTTP_BAD_REQUEST replaced a hardcoded 400. Small change, but consistent with the principle: every literal value is a future bug where someone changes the logic but not the number.

Twig Component Extraction#

Between quality rounds, a separate effort extracted reusable components from monolithic templates.

The About Page#

The about page was the worst offender — 146 lines mixing profile markup, expertise cards, skill pills, open source projects, and recommendation blockquotes in one template.

After extraction:

{# about.html.twig — clean and scannable #}
{% block body %}
<article class="page-content" data-pagefind-body>
    {{ include('components/about_profile.html.twig', {
        author: site_author,
        role: 'about.role'|trans,
        headline: 'about.headline'|trans
    }) }}

    <section class="about-section">
        <h2>{{ 'about.expertise_title'|trans }}</h2>
        {{ include('components/expertise_grid.html.twig', { expertise: expertise_items }) }}
    </section>

    {{ include('components/skills_pills.html.twig', { skills: ..., labels: ... }) }}
    {{ include('components/opensource_grid.html.twig', { projects: os_projects }) }}

    {% for rec in site_author.recommendations %}
        {{ include('components/recommendation_card.html.twig', { rec: rec, ... }) }}
    {% endfor %}

    {{ include('components/about_cta.html.twig', { text: ..., url: ..., label: ... }) }}
</article>
{% endblock %}

Eight components extracted from one page: about_profile, expertise_grid, skills_pills, opensource_grid, recommendation_card, about_cta, plus error_terminal and coming_soon_terminal from other pages.

The Styleguide Benefit#

holas.pl has a dev-only styleguide at /styleguide/ that demonstrates all UI components. Before extraction, the styleguide hardcoded its own markup to show each component — which drifted from the real templates when changes were made.

After extraction, both the real site and the styleguide include the same component files:

{# styleguide.html.twig #}
{{ include('components/recommendation_card.html.twig', { rec: demo_recommendation, ... }) }}

{# about.html.twig #}
{{ include('components/recommendation_card.html.twig', { rec: rec, ... }) }}

Change the component once, both update automatically. The styleguide went from a manual sync burden to zero maintenance.

The component count grew from ~15 to 25 across these extractions.

Namespace Reorganization#

The value object and interface work created enough files that flat namespaces became crowded:

# Before
src/Content/AdjacentPosts.php
src/Content/ArchiveMonth.php
src/Content/CategoryCount.php
src/Content/CardLayout.php
src/Service/ContentService.php
src/Service/ImageResizer.php
src/Service/DraftPreviewService.php

# After
src/Content/ValueObject/AdjacentPosts.php
src/Content/ValueObject/ArchiveMonth.php
src/Content/ValueObject/CategoryCount.php
src/Content/Enum/CardLayout.php
src/Service/Content/ContentService.php
src/Service/Image/ImageResizer.php
src/Service/Preview/DraftPreviewService.php

CardLayout moved to Enum/ — it's a backed PHP enum for post card layout variants:

enum CardLayout: string
{
    case Top = 'layout-top';
    case Right = 'layout-right';
    case Text = 'layout-text';
    case Left = 'layout-left';

    /** @return list<string> */
    public static function cycle(): array
    {
        return array_map(fn (self $l) => $l->value, self::cases());
    }
}

Type-safe, auto-completable, impossible to typo. The cycle() method returns layout values that the blog listing template rotates through for visual variety.

The reorganization touched 46 files in a single commit — every use statement referencing a moved class needed updating. This is exactly the kind of mechanical refactoring where AI shines: change the namespace, update all imports, verify nothing broke. The human decides the target structure; the AI handles the tedious part.

The AI Workflow for Refactoring#

The practical workflow behind these rounds:

Step 1: Scoped audit. Ask Claude Code to review all PHP files for a specific category of issues. Not "find all problems" — too vague. Instead: "check every file in src/ for methods returning associative arrays instead of value objects." The AI reads every file and reports specific issues with file paths and line numbers.

Step 2: Plan. Write a .plans/ file documenting what needs to change, which files are affected, and the implementation steps as checkboxes. The plan is the source of truth — not a summary of intent, but a detailed implementation spec.

Step 3: Phase-by-phase implementation. Execute one phase, run ddev code-check (PHP CS Fixer + PHPStan level 6), verify the build passes with ddev build. Move to the next phase.

Step 4: Verify. After the round is complete, run the full quality suite. The numbers for holas.pl:

$ ddev code-check
PHP CS Fixer: Found 0 of 53 files that can be fixed
PHPStan: [OK] No errors (53 files, level 6)

53 PHP files, zero CS Fixer issues, zero PHPStan errors. The automated tools confirm what the review intended.

What AI Does Well in Refactoring#

• Systematic file-by-file review: reads 53 files and reports every violation of a pattern. Humans skim; AI doesn't.
• Mechanical refactoring: renaming namespaces across 46 files, updating import statements, moving constants from concrete classes to interfaces.
• Consistency checks: verifying that every service has an interface, every value object is readonly, every comparison uses Yoda style — across the entire codebase.

What AI Needs Humans For#

• Deciding which abstractions to introduce: should SidebarData be one value object or four separate return values? The AI can implement either; the human decides which is cleaner.
• Judging when an interface adds value vs. overhead: a service used in one place doesn't need an interface for testing flexibility. The project rule says "every service gets an interface" — but the human decided that rule, and the human could change it.
• Knowing when to stop: three quality rounds is enough. The codebase is clean. A fourth round of micro-optimizations would be over-engineering.

The AGENTS.md Feedback Loop#

Each round discovers patterns worth documenting. Round 1 added the value object convention to AGENTS.md. Round 2 added the interface naming rule. Round 3 added the "no hardcoded URLs" principle.

The next time Claude Code generates a new service, it follows all three rounds' learnings from the start. The first version of a service now ships with an interface, uses value objects for complex returns, and references named routes instead of hardcoded paths. The iteration compounds.

The Result#

After three rounds, the codebase state:

• 53 PHP files, all with declare(strict_types=1), explicit return types, Yoda conditions
• 12 service interfaces — every service injected via interface
• 7 value objects — no associative arrays for multi-field returns
• 1 enum — type-safe card layout variants
• 25 Twig components — reusable, shared between site and styleguide
• 0 PHP CS Fixer issues, 0 PHPStan errors at level 6
• 0 hardcoded URLs in templates or controllers

None of this was in the first version. The first version had concrete injections, array returns, monolithic templates, and hardcoded locale checks. It worked — the site built, the pages rendered, users could read blog posts.

The difference is maintainability. Adding the multilanguage system (previous post) was straightforward because the codebase was already clean: interfaces for everything, typed returns, clear separation of concerns. Refactoring a clean codebase is fast. Refactoring a messy one is slow and error-prone.

Ship first. Iterate second. Use AI for the systematic work that a solo developer would skip — or postpone until it becomes a problem. Three focused rounds, each building on the last, each verified by automated tools. The code is measurably better, and the investment is a few hours of review cycles, not a week-long rewrite.

Adding a second language to a Symfony site usually means duplicating controllers, hardcoding URL prefixes, and scattering locale checks everywhere. holas.pl takes a different approach: locale config lives in one YAML file, routes are generated from a custom PHP attribute, and translations are linked by the filesystem — not by explicit keys.

The Problem with Hardcoded Locales#

The first working version of holas.pl's multilanguage support had around 30 places with patterns like this:

#[Route('/blog/', name: 'blog_list_en')]
public function listEn(int $page = 1): Response
{
    return $this->renderList('en', $page);
}

#[Route('/pl/wpisy/', name: 'blog_list_pl')]
public function listPl(int $page = 1): Response
{
    return $this->renderList('pl', $page);
}

Every route had two methods — one per locale. The real controller logic lived in a private render*() method; the public methods were pure boilerplate that set the locale and delegated. Seven controllers × two locales = 28 methods doing nothing useful.

Adding a third language would mean adding 14 more methods, plus updating templates, the locale listener, and every place that checked 'pl' === $locale. The code didn't scale.

Single Source of Truth — _site.yaml#

The fix starts with centralizing the locale list. Instead of spreading locale knowledge across PHP files, everything lives in content/_site.yaml:

site:
  locales:
    en:
      label: "English"
      og_locale: en_US
      date_format: "M d, Y"
    pl:
      label: "Polski"
      og_locale: pl_PL
      font_preload: fonts/inter-normal-latin-ext.woff2
      date_format: "d.m.Y"

Order matters: the first key is the default locale. Each locale carries its own metadata — og_locale for Open Graph tags, date_format for template rendering, font_preload for Latin Extended characters that only Polish needs.

SiteConfigService reads this file once, caches it, and provides it to the entire application:

interface SiteConfigServiceInterface
{
    /** @return string[] Ordered locale codes, first = default */
    public function getLocales(): array;

    public function getDefaultLocale(): string;

    /** @return array<string, mixed> Config for a single locale */
    public function getLocaleConfig(string $locale): array;
}

Every controller, listener, and route loader injects this interface. No PHP code imports a locale list from framework.yaml or hardcodes ['en', 'pl'].

Custom Route Attribute — #[LocalizedRoute]#

The key innovation is a custom PHP attribute that replaces duplicate route methods:

#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
final class LocalizedRoute
{
    public function __construct(
        public readonly string $name,
        public readonly string $path,
        public readonly array $requirements = [],
        public readonly array $methods = [],
        public readonly int $priority = 0,
    ) {
    }
}

The attribute defines a route for the default locale only. A custom LocalizedRouteLoader scans all controllers, finds #[LocalizedRoute] attributes, and generates {name}_{locale} routes for every configured locale:

#[LocalizedRoute('blog_list', path: '/blog/')]
#[LocalizedRoute('blog_list_paginated', path: '/blog/page/{page}/', requirements: ['page' => '\d+'])]
public function list(string $locale, int $page = 1): Response
{
    // one method handles all locales
}

This single method replaces the two listEn() / listPl() methods from before. The loader generates four routes from the two attributes: blog_list_en, blog_list_pl, blog_list_paginated_en, blog_list_paginated_pl.

The total across all controllers: 28 methods became 14. Every removed method was pure boilerplate.

Route Resolution#

The loader needs to know that /blog/ is the English path but /pl/wpisy/ is the Polish one. A three-step resolution algorithm handles this:

private function resolvePath(
    string $name, string $defaultPath,
    string $locale, string $defaultLocale,
    array $overrides,
): string {
    if ($locale === $defaultLocale) {
        return $defaultPath;                          // EN: /blog/
    }

    if (isset($overrides[$name][$locale])) {
        return '/'.$locale.$overrides[$name][$locale]; // PL: /pl/wpisy/
    }

    return '/'.$locale.$defaultPath;                   // fallback: /pl/blog/
}

1. Default locale — use the attribute's path as-is: /blog/
2. Override exists — prepend /{locale} + the translated path from _routes.yaml
3. No override — prepend /{locale} + the default path: /pl/blog/

_routes.yaml — Translated Path Segments#

Only routes with translated URL segments need overrides. Routes without entries get auto-prefixed:

routes:
  blog_list:
    pl: /wpisy/
  blog_list_paginated:
    pl: /wpisy/strona/{page}/
  blog_category:
    pl: /wpisy/{category}/
  blog_archive:
    pl: /archiwum/{year}/{month}/
  contact:
    pl: /kontakt/
  search:
    pl: /szukaj/

blog_tag has no entry, so blog_tag_pl gets the auto-prefix: /pl/tag/{tag}/. Adding German would mean adding de: entries to the routes that need translation, and nothing for routes where the English path is fine.

Two URL Resolution Patterns#

Templates need to link to pages. There are two fundamentally different cases:

Structural routes come from the router — they're generated by LocalizedRouteLoader and have {name}_{locale} names. Content URLs come from frontmatter slug fields — each en.md and pl.md defines its own URL.

{# Structural: the router knows the path #}
<a href="{{ path('blog_list_' ~ locale) }}">Blog</a>
<a href="{{ path('contact_' ~ locale) }}">Contact</a>

{# Content: look up by directory key #}
<a href="{{ content_url('about', locale) }}">About</a>
<a href="{{ content_url('privacy-policy', locale) }}">Privacy</a>

content_url() is a custom Twig function that looks up a ContentItem by its directory key — the folder name — and returns the URL from its frontmatter. This replaces the old approach of hardcoding slugs per locale in templates.

Co-located Content — The Filesystem as Translation Link#

Content files for the same post live in the same directory:

content/blog/tutorials/my-post/
    en.md  → slug: "blog/my-post"
    pl.md  → slug: "pl/blog/moj-wpis"
    files/ → images served at /media/my-post/

Both files in the same folder are automatically linked as translations. No explicit translation_key field needed. ContentItem::directoryKey() returns the folder name ("my-post"), and TranslationMapBuilder uses it to build a lookup table:

public function build(array $trees): array
{
    $map = [];

    foreach ($trees as $locale => $tree) {
        foreach ($tree->getAllItems() as $item) {
            $key = $item->directoryKey();
            if (null === $key || '' === $item->url()) {
                continue;
            }
            $map[$key][$locale] = $item->url();
        }
    }

    return $map;
}

The result: $map['my-post']['en'] = '/blog/my-post/', $map['my-post']['pl'] = '/pl/blog/moj-wpis/'. This map drives hreflang <link> tags in the HTML head and the language switcher.

Not every post needs both locale files. A post with only en.md won't appear in Polish listings, and the language switcher falls back to the other language's homepage.

Language Switcher — Fallback Chain#

The language switcher seems simple — link to the same page in the other language. In practice, it needs to handle partial translations, tag pages, archive pages, and paginated listings. The fallback chain:

{# 1. Try translation map (page exists in other locale) #}
{% if tk and translation_map[tk][other] is defined %}
    {% set url = translation_map[tk][other] %}
{% endif %}

{# 2. Try controller-provided URL (tag pages) #}
{% if url is null and lang_switch_url is defined %}
    {% set url = lang_switch_url %}
{% endif %}

{# 3. Fallback: archive, paginated listing, or homepage #}
{% if url is null %}
    {% if filter_type is same as('archive') and archive_year is defined %}
        {% set url = path('blog_archive_' ~ other, {year: ..., month: ...}) %}
    {% elseif current_page > 1 %}
        {% set url = path('blog_list_paginated_' ~ other, {page: current_page}) %}
    {% else %}
        {% set url = path('home_' ~ other) %}
    {% endif %}
{% endif %}

Tag pages get special treatment: BlogController translates the tag slug between locales (e.g., security → bezpieczenstwo) and checks whether the other locale has any posts with that tag. If yes, the switcher links to the translated tag page. If no, it falls back to the other locale's blog listing.

On the client side, locale-redirect.js handles first-visit language detection. It reads navigator.language, matches it against the configured locale list (from a data-locales attribute on <html>), and stores the preference in a cookie. On return visits, it redirects to the saved preference. The locale list isn't hardcoded in JavaScript — it comes from the same _site.yaml config, passed through Twig.

Locale Detection#

LocaleListener runs at priority 8 — after Symfony's built-in locale listeners — and detects locale from the URL path:

private function detectLocale(string $path): string
{
    $defaultLocale = $this->siteConfig->getDefaultLocale();

    foreach ($this->siteConfig->getLocales() as $locale) {
        if ($locale === $defaultLocale) {
            continue;
        }

        if (str_starts_with($path, '/'.$locale.'/') || '/'.$locale === $path) {
            return $locale;
        }
    }

    return $defaultLocale;
}

No hardcoded /pl/ check. It iterates the configured locales dynamically. Adding a new locale to _site.yaml is enough for the listener to start detecting it.

Adding a New Language — Zero PHP Changes#

This is the payoff. Adding German to holas.pl requires:

1. content/_site.yaml — add a de: entry with label, og_locale, date_format
2. content/_routes.yaml — add de: overrides for translated route segments
3. translations/messages.de.yaml — German UI strings (nav labels, button text, etc.)
4. content/_tags.yaml — German tag translations
5. Content files — create de.md alongside en.md and pl.md for posts that should exist in German

No PHP files touched. No Twig templates edited. No controller methods added. The route loader generates German routes automatically. The locale listener detects /de/ paths. The language switcher renders a dropdown instead of a toggle link. The translation map includes German URLs.

The 28 locale-specific controller methods and 30 hardcoded locale checks from the first version would have meant editing 20+ files to add German. The configuration-driven approach means editing 5 config files and creating content.

The architecture decisions that make this work — SiteConfigService as the single locale authority, LocalizedRouteLoader generating routes from attributes, co-located content as the translation link — are the kind of decisions that seem like over-engineering when you only have two languages. They're not. They're the difference between "adding a language is a week of work" and "adding a language is an afternoon of config."

Next post covers how the codebase improved through iterative quality rounds — value objects, interfaces, component extraction — with AI handling the systematic review work.

On a static site, there's no server handling requests and no application layer checking the clock. Both features require deliberate implementation — and the right place for both is the build step.

Responsive Images#

The Problem#

Featured images on holas.pl are 1280×720px WebP. On a desktop browser, that's the right size. On a mobile screen 400px wide, the browser downloads a 1280-pixel image to display at 400 pixels — roughly 10× the data actually needed.

The solution is srcset + sizes: tell the browser what image variants exist and how large the image renders at each viewport width, then let it pick the right file. The static site constraint: every variant must exist as a file before any request arrives. There's no resize-on-demand.

Build-Time Variant Generation#

BuildStaticSiteCommand generates variants after copying media files to public/static/media/. It scans for .webp files, reads each file's actual dimensions with getimagesize(), and generates variants via ImageResizerInterface::resize():

$variantWidths = $this->responsiveImageService->getVariantWidths($width);

foreach ($variantWidths as $variantWidth) {
    $this->imageResizer->resize(
        $filePath,
        $dir . '/' . $baseName . '-' . $variantWidth . 'w.webp',
        $variantWidth,
    );
}

ImageResizer::resize() calls ImageMagick:

magick source.webp -resize 640x -quality 82 -strip -define webp:method=6 source-640w.webp

-resize 640x scales to 640px wide, preserving aspect ratio. -quality 82 -strip -define webp:method=6 matches the production image settings and removes EXIF data.

Variant filenames follow a convention: image.webp → image-640w.webp, image-960w.webp. The build skips files that already end in -640w or -960w to avoid re-processing previously generated variants.

ResponsiveImageService#

Two places need to know which variants exist: BuildStaticSiteCommand (which files to generate) and SrcsetExtension (which filenames to reference in HTML). Rather than duplicating the breakpoint logic, both inject ResponsiveImageServiceInterface:

interface ResponsiveImageServiceInterface
{
    /** @return int[] */
    public function getVariantWidths(int $sourceWidth): array;

    public function buildSrcset(string $src, int $sourceWidth): string;
}

The implementation:

public function getVariantWidths(int $sourceWidth): array
{
    if (960 < $sourceWidth) {
        return [640, 960];
    }
    if (640 < $sourceWidth) {
        return [640];
    }

    return [];
}

public function buildSrcset(string $src, int $sourceWidth): string
{
    $base = substr($src, 0, -5);  // strip .webp

    if (960 < $sourceWidth) {
        return sprintf('%s-640w.webp 640w, %s-960w.webp 960w, %s 1280w', $base, $base, $src);
    }
    if (640 < $sourceWidth) {
        return sprintf('%s-640w.webp 640w, %s 960w', $base, $src);
    }

    return '';
}

Images ≤640px wide get no variants — the original is already small enough. buildSrcset() returns '' to signal that no srcset attribute is needed.

If breakpoints ever need to change, there's one place to update.

Featured Image Component#

The responsive_img.html.twig component renders featured images with srcset hardcoded to the 640/960/1280 breakpoints:

<img src="{{ src }}"
     srcset="{{ src|replace({'.webp': '-640w.webp'}) }} 640w,
             {{ src|replace({'.webp': '-960w.webp'}) }} 960w,
             {{ src }} 1280w"
     sizes="{{ sizes|default('(max-width: 48em) 100vw, 720px') }}"
     alt="{{ alt }}"
     width="{{ width|default(1280) }}"
     height="{{ height|default(720) }}">

sizes="(max-width: 48em) 100vw, 720px" tells the browser: below 48em viewport width, the image fills the full viewport; above that, it's constrained to 720px (the content column width). The browser uses this to pick the right srcset entry before downloading anything.

width and height are explicit for Cumulative Layout Shift prevention — the browser reserves the exact space for the image before it loads. Without them, the layout shifts when the image arrives.

Inline Content Images#

Markdown images inside post body render as plain <img> tags. No srcset. A post with a diagram or screenshot at /media/post-dir/diagram.webp would serve the full-size image to mobile too.

The srcset_media Twig filter handles this. In post.html.twig:

{{ content.htmlContent|srcset_media|raw }}

SrcsetExtension::srcsetMedia() finds all /media/*.webp <img> tags with a regex, reads the source image width from the content directory (not the static output), and injects srcset and sizes:

$result = preg_replace_callback(
    '/<img(\s[^>]*)src="(\/media\/[^"]+\.webp)"([^>]*)>/i',
    function (array $matches): string {
        $src = $matches[2];

        // skip if srcset already present
        if (str_contains($matches[1], 'srcset') || str_contains($matches[3], 'srcset')) {
            return $matches[0];
        }

        $width = $this->getSourceWidth($src);
        if (null === $width) {
            return $matches[0];
        }

        $srcset = $this->responsiveImageService->buildSrcset($src, $width);
        if ('' === $srcset) {
            return $matches[0];  // no variants generated — leave as-is
        }

        return sprintf(
            '<img%ssrc="%s" srcset="%s" sizes="(max-width: 48em) 100vw, 720px"%s>',
            $matches[1], $src, $srcset, $matches[3],
        );
    },
    $html,
);

getSourceWidth() looks up the actual source file under content/ (not public/static/), since that's where the original dimensions live. Images with no variants — small inline screenshots ≤640px wide — are left unchanged.

Scheduled Posts#

The Problem#

A post with date: 2026-06-01 shouldn't appear in listings until June 1. The site rebuilds nightly, so a future-dated post simply won't appear in ContentTree::getAllPosts() until the build after its publish date. That part is automatic.

The URL is a different problem. If someone shares the link before the post is live, they get a 404. Better to serve a "coming soon" page at the exact URL the post will occupy.

ContentItem::isScheduled()#

public function isScheduled(): bool
{
    $date = $this->date();

    return null !== $date && $date > new \DateTimeImmutable();
}

One comparison. isDraft() takes priority — a post with both draft: true and a future date is treated as a draft and excluded from all builds.

Static Build: Coming-Soon Pages#

BuildStaticSiteCommand::collectRoutes() collects two categories of post URLs:

• Published posts via ContentTree::getAllPosts() — rendered with the full post template
• Scheduled posts via ContentTree::getScheduledPosts() — rendered with the coming-soon template

Both produce static HTML files at their eventual URL. When the post's date passes and the next build runs, isScheduled() returns false, the URL moves to the published list, and the full post HTML replaces the coming-soon HTML. No redirect, no special handling needed.

The Coming-Soon Page#

The coming-soon template uses the same green terminal aesthetic as the error pages:

{% block robots %}<meta name="robots" content="noindex, nofollow">{% endblock %}

<pre class="coming-soon-terminal"><code>
<span class="coming-soon-terminal__code">COMING_SOON</span>
{% if days_until <= 14 %}
<span class="coming-soon-terminal__text">{{ post.title }}</span>
<span class="coming-soon-terminal__date">Publishing: {{ post.date|date('Y-m-d') }}</span>
{% endif %}
</code></pre>

noindex, nofollow — the page handles direct links gracefully without ranking or passing link equity.

If the publish date is ≤14 days away, the title and date are shown. Further out: just the COMING_SOON code, no date. The 14-day threshold avoids making a public commitment to a specific date that might slip.

Dev Preview Toolbar#

In production, scheduled posts are invisible — they appear only as coming-soon pages at their URLs, not in any listing.

In development, you're writing scheduled post content and need to see it. The Symfony profiler toolbar gets a calendar icon toggle ("Scheduled preview"). When on, scheduled posts appear in listings with a [PLANNED] badge:

{% if post.isDraft() %}
    <span class="post-card-badge post-card-badge--draft">[DRAFT]</span>
{% elseif post.isScheduled() %}
    <span class="post-card-badge post-card-badge--planned">[PLANNED]</span>
{% else %}
    {# pinned / new / recently updated badges #}
{% endif %}

Toggle it off to preview what production will look like. The mechanism mirrors the existing draft preview toggle exactly — same session key pattern (scheduled_preview), same controller structure.

The Build-Step Pattern#

Both features follow the same approach: push work into the build step, keep the serving layer simple.

Responsive images: generate all variants at build time. A few seconds of ImageMagick calls during ddev build saves bandwidth on every mobile page load for the lifetime of the post.

Scheduled posts: pre-render coming-soon pages rather than handling "not yet published" at request time. The static file exists, nginx serves it, no PHP involved.

The build runs once. nginx serves the result to every visitor. Any work that can move to the build step is work the server doesn't have to do.

The build pipeline that makes this possible is covered in Part 2 of this series. The two-container production setup that runs it is in Part 3.

What Lighthouse SEO doesn't check: whether your structured data is complete, how your page renders as a social card, what feed readers see when they subscribe, whether Google can find and index your images without crawling every page.

This post covers the implementation layer beneath that score.

Structured Data#

Structured data is JSON-LD in a <script type="application/ld+json"> block. It tells search engines what a page is, not just what it says. holas.pl uses four schema types.

WebSite + SearchAction#

Every page carries a WebSite schema identifying the site and its search endpoint:

{
    "@context": "https://schema.org",
    "@type": "WebSite",
    "name": "holas.pl",
    "url": "https://holas.pl",
    "author": {
        "@type": "Person",
        "name": "Paweł Holik",
        "url": "https://holas.pl"
    },
    "potentialAction": {
        "@type": "SearchAction",
        "target": {
            "@type": "EntryPoint",
            "urlTemplate": "https://holas.pl/search/?q={search_term_string}"
        },
        "query-input": "required name=search_term_string"
    }
}

The potentialAction enables the Google Sitelinks search box — a search input that appears directly in the Google result for the site. It maps to the Pagefind-powered search at /search/. This is one extra field on an existing schema with no downside.

BlogPosting#

Blog posts carry the richest schema. Beyond headline, description, url, and datePublished, several fields matter for how Google represents the content:

• inLanguage — "en" or "pl", needed for multilingual indexing
• wordCount — computed at parse time by ContentItem::wordCount() (strips HTML tags, counts tokens)
• articleSection — the post category
• keywords — the post tags as a comma-separated string
• image — a nested ImageObject with url, width, and height

{
    "@type": "BlogPosting",
    "headline": "Post title",
    "inLanguage": "en",
    "wordCount": 842,
    "articleSection": "tutorials",
    "keywords": "seo, symfony, static-site",
    "image": {
        "@type": "ImageObject",
        "url": "https://holas.pl/media/post-dir/featured.webp",
        "width": 1280,
        "height": 720
    }
}

Without ImageObject, Google treats the featured image as an unknown attachment. With width and height explicitly set, the image becomes eligible for large preview cards in Google Discover and Search.

BreadcrumbList#

Google can replace the raw URL in search results with breadcrumb navigation — "Home / Blog / tutorials / Post Title". This requires BreadcrumbList schema.

It's rendered in breadcrumb.html.twig alongside the HTML nav. Each crumb is a ListItem with position and item (URL). The last item — the current page — has a name but no URL:

{
    "@type": "BreadcrumbList",
    "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://holas.pl/" },
        { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://holas.pl/blog/" },
        { "@type": "ListItem", "position": 3, "name": "tutorials", "item": "https://holas.pl/blog/tutorials/" },
        { "@type": "ListItem", "position": 4, "name": "Post Title" }
    ]
}

CollectionPage + ItemList#

Category, tag, and archive listing pages carry CollectionPage with a nested ItemList. Each entry has a position and url. Only rendered when the listing has posts — an empty category page doesn't get it.

{
    "@type": "CollectionPage",
    "name": "tutorials | holas.pl",
    "mainEntity": {
        "@type": "ItemList",
        "numberOfItems": 5,
        "itemListElement": [
            { "@type": "ListItem", "position": 1, "url": "https://holas.pl/blog/post-name/" }
        ]
    }
}

Social Sharing#

OpenGraph Image Dimensions#

Without og:image:width and og:image:height, platforms like LinkedIn and Slack must fetch the image before rendering the preview card. With them, the card renders immediately:

<!-- blog post (WebP, 1280×720) -->
<meta property="og:image:width" content="1280">
<meta property="og:image:height" content="720">
<meta property="og:image:type" content="image/webp">

<!-- other pages (default og:image, JPG, 1200×630) -->
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:type" content="image/jpeg">

The conditional is in base.html.twig: if a content object with an image is defined (blog post or page with featured image), use the WebP dimensions; otherwise use the defaults for og-default.jpg. The JPG exception exists because og:image is consumed by external crawlers that don't reliably support WebP.

Twitter/X Card#

The base twitter:card type was already present. Three explicit fields were added:

<meta name="twitter:title" content="...">
<meta name="twitter:description" content="...">
<meta name="twitter:image" content="...">

Without them, Twitter/X falls back to OG properties. Explicit meta removes that dependency — if OG processing has any issue, Twitter Card still has the correct values.

article:* Meta#

Blog posts get article-specific OG meta in post.html.twig's og_article_meta block:

<meta property="article:published_time" content="2026-06-21T00:00:00+00:00">
<meta property="article:modified_time" content="2026-06-21T00:00:00+00:00">
<meta property="article:author" content="Paweł Holik">
<meta property="article:section" content="tutorials">
<meta property="article:tag" content="seo">
<meta property="article:tag" content="symfony">
<meta property="article:tag" content="static-site">

article:tag is one element per tag — not comma-separated. The Open Graph spec requires separate elements for multi-value properties.

Feed Readers#

content:encoded#

The default RSS <description> contains only the post excerpt — first paragraph, HTML stripped. content:encoded carries the full post HTML in a CDATA block:

<content:encoded><![CDATA[<p>Full post content...</p>]]></content:encoded>

This requires xmlns:content="http://purl.org/rss/1.0/modules/content/" on the root <rss> element. Feed readers like NetNewsWire, Reeder, and Feedbin render content:encoded inline — subscribers read the full article without leaving their reader.

category and media:content#

Each RSS item gets <category> elements for the post category and each tag:

<category>tutorials</category>
<category>seo</category>
<category>symfony</category>

media:content attaches the featured image as a typed media attachment:

<media:content url="https://holas.pl/media/post-dir/featured.webp"
               medium="image" type="image/webp" width="1280" height="720"/>

Feed readers that render inline images (Feedly, Inoreader) use this for the post thumbnail in the feed list. This requires xmlns:media="http://search.yahoo.com/mrss/" on the <rss> element.

Crawling Signals#

max-image-preview:large#

The default robots behavior limits image previews in Google Search and Discover to standard size. max-image-preview:large opts into full-size previews. Combined with max-snippet:-1 (no restriction on text snippet length), this is the default robots meta on every page:

<meta name="robots" content="max-image-preview:large, max-snippet:-1">

Implemented as the default {% block robots %} in base.html.twig. Child templates override the block for pages that shouldn't be indexed — coming-soon pages use noindex, nofollow, the search page uses noindex.

Image Sitemap#

The standard sitemap lists page URLs. The image sitemap adds <image:image> blocks, giving Google direct visibility into image locations and alt text without crawling every page first:

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
    <url>
        <loc>https://holas.pl/blog/post-name/</loc>
        <image:image>
            <image:loc>https://holas.pl/media/post-dir/featured.webp</image:loc>
            <image:title>Alt text from image_alt frontmatter</image:title>
        </image:image>
    </url>

image:title comes from the image_alt frontmatter field — the same text used in the HTML alt attribute. Both the xmlns:image namespace and the image:image block are in sitemap.xml.twig.

What Changed#

The Lighthouse SEO score was 100 before these changes. It's still 100 after them. That score measures the technical floor: crawlability, meta tags, mobile-friendliness.

The changes above operate at a different level. Structured data shapes how search engines represent content in rich results. Explicit social meta ensures correct rendering without relying on platform fallback logic. RSS extensions let subscribers read full posts in their reader. The image sitemap gives Google image visibility without requiring a crawl of every page.

None of it is architecturally complex — most of it is Twig template additions and namespace declarations. The constraint is discipline: every field needs a real value from frontmatter, not a placeholder.

The architecture that makes all of this straightforward is covered in Part 2 of this series — the static generation pipeline that produces complete HTML for every page.

This post goes through what actually drives each number. Most of it isn't optimisation work — it's a side effect of how the site is built.

Performance#

The main reason the performance score is 100 is that nginx serves pre-rendered HTML files with no PHP involved. There is no database query, no template rendering, no framework bootstrap on every request. A file comes off disk and goes to the client. A Raspberry Pi 5 handles this without breaking a sweat.

Everything else follows from there:

Assets are hashed and immutable. JavaScript and CSS files compiled by Symfony's AssetMapper get a content hash in the filename (app-a1b2c3d4.css). nginx serves them with Cache-Control: public, max-age=31536000, immutable — one year, no revalidation. On repeat visits, the browser serves everything from cache. On deploy, the hash changes and the new file is fetched.

JavaScript is minimal and non-blocking. The site uses native ES module imports via a browser-native importmap — no bundler, no webpack, no jQuery. There are seven small JS files: app.js, contact.js, cookie-banner.js, lightbox.js, locale-redirect.js, nav-toggle.js, tagline.js. None of them block rendering. Search is powered by Pagefind, a WASM-based static search index that loads lazily — only on the search page, only when needed.

Images are WebP. Featured images are stored as WebP at 1280×720. No large uncompressed JPEGs.

No render-blocking resources. There is no <link rel="stylesheet"> to an external font CDN, no synchronous third-party script loaded in <head>. The CSS is compiled locally and served as a hashed asset.

Accessibility#

<html lang> is set per locale. Every page has the correct language attribute — lang="en" for English pages, lang="pl" for Polish. This is set in the base Twig template based on the current locale, not hardcoded.

Semantic HTML throughout. The layout uses <nav>, <main>, <article>, <aside>, <footer> — not a sequence of <div> elements. Headings follow a logical hierarchy: one <h1> per page, <h2> for top-level sections, <h3> below that.

Color contrast passes. The site uses a Monokai-derived dark palette: #F8F8F2 text on #242424 background. That's a contrast ratio of 15.5:1, well above the WCAG AA threshold of 4.5:1.

All images have alt attributes. This is enforced in the Twig templates — the <img> tag always outputs the alt text from the content item's frontmatter.

Viewport meta tag is present. Every page includes <meta name="viewport" content="width=device-width, initial-scale=1">.

Best Practices#

HTTPS. The site runs behind Cloudflare, which handles TLS termination. All HTTP requests are redirected to HTTPS.

Security headers. nginx sets the full set on every response:

add_header X-Frame-Options           "SAMEORIGIN"                       always;
add_header X-Content-Type-Options    "nosniff"                          always;
add_header Referrer-Policy           "strict-origin-when-cross-origin"  always;
add_header Permissions-Policy        "camera=(), microphone=(), geolocation=()" always;
add_header Content-Security-Policy   "default-src 'self'; ..." always;

The CSP required some care — wasm-unsafe-eval for Pagefind's WASM bundle, and challenges.cloudflare.com as an allowed frame source for the Turnstile CAPTCHA on the contact form. Everything else is 'self'.

No deprecated APIs. The site doesn't use document.write, XMLHttpRequest, <table> layouts, or anything else Lighthouse flags as a deprecated practice.

No mixed content. Every external resource (Cloudflare Turnstile script) is loaded over HTTPS.

SEO#

Pre-rendered HTML. Crawlers receive complete HTML — every heading, paragraph, code block, and link is in the source. There is no client-side rendering to wait for, no JavaScript required to see the content.

Sitemap with hreflang. The sitemap at /sitemap.xml lists all posts and pages for both locales. Each entry includes <xhtml:link rel="alternate" hreflang="..."> pairs pointing to the EN and PL versions. If a post exists only in one language, the alternate entry is omitted.

hreflang in <head>. Every page includes <link rel="alternate" hreflang="..."> tags for both locales. The language switcher uses the same translation map — built from co-located en.md/pl.md files in each post directory.

Canonical URLs. Each page includes <link rel="canonical" href="..."> pointing to the authoritative URL for that page.

OpenGraph meta. Every page has og:title, og:description, og:image, and og:url. These are populated from frontmatter — title, description, and image fields map directly to the OG tags in the base template.

Descriptive titles and meta descriptions. Frontmatter title and description fields are required. The site doesn't have any pages with default or missing meta descriptions.

What wasn't automatic#

Most of the above follows from the architecture — static files, minimal JS, pre-rendered HTML. But a few things required deliberate work.

Accessibility attributes. The lang attribute, alt text enforcement, heading hierarchy, and semantic element choices all had to be written into the templates. They don't appear by themselves.

The CSP. Getting the Content-Security-Policy right took iteration. Pagefind uses WebAssembly, which requires wasm-unsafe-eval. Cloudflare Turnstile loads from challenges.cloudflare.com and needs a frame-src exception. Every third-party resource requires an explicit CSP exception — adding one without checking breaks the score.

hreflang. The TranslationMapBuilder service builds the {directoryKey → {locale → url}} map from co-located content files. If a post exists only in one locale, the hreflang entry for the missing locale is omitted rather than pointing to a non-existent URL. This required a deliberate fallback in the template, not just a loop over all locales.

The result#

The 4×100 isn't the outcome of an optimisation sprint. It's what you get when a site serves static files, uses minimal JavaScript, has proper HTML structure, and sets the security headers that should be on every production site anyway.

The architecture is described in detail in Part 2 of this series (how Symfony generates the static HTML) and Part 4 (how nginx serves it in production).

notACMS grew out of my own site and for the first release it was one piece: clone the repo, get a full design, start overriding. It worked, but anyone who wanted to build their own look from scratch had to fight against things they didn't need. 1.1.0 fixes this by splitting core from the demo theme.

The core is a skeleton#

templates/, assets/, translations/ are now a minimal wireframe. System fonts, light mode, ~200 lines of CSS. All features work — blog, pages, search, RSS, sitemap, responsive images, contact form — but it looks like a site from the 90s. Deliberately. If you're building your own design, you don't fight a theme that imposes a visual language on you.

The demo theme lives in docs/demo/ and is the default seed — ./notACMS deploy or ddev build will lay it down on first run. Pass --bare if you want the skeleton instead:

./notACMS deploy           # amber-phosphor (default), ready to tweak
./notACMS deploy --bare    # skeleton, build your own from scratch

Everything else — the local override pattern, no core editing, clean git pull — works the same regardless of your choice.

What else shipped in 1.1.0#

Reading time and reading progress on posts and docs. Language switcher as a Twig extension. Post excerpts that no longer leak # from heading anchors. PHPUnit test scaffolding under tests/. AI-agent skills for working with the repo. An old-template compatibility package at docs/customization/old-template/ — one cp -r and you're back to the 1.0.0 look.

1.1.1 — the patch that real use forced#

Preparing this post on holas.pl, deploying to production, I noticed something annoying: ./notACMS deploy --prod backed up and replaced local/ on every run. If you already had content there, it was gone. Deploy couldn't tell "user wants to replace the whole theme" from "user just wants to build their site with existing content."

1.1.1 fixes it so deploy behaves like ddev build: it seeds local/ only when the directory is missing or empty. Content you already have stays untouched. Want to force a re-seed? Pass --bare or --demo explicitly.

The other change is frontmatter-driven navigation labels. Until now every tab in the menu needed a translation key in every locale file — nav.home, nav.about, site.releases and so on. Adding a page meant updating N YAML files. Now menu.label in a page's frontmatter is enough:

---
title: "Architecture guide"
menu:
  label: "Architecture"
  weight: 30
---

A new content_item() Twig function reads it without extra config:

{{ content_item('architecture-guide', 'en').menuLabel() }}

Polish, German, and French demo content got a full review across every page and blog post.

1.1.2 — review-driven hardening#

1.1.2 is what happens when you sit down with the code before tagging and look at it with fresh eyes. Two security bugs surfaced during the review and got fixed before release: an open-redirect through path normalisation (Request::getPathInfo() doesn't collapse repeated slashes, so /<default-locale>//evil.com would have produced a Location: //evil.com cross-origin redirect), and an XSS in the search results page where Pagefind's excerpt was injected into innerHTML without escaping.

The headline feature is canonical URLs. If your default locale is en, /en/blog/ and /blog/ were both reachable and rendered the same content — two indexable URLs for one page. A new event listener now issues 301s from /<default-locale>/... to the unprefixed form before Symfony's router even runs.

Internally, the inline |json_encode|raw JSON-LD blocks scattered across templates are gone. A small StructuredDataBuilder service plus two Twig functions (json_ld() and structured_data()) replace them with a fluent, typed API. JSON_THROW_ON_ERROR is on, so a bad UTF-8 byte in frontmatter raises an exception during render instead of silently shipping <script>false</script>. The bare core templates for contact, default, and projects pages now emit Schema.org markup too — bare deploys no longer have weaker SEO than every customisation example.

The demo as living proof#

The most satisfying part of this release is not the code — it's what ships in docs/demo/. Not the theme. A complete, four-language site that lives in the repository. It has its own manual, architecture docs, styleguide, and a releases blog — all running, all rendered by the same system you get after git clone.

• Manual — install, config, content structure, frontmatter, build commands, deploy, environment variables, troubleshooting
• Architecture — routing, content pipeline, static build, search, multi-language, deployment
• Styleguide — every component documented with real SCSS tokens
• Releases blog — posts about every version, rendered by the system itself

"I trust you that it works, but show me" — this is that. The demo is not an example, it's proof. Multi-language routing, static pre-rendering, Pagefind search, responsive images, contact form, RSS, sitemap — everything runs in the demo content. Someone doing a fresh git clone followed by ddev build sees exactly this site.

Links#

Full changelog with every change categorised: CHANGELOG.md.

Breaking changes and migration from 1.0.0: UPGRADE-1.1.md.

Repository: GitHub / holas1337/notACMS — Apache 2.0.

Building holas.pl involved writing a fair amount of PHP, Twig, and SCSS — and making architectural decisions that would be annoying to undo later. I used Claude Code as an AI pair programmer throughout. This post covers what that workflow actually looks like, where it works well, and where it still needs human judgment.

AGENTS.md — The AI's Instruction Manual#

The first practical insight from this project: an AI assistant is only as good as the instructions it's given. Without explicit guidance, Claude defaults to generating functional but generic code — reasonable choices, but not necessarily the choices you'd make yourself.

The solution is AGENTS.md, a file in the project root that Claude Code reads at the start of every session. It documents:

• Architecture rules — final classes only, no inheritance, interface segregation, value objects over associative arrays
• Code style — strict types on every file, Yoda conditions, blank line before return, PSR-4 namespace convention
• Naming conventions — interface naming (ContentServiceInterface → ContentService), readonly value objects, constructor property promotion
• DDEV commands — how to start the environment, run builds, check code quality
• Content structure — where Markdown files live, how frontmatter works, what the URL slug conventions are

With this context, Claude generates code that follows the project's actual conventions. Reviewing a generated class feels like reviewing a pull request from a teammate who has read the style guide — not reviewing output that needs to be translated into project conventions.

EDITOR_GUIDE.md — Delegating Content Creation#

The same principle applies to content. EDITOR_GUIDE.md documents:

• Title format and length (under 70 characters, technology names included, no clickbait)
• Description format (120–160 characters, no "In this post...", lead with reader benefit)
• Intro structure (2–3 sentences, no greeting, problem first)
• Body conventions (code blocks for all commands, short paragraphs, numbered steps for procedures)
• EN/PL parity requirements (both versions equal depth, same code blocks)
• Frontmatter fields and their formats

With this guide, the content creation workflow becomes:

1. Write the post in rough form — the ideas, the code snippets, the structure
2. Hand it to Claude with: "proofread this, correct the English, translate to Polish, and produce the two .md files with correct frontmatter"
3. Review the result

The guide is specific enough that Claude doesn't need to ask clarifying questions. Title format, slug convention, category values, tag format, image path pattern — it's all documented. The output is ready to commit.

Image Generation with Draw Things and MCP#

Every post needs a featured image (minimum 1200×630px). For holas.pl, images are generated locally using Draw Things via the MCP (Model Context Protocol) integration in Claude Code.

The workflow:

1. Claude Code calls mcp__draw-things__generate_image with a prompt describing the image, 4 parallel variants at 1024×576px with steps=4
2. The best variant is selected from .generated/YYYY-MM-DD-session-name/
3. ImageMagick upscales it to production size:

ddev exec convert .generated/session/image.jpg \
    -resize 1920x1080! -filter Lanczos -quality 92 \
    assets/images/output.jpg

4. The image is moved to content/blog/category/post-name/files/ and referenced in frontmatter

The .generated/ directory is gitignored — it holds expendable previews. Only approved images committed to files/ become production assets.

MCP (Model Context Protocol) is what makes this work: it's a standard interface for connecting AI assistants to external tools. Claude Code connects to Draw Things running locally, Hugging Face Spaces, and other services without leaving the development session. The image generation happens on the local machine — no API quota, no external service, no per-image cost.

What AI Does Well#

Boilerplate and patterns — generating a new service with its interface, value object, and correct import ordering is instant. The structure is consistent with the rest of the codebase because the conventions are documented.

SCSS from description — describing a component layout in words and getting working SCSS back, with the project's variable names, is faster than writing it from scratch.

Translation — Polish and English content at equal quality. The editorial guide's specificity about what "equal quality" means (same code blocks, same depth, not a summary) produces translations that don't need significant editing.

Repetitive structured work — generating nginx redirect lists, updating frontmatter across multiple files, writing sitemap entries — tasks with clear rules but many instances.

Staying in context — Claude Code reads the project files, understands the existing patterns, and generates code that fits without being told what every class does.

Where Human Judgment Is Still Required#

Architecture decisions — which abstractions to introduce, when a value object is warranted, how to structure the content pipeline — these require understanding the trade-offs in a way that goes beyond pattern matching. The AI generates plausible options; the decision is still human.

Design aesthetics — SCSS variables can be generated, but deciding whether the color palette looks right on a dark terminal-style background requires eyes and taste.

Content voice — the editorial guide captures tone conventions, but the actual ideas — what's worth writing about, what angle is interesting — come from experience, not from a prompt.

Reviewing AI output — the code and content still need to be read. AI-generated code is plausible-looking; it takes a developer to notice when something is technically correct but architecturally wrong.

The Practical Result#

The entire site — architecture, frontend, content pipeline, contact form, deployment scripts, this blog post series — was built with Claude Code. The time investment in AGENTS.md and EDITOR_GUIDE.md paid back immediately: less time correcting style, less time explaining the same conventions session after session, more time on the actual work.

The most surprising benefit was content. Writing a post in rough Polish, having it proofread, translated to English, and converted to two properly-structured .md files with correct frontmatter in one step — that removes enough friction that publishing actually happens.

The architecture built this way doesn't just produce maintainable code — it produces measurable results. The next post looks at the Lighthouse scores: what drives each of the four metrics and why most of it follows from the architecture, not from optimisation work.

One of the goals for holas.pl was a development environment as simple as the production one. No database to start, no Docker networking to configure by hand, no five-minute startup sequence. The result is a DDEV-based dev setup that starts with a single command and a production stack that runs in two containers.

Development with DDEV#

DDEV handles the local development environment. The entire setup is in .ddev/config.yaml:

name: holas-pl
type: php
php_version: "8.5"
webserver_type: nginx-fpm
nodejs_version: "22"
omit_containers: [db]
web_environment:
  - APP_ENV=dev

The omit_containers: [db] line is notable — there's no database, so there's no database container. DDEV's default MySQL/MariaDB setup is skipped entirely. ddev start spins up nginx + PHP-FPM and nothing else.

In development the content tree is rebuilt on every request, so editing a Markdown file and refreshing the browser shows the change immediately. No cache to clear. Symfony's debug toolbar is available. Draft posts are visible.

The Build Command#

ddev build runs the full pipeline:

rm -rf var/dart-sass         # remove arch-specific binary (see below)
php bin/console cache:clear
php bin/console sass:build   # compile SCSS via dart-sass
php bin/console asset-map:compile  # fingerprint assets
php bin/console app:build    # render all URLs to public/static/
npx pagefind --site public/static --output-path public/pagefind

After this, public/static/ contains the complete site as HTML files. nginx serves from that directory. The dart-sass step removes the platform-specific binary before the build to force a fresh download — more on this below.

Code Quality Checks#

ddev code-check runs four checks in sequence:

composer validate --strict
composer audit --no-dev         # checks for known CVEs in dependencies
vendor/bin/php-cs-fixer fix --dry-run --diff
vendor/bin/phpstan analyse      # level 6

ddev code-fix auto-fixes PHP CS Fixer issues and re-runs the check. PHPStan level 6 catches missing type hints, wrong argument types, and unknown methods before they reach production.

The Styleguide#

A dev-only page at /styleguide/ documents every component in the UI using the actual CSS classes — not wrappers or snapshots. The page is served only in the dev environment (the controller throws a 404 in production) and is not included in the static build.

The value of the styleguide is in development: changing a component's SCSS immediately updates the styleguide. There's no separate design system to keep in sync.

Asset Pipeline Without Node.js#

SCSS is compiled by symfonycasts/sass-bundle, which wraps dart-sass and requires no Node.js installation. The single entrypoint assets/styles/app.scss imports all partials. In development it compiles on-the-fly. In production php bin/console sass:build runs before the build.

JavaScript modules are handled by Symfony's AssetMapper — no webpack, no Vite, no rollup. Scripts are loaded as plain <script src="..."> tags with content-hashed filenames. The import map registers only the main app.js entrypoint; other scripts (contact form, search, cookie banner) are loaded separately via {{ asset('script.js') }} in templates.

The dart-sass binary problem: symfonycasts/sass-bundle downloads a platform-specific dart-sass binary to var/dart-sass/. The binary compiled on a development machine (x86_64) won't run in the production Docker container (also x86_64 in this case, but the binary path and version can differ). The solution is straightforward: delete the binary before every build and let dart-sass download the correct one for the current platform.

Production: Two Containers#

The production docker-compose.yaml:

services:
  nginx:
    image: nginx:alpine
    volumes:
      - ./docker/nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - .:/app:ro
    depends_on:
      - php

  php:
    build:
      context: .
      dockerfile: docker/Dockerfile
    user: "${UID:-1000}:${GID:-1000}"
    volumes:
      - .:/app

Two containers: nginx and PHP-FPM. No database container. nginx mounts the project read-only; PHP-FPM runs as the host user to avoid file permission issues with the Symfony cache.

The PHP image (docker/Dockerfile) is php:8.5-fpm-alpine with only what's needed: icu-dev (Symfony intl), nodejs and npm (for the Pagefind build step), unzip, git, and Composer.

Deployment#

The entire deployment is a single script ./deploy.sh --prod:

1. docker compose down
2. docker compose build --pull — rebuilds the PHP image from scratch
3. docker compose up -d
4. composer install --no-dev --optimize-autoloader
5. php bin/console cache:clear
6. rm -rf var/dart-sass — remove the arch-specific binary
7. php bin/console sass:build
8. php bin/console asset-map:compile
9. php bin/console app:build — render all static HTML
10. npx --yes pagefind --site public/static --output-path public/pagefind

The build runs inside the PHP container where the correct CPU architecture is known. After step 10, nginx is already serving the previous build's static files. The new files replace them atomically at the filesystem level. There's a brief window where a partial build is live, but for a low-traffic portfolio site this is acceptable without blue-green deployment complexity.

No CI/CD pipeline, no staging environment. Deployment is ssh server, cd holas.pl, git pull, ./deploy.sh --prod.

Compared to WordPress#

The full WordPress production stack required: PHP-FPM, MySQL, a caching layer (Redis or filesystem), a scheduled task runner for wp-cron, and enough RAM to keep MySQL warm. Updates to any component required downtime or careful sequencing.

The current stack is two containers. A Raspberry Pi 5 runs it without memory pressure. Deployment is a shell script. The entire codebase, content, and configuration fits in a single git repository. Backup is git push.

The next post in the series covers the most unconventional part of this project: building the entire site with Claude Code as an AI pair programmer, and using MCP tools to generate featured images locally.

The fix is a global CLAUDE.md — a persistent instruction file that teaches Claude which tool to reach for based on the query type. This post walks through my setup, the decision tree I built, and how you can build one for your own stack.

The Problem: Too Many Tools, No Strategy#

MCP servers give Claude Code superpowers: browser automation, error tracking, documentation lookup, IDE integration. But more tools means more choices, and without guidance Claude makes reasonable but suboptimal picks.

Common failure modes I observed:

• Wrong tool for the job — querying Context7 for "latest Symfony version" (it only has docs, not release metadata) instead of Perplexity
• Expensive path when a cheap one exists — using Grep to search for Symfony routes across multiple files instead of asking JetBrains MCP for a structured route list
• Missing the specialist — not checking Sentry for a production error when the stack trace would immediately reveal the root cause
• Redundant queries — trying multiple tools sequentially when the memory could route to the right one immediately

The solution is explicit routing rules stored in Claude Code's global CLAUDE.md. Claude reads this file at the start of every session, so the decision tree is always available.

My MCP Stack#

Here are the six MCP servers I run and what each does best.

Context7 — Library and Framework Docs#

Context7 serves versioned documentation with code examples. You give it a library name and a question, and it returns the relevant section from official docs.

Workflow: resolve-library-id (find the library) → query-docs (fetch docs for a specific question). It supports versioned lookups — I can query /sylius/sylius/v1.14.6 specifically, not just "latest."

Best for:

• Method signatures and configuration examples
• Migration guides between framework versions
• How-to patterns from official docs (Symfony forms, Doctrine mappings, API Platform filters)

Fails for:

• Current version numbers or release dates (it has docs, not metadata)
• PHP language features (PHP itself isn't a library with versioned docs in Context7)
• Security CVEs or advisories
• Anything that requires real-time information

Perplexity — Current Facts and Research#

Perplexity is an AI-powered web search with four modes: search (web results with citations), ask (AI-synthesized answers via sonar-pro), research (deep multi-source analysis, 30+ seconds), and reason (step-by-step logical reasoning).

Best for:

• Latest version numbers, release dates, EOL schedules
• Security advisories and CVE details
• PHP language features and RFCs (property hooks, asymmetric visibility — these aren't in Context7)
• External service pricing (API costs, hosting comparisons)
• General programming best practices and benchmarks

Key role: Perplexity fills every gap Context7 has. When Context7 returns nothing or returns stale docs, Perplexity almost always has the answer.

JetBrains — IDE-Level Code Intelligence#

This is the MCP server that saves the most tokens. JetBrains MCP connects Claude Code to your IDE's index — the same index that powers autocomplete, go-to-definition, and refactoring. The base JetBrains MCP provides generic tools (file search, symbol lookup, text search, terminal commands), and framework plugins extend it with specialized tools — the Symfony plugin adds route listing, service lookup, Doctrine entity inspection, and Twig analysis.

My typical workflow: I paste a Jira ticket link into the conversation. Claude reads the task via the Atlassian MCP, then uses JetBrains MCP to do a quick code reconnaissance — finding the relevant services, checking route definitions, inspecting entity fields — all before writing a single line of code. This "analyze first" step catches misunderstandings early and gives Claude the context to ask better clarifying questions.

Symfony-specific capabilities (via the Symfony plugin):

• list_symfony_routes_controllers — all routes with controller, path, methods. One call instead of grepping through attributes across dozens of files
• locate_symfony_service — find any service definition by its fully-qualified class name
• list_doctrine_entity_fields — entity fields, types, and relationships in structured format
• list_symfony_commands, list_symfony_forms — console commands and form types at a glance

Token savings example: Finding all routes matching /api/ in a Symfony project:

• Without JetBrains: Grep for #[Route across src/Controller/, read each matching file, parse the route attributes, cross-reference with _routes.yaml. Easily 5-10 tool calls and thousands of tokens of file content.
• With JetBrains: One list_symfony_routes_controllers call returns a structured, filterable list. Done.

Also useful for: Indexed text search (search_in_files_by_text), file search by name, symbol lookup, running terminal commands in the IDE, build/test execution.

Chrome DevTools — Browser Automation#

Chrome DevTools MCP lets Claude control a browser: navigate to URLs, click elements, fill forms, take screenshots, inspect network requests, run JavaScript, and execute Lighthouse audits.

Best for:

• Testing UI changes visually after modifying templates or CSS
• Running Lighthouse performance/accessibility audits
• Debugging frontend issues (checking console errors, network requests)
• Verifying responsive behavior at different viewport sizes

Sentry — Production Error Tracking#

Sentry MCP connects Claude to your error tracking system. It can search issues, retrieve stack traces, analyze errors with Sentry's AI (Seer), and look up release and deployment information.

The workflow that makes this valuable:

1. You notice an error (or a user reports one)
2. Claude queries Sentry: "search for 500 errors in the last 24 hours"
3. Sentry returns the stack trace, affected users count, first/last seen timestamps
4. Claude reads the relevant source file, identifies the root cause, and proposes a fix
5. The entire debug cycle happens without leaving the terminal

Best for:

• Investigating production errors with full stack traces
• Understanding error frequency and patterns (is it new? is it getting worse?)
• Correlating errors with recent deployments

Atlassian/Jira — Task Management#

Jira MCP provides full issue lifecycle management: create, read, edit, transition, comment, and search with JQL.

Best for:

• Reading task specifications before starting work
• Updating issue status as work progresses
• Adding technical comments to issues for team visibility
• JQL searches to find related issues or check what's in the current sprint

The Decision Tree#

The core of the global CLAUDE.md is a routing table that maps query types to the best tool. Here's the actual content from mine:

## Search & Research — Tool Decision Tree

### When to use Context7
**Best for**: library/framework API docs with clean code examples
- Versioned library docs (Sylius, Doctrine, API Platform, Symfony, GitHub Actions)
- Official method signatures, configuration examples, how-to patterns
- Concise, authoritative answers directly from official source
- `resolve-library-id` first, then `query-docs`
- **Fails for**: current version/release info, PHP language features,
  security CVEs, pricing, general programming

### When to use Perplexity
**Best for**: anything current, factual, or not a library doc
- Latest versions, release dates, EOL schedules
- Security advisories, CVEs, vulnerability details
- PHP language features (property hooks, new syntax)
- External service pricing
- General programming best practices, benchmarks
- Supplement when Context7 fails or for real-world context

### When to use WebSearch
- Official blog posts / release announcements
- As last resort or to supplement

The key pattern: each section leads with "best for" (when to pick this tool) and ends with "fails for" (when to skip it). Claude uses both signals — positive routing and negative routing.

The Benchmark Table#

I ran the same 10 query types through Context7, Perplexity, and WebSearch and rated the results. This table lives in the global CLAUDE.md so Claude can reference it when deciding:

The pattern is clear: Context7 is excellent for versioned docs but scores zero on anything requiring current or real-world data. Perplexity covers nearly everything. WebSearch is the strongest for blog posts and release announcements.

Including this table in the global CLAUDE.md gives Claude a quantitative basis for tool selection, not just rules.

How Global Memory Works#

Claude Code supports a global instruction file at ~/.claude/CLAUDE.md. This file is loaded at the start of every conversation, regardless of which project you're working in. It's the right place for tool routing rules because MCP servers are configured globally, not per-project.

Compare this with project-level AGENTS.md:

Structuring the Global CLAUDE.md#

The global CLAUDE.md works best when it's structured like a reference manual, not a narrative. Claude scans it at session start — clear headings and explicit rules make that scan effective.

Tips from my experience:

1. Lead with the decision rule, not the description. "Best for: versioned library docs" is more useful than "Context7 is a documentation server that..."
2. Include failure modes. "Fails for: current versions" prevents Claude from trying Context7 for queries it can't handle.
3. Add a server inventory. List every MCP server with its tools — Claude can reference this when it needs a capability it hasn't used before.
4. Use concrete examples. "Latest Symfony version → Perplexity" beats "use Perplexity for current data."
5. Update when tools change. Added a new MCP server? Update the file. Removed one? Remove its entry. Stale routing rules are worse than no rules.

Build Your Own#

The specific MCP servers don't matter — the pattern does. Whether you use Cursor, Windsurf, or Claude Code, whether you write Python or Go, the principle is the same: teach your AI assistant which tool to reach for.

Step-by-step:

1. List your MCP servers (or equivalent tool integrations) and what each one does
2. Identify overlaps — where can two tools answer the same query? (Context7 and Perplexity both handle Symfony docs, but with different strengths)
3. Benchmark — run the same 5-10 representative queries through each overlapping tool. Rate the results. This gives you data, not gut feeling.
4. Write routing rules — for each tool, write "best for" and "fails for" sections with specific query types
5. Include the benchmark — the table gives your AI a quantitative reference, not just instructions
6. Iterate — the first version won't be perfect. When Claude picks the wrong tool, update the file. Over a few sessions, the routing gets tight.

My global CLAUDE.md started as a list of MCP servers with one-line descriptions. After a few weeks of observing where Claude made suboptimal choices, it evolved into the decision tree above. The benchmark table was the biggest single improvement — it turned vague "prefer X over Y" rules into concrete data Claude could act on.

The investment is small (an hour to set up, a few minutes per update) and the payoff compounds: fewer wasted tokens, faster answers, and less time correcting tool choices mid-conversation.

holas.pl is a static site with one exception: the contact form. Every blog post, category page, and static page is a pre-rendered HTML file served by nginx. The contact form is the only endpoint that runs PHP.

That single exception raises a specific security question: how do you protect a form on a static page from bot submissions and CSRF attacks when there's no session?

The CSRF Problem with Static Pages#

Standard CSRF protection works by embedding a token in the form that is tied to the user's session. When the form is submitted, the server verifies the token matches the one in the session.

Static pages don't have sessions. The contact page is generated once during ddev build and served as a file. It can't generate a per-user token at render time. Symfony's built-in csrf_protection is therefore explicitly disabled on the contact form:

public function configureOptions(OptionsResolver $resolver): void
{
    $resolver->setDefaults([
        'csrf_protection' => false,  // deliberate — static page, no session
    ]);
}

Disabling CSRF protection is the right call here. The alternative — adding a dynamic PHP endpoint just to generate tokens for the form — would reintroduce the PHP-on-every-request problem for a page that otherwise needs none.

Cloudflare Turnstile as the Replacement#

Cloudflare Turnstile is a CAPTCHA alternative that runs client-side, confirms the user is human, and provides a one-time token that can be verified server-side. It replaces CSRF as the bot-prevention layer.

The form flow:

1. The contact page is served as static HTML with the Turnstile widget embedded (site key baked in at build time)
2. Turnstile runs its challenge invisibly; on success it calls window.onTurnstileSuccess(token), which writes the token into a hidden field
3. contact.js intercepts the form submit event and sends the data via fetch() instead of a standard form post
4. The PHP endpoint receives the submission, validates the form fields, then verifies the Turnstile token with Cloudflare's API
5. Only if both pass does the email get sent

Server-side verification is the critical step:

final class TurnstileValidator
{
    public function verify(string $token, string $remoteIp): bool
    {
        try {
            $response = $this->httpClient->request('POST', 'https://challenges.cloudflare.com/turnstile/v0/siteverify', [
                'body' => [
                    'secret'   => $this->secretKey,
                    'response' => $token,
                    'remoteip' => $remoteIp,
                ],
            ]);

            $data = $response->toArray();

            return true === ($data['success'] ?? false);
        } catch (\Throwable $e) {
            $this->logger->error('Turnstile verification failed: '.$e->getMessage());

            return false;
        }
    }
}

The validator fails closed — any exception returns false and blocks the submission. An empty or missing token also returns false immediately.

Minimal PHP Attack Surface#

The entire application's PHP surface in production is two URL patterns:

location ~ ^/(api|pl/api)/ {
    fastcgi_pass $php_upstream;
    fastcgi_read_timeout 30;
}

Everything else — every blog post, every category page, the sitemap, the RSS feed, the search page — is handled by nginx serving static files. PHP-FPM is never invoked for content delivery. The attack surface for the PHP layer is a single POST endpoint.

Content Security Policy#

The nginx config applies a strict CSP on every response:

add_header Content-Security-Policy
    "default-src 'self';
     script-src  'self' challenges.cloudflare.com;
     style-src   'self' 'unsafe-inline';
     img-src     'self' data:;
     frame-src   challenges.cloudflare.com;
     connect-src 'self' challenges.cloudflare.com;"
    always;

The only external domain permitted is challenges.cloudflare.com, which Turnstile requires for its script, iframe, and API call. No Google Analytics, no CDN scripts, no Facebook pixel. script-src has no 'unsafe-inline' and no 'unsafe-eval' — all JavaScript is loaded from hashed files via Symfony AssetMapper.

The 'unsafe-inline' in style-src is a deliberate compromise: Turnstile's widget injects inline styles that can't be avoided without a CSP nonce, and AssetMapper doesn't currently inject nonces. Everything else is locked down.

Additional Security Headers#

add_header X-Frame-Options        "SAMEORIGIN"                       always;
add_header X-Content-Type-Options "nosniff"                          always;
add_header Referrer-Policy        "strict-origin-when-cross-origin"  always;
add_header Permissions-Policy     "camera=(), microphone=(), geolocation=()" always;

Hidden files are denied:

location ~ /\. { deny all; }

HSTS is handled upstream at Cloudflare, so there's no Strict-Transport-Security header in the nginx config — it would be redundant.

The Result#

The contact form works without sessions, without CSRF tokens, and without JavaScript being required for anything other than the form submission itself. The page renders fully as static HTML. Bot submissions are blocked by Turnstile's server-side verification. The PHP endpoint is unreachable for anything other than POST requests to /api/contact.

Compared to WordPress with a contact form plugin, the attack surface went from "PHP running on every request, wp-admin exposed, XML-RPC enabled, 22 plugins any of which could have a vulnerability" to "one POST endpoint with Cloudflare verification."

The next post covers the developer experience — DDEV, the build pipeline, and deployment to production in two Docker containers.

The codebase is open-source under Apache 2.0 — see GitHub / notACMS. It has 368 PHPUnit tests, CI/CD via GitHub Actions, and a local override pattern that lets users customise templates, CSS, and translations without forking.

Architecture#

All content lives in Markdown files with YAML frontmatter:

content/
├── blog/
│   └── tutorials/
│       └── my-post/
│           ├── en.md   ← English version
│           ├── pl.md   ← Polish version
│           └── files/  ← images, served at /media/my-post/
└── pages/
    └── about/
        ├── en.md
        └── pl.md

ContentTreeBuilder scans the filesystem, parses each file with league/commonmark (GitHub Flavoured Markdown + YAML frontmatter), and builds a typed ContentTree — an in-memory index of all posts and pages for a given locale. Tags, categories, archive months, and URL maps are computed from that index.

The static build uses Symfony sub-requests: HttpKernelInterface::handle() with SUB_REQUEST renders every URL through the full kernel without touching the network. If a URL works in development, it will be in the static build. No separate template engine, no build configuration.

Key Features#

• Multi-language — co-located en.md + pl.md in the same directory, automatic translation mapping, hreflang tags, language switcher
• Search — Pagefind WASM-based static index, client-side, no Elasticsearch or Algolia
• Responsive images — automatic srcset generation via ImageMagick, configured variant widths
• Draft & scheduled posts — dev-only preview toggles, scheduled posts automatically published at build time
• Contact form — Cloudflare Turnstile CAPTCHA, tight CSP, single POST endpoint
• Styleguide — dev-only page documenting every component with real CSS classes
• Local override pattern — local/ directory merges on top of base at build time, customise without forking

Tech Stack#

• PHP 8.5, Symfony 7.x
• Twig templates, SCSS (dart-sass via symfonycasts/sass-bundle)
• Symfony AssetMapper (no webpack, no Vite, no Node.js build pipeline)
• nginx + PHP-FPM (two Docker containers in production)
• Pagefind for search
• PHPUnit 13, PHPStan level 6, Rector, PHP CS Fixer

Why Build It?#

Hugo, Jekyll, and Eleventy were obvious candidates. I chose to build a custom Symfony application because I already know Symfony well, and owning the full stack turned out to have real advantages: the same templates, controllers, and content pipeline serve both development and production. There is no "build-time template engine" separate from the "runtime template engine." It's just Symfony.

The full story of why WordPress had to go is in Why I left WordPress. The architecture deep dive is in Symfony as a Static Site Generator.

Open Source#

notACMS is available on GitHub under Apache 2.0. The preparation for release — testing, AI code review, security fixes, the local override pattern — is documented in the open-source series.

After deciding to leave WordPress, the question was what to replace it with. Hugo, Jekyll, and Eleventy were obvious candidates. I chose to build a custom Symfony application instead — not because the existing tools are inadequate, but because I already know Symfony well, and owning the full stack turned out to have real advantages.

The Core Idea#

The site works in two modes:

• Development — Symfony handles requests dynamically. Edit a Markdown file, refresh the browser, see the result. Standard Symfony dev workflow with the profiler toolbar.
• Production build — a single console command renders every URL to an HTML file on disk. nginx serves those files directly. PHP is never called for content delivery.

The same templates, controllers, and content pipeline serve both modes. There is no "build-time template engine" separate from the "runtime template engine." It's just Symfony.

Content Pipeline#

All content lives in Markdown files with YAML frontmatter:

content/
├── blog/
│   └── tutorials/
│       └── my-post/
│           ├── en.md   ← English version
│           ├── pl.md   ← Polish version
│           └── files/  ← images, served at /media/my-post/
└── pages/
    └── about/
        ├── en.md
        └── pl.md

ContentTreeBuilder scans the filesystem, parses each file with league/commonmark (GitHub Flavoured Markdown + YAML frontmatter), and builds a typed ContentTree — an in-memory index of all posts and pages for a given locale. Tags, categories, archive months, and URL maps are computed from that index.

ContentItem is a final readonly value object. No database, no ORM, no migrations. Adding a post means creating a directory with two Markdown files and running the build.

The Build Command — Symfony Sub-requests#

The static build uses a technique that's specific to Symfony and distinguishes this approach from Hugo or Jekyll: it calls HttpKernelInterface::handle() to make sub-requests — internal PHP calls that go through the full Symfony kernel without touching the network.

$request = Request::create($url);
$request->attributes->set('_static_build', true);
$response = $this->kernel->handle($request, HttpKernelInterface::SUB_REQUEST, false);

if ($response->getStatusCode() < 400) {
    file_put_contents($outputPath, $response->getContent());
}

For every URL — blog posts, category pages, tag pages, archive months, static pages, error pages, RSS feeds, the sitemap — the build command creates a request, runs it through Symfony, and writes the HTML to disk. The URL /blog/ becomes public/static/blog/index.html. The URL /sitemap.xml becomes public/static/sitemap.xml.

No separate template engine to learn. No build configuration. If a URL works in development, it will be in the static build.

nginx Serves Everything#

In production, nginx handles all content delivery:

location / {
    try_files /static$uri/index.html /static$uri/index.xml /static$uri $uri =404;
}

# PHP only for the contact form
location ~ ^/(api|pl/api)/ {
    fastcgi_pass $php_upstream;
}

For any incoming URL, nginx tries the pre-rendered HTML file first. PHP-FPM is only invoked for /api/contact — the single dynamic endpoint. Every blog post, category listing, tag page, and static page is a file served directly from disk. A Raspberry Pi 5 handles this trivially.

No Database#

The content tree is built from Markdown files at build time. In production it's cached indefinitely in Symfony's filesystem cache (invalidated and rebuilt on every deploy). In development it's rebuilt on every request so file changes are immediately visible.

There is no MySQL, no schema, no migrations, no connection pooling, no slow queries. Adding content means creating files and running ddev build. Removing content means deleting files. The entire site history is in git.

Multi-language Without a Database#

Both Polish and English content lives in the same directory:

content/blog/tutorials/my-post/
    en.md  → slug: "blog/my-post"      → /blog/my-post/
    pl.md  → slug: "wpisy/moj-wpis"    → /pl/wpisy/moj-wpis/
    files/ → images served at /media/my-post/

Co-location is the translation link. Two locale files in the same directory are automatically treated as translations of each other. TranslationMapBuilder constructs {directoryKey → {locale → url}} for hreflang tags and the language switcher. No translation_key field, no join table, no synchronisation to manage.

Search with Pagefind#

Search is a WASM-based static index built by Pagefind after the HTML files are generated:

npx pagefind --site public/static --output-path public/pagefind

Pagefind reads the pre-rendered HTML, indexes data-pagefind-body regions, and generates a binary index in public/pagefind/. The search page loads this index client-side via a dynamic import(). No Elasticsearch, no Algolia, no server-side search query. The index is a set of static files.

Redesign Simplicity#

Changing the site's appearance means editing Twig templates and SCSS. No React component library to update. No Node.js build pipeline. No WordPress child theme hierarchy. The entire frontend is:

• assets/styles/app.scss — one entrypoint importing partials
• templates/ — Twig templates
• symfonycasts/sass-bundle — compiles SCSS with dart-sass, no Node required

To change the colour scheme: edit _variables.scss. To change the layout: edit a Twig template. Run ddev build and it's done.

Trade-offs#

The main trade-off compared to Hugo or Jekyll is that this is custom code — I maintain it. The upside is that it's exactly what's needed, nothing more. There's no plugin ecosystem to navigate, no upgrade path to worry about, no feature flags for things I'll never use.

The only genuinely dynamic feature — the contact form — is covered in the next post.

This is the first post in a series documenting the migration to a custom Symfony-based static site generator. The next posts cover the architecture, the contact form, the developer workflow, and building the site with AI assistance.

The Update Treadmill#

WordPress ships security updates frequently. Plugins ship updates independently. Themes do too. On a quiet week my update queue had three items. On a bad week it had fifteen. Each one required:

1. Back up the database and files
2. Apply the update
3. Check that nothing broke

That last step is the killer. WordPress plugins interact with each other in ways that are impossible to predict. An update to a caching plugin would break the SEO plugin's output. An update to the SEO plugin would change how sitemaps were generated. Every update was a small gamble.

For a portfolio site that publishes a post every few months, this maintenance overhead is absurd.

Dozens of Plugins for Basic Features#

A fresh WordPress installation does almost nothing useful. To run a respectable portfolio blog you need plugins for:

• SEO — Yoast or Rank Math, with their own settings screens, meta boxes, and update cycles
• Caching — W3 Total Cache or WP Super Cache, with complex configuration and edge cases
• Security — Wordfence or similar, scanning for intrusions, blocking IPs, sending daily reports
• Contact form — Contact Form 7 or Gravity Forms
• Backups — UpdraftPlus or similar, usually pushing to an external service
• Performance — image optimization, lazy loading, minification
• SMTP — because WordPress sends email through PHP mail() by default, which goes to spam

Each plugin is code you don't control, maintained by someone else, potentially abandoned tomorrow, running on every page load.

When I started planning the migration I counted 22 active plugins.

Bot Attacks and Login Problems#

A WordPress login page is a known target. The URL is always /wp-admin/ or /wp-login.php. Every bot on the internet knows this. The result: constant brute-force login attempts, around the clock.

I had Wordfence rate-limiting login attempts, blocking suspicious IPs, and sending me daily attack reports. It worked — but it was another moving part consuming server resources on a site that didn't need user logins at all. The only person logging in was me, once a month.

XML-RPC was another attack vector. WordPress enables it by default for pingbacks and the mobile app. Bots probe it constantly. The fix was an nginx rule to block it — but you only find out about it after seeing the traffic in your logs.

PHP and MySQL on a Raspberry Pi#

holas.pl runs on self-hosted hardware — first a Banana Pi, now a Raspberry Pi 5. These are capable ARM boards, but they are not server-grade machines. Running PHP-FPM and MySQL simultaneously for a blog that changes once a month is wasteful.

A typical WordPress page load on that hardware: PHP parses the request, MySQL runs several queries to fetch post content, navigation data, sidebar widgets, and site options, PHP renders templates, every active plugin executes its hooks. All of this for content that was identical to the last request and will be identical to the next one.

With a static site, nginx serves a pre-rendered HTML file directly from disk. The ARM processor barely wakes up. Pages load faster than WordPress could parse the incoming request.

The Database as a Liability#

Nineteen years of WordPress produces a database with thousands of rows of post metadata, options, post revisions, and transients. It needs:

• Regular backups (and testing that restores actually work)
• Occasional cleanup — WordPress accumulates garbage: post revisions, expired transients, orphaned metadata rows
• Monitoring for corruption after unclean shutdowns
• A MySQL process running continuously, consuming memory

A portfolio blog is a collection of text and images. Storing it in a relational database adds operational complexity without adding value.

What I Kept#

The content. All 26 posts were exported and converted to Markdown files — titles, dates, categories, tags, images. The URLs were preserved exactly: 25 individual post redirects and 43 image path redirects are now baked into the nginx config. Search rankings survived the migration intact.

Everything else — the database, the plugins, the update queue, the /wp-admin/ login page — is gone.

The next post covers what replaced it: a custom Symfony application that generates static HTML files and serves them through nginx, with no PHP involved in delivering content to visitors.