Staccato Bundle Laravel Package

Getting Started

First, a framework check. Despite the name pattern, cristianradulescu/staccato-bundle is a Symfony bundle (AbstractBundle, config/packages/, bin/console), not a Laravel package. There is no service provider, no artisan command, and no package discovery entry. In a Laravel app it will not auto-register and site:build will not appear under php artisan. Treat this as a separate static-site project you run alongside your Laravel app (e.g. a docs or marketing site that Laravel links to), not as something you require into an existing Laravel codebase.

Assuming a Symfony context:

composer require cristianradulescu/staccato-bundle

Or scaffold a working site end-to-end:

bin/create-blog.sh

Look here first, in this order:

1. The config tree — config/packages/staccato.yaml. This is the whole control surface: title, base_url, description, language, articles_per_page, footer_text, include_default_styles, stylesheets, highlighter_css, content_dir, build_dir, assets_dir. Everything is validated, so a typo fails fast rather than producing a weird build.
2. content/ — Markdown files with YAML front matter (title, slug, date, excerpt, draft). content/docs.md → /docs/.
3. @Staccato templates — shipped defaults for base, page, home, 404, rss.xml, sitemap.xml. Read these before overriding; they encode the SEO behavior (canonical URLs, meta description, lang, RSS alternate link).

Canonical first use case: a documentation or small blog site where you already have a Symfony app, or a standalone site repo where Markdown lives in git and CI builds to static HTML. Write one .md file, run bin/console site:build, open build/index.html.

Implementation Patterns

Content-as-source-of-truth workflow. Keep content/ in the repo, run site:build in CI, deploy build/ (plus build/assets/) to any static host. Because path resolution is directory-style, content/guides/deploy.md maps predictably to /guides/deploy/ — author links with staccato_path() rather than hardcoding so the sub-path prefix from base_url is applied automatically.

Override one template, inherit the rest. Drop a file at templates/bundles/StaccatoBundle/page.html.twig and only that template wins; home, 404, feeds and sitemap keep working from the bundle defaults. This is the right granularity for most customization — copy the default first, then edit, so you don't silently lose the canonical/meta logic.

Config-only theming. You can extend or fully replace the theme without touching PHP: set include_default_styles: false and list your own stylesheets, plus a highlighter_css for the code theme. Since stylesheets and highlighter_css are linked independently of the default theme, you can also layer your own CSS on top of the default when you just want tweaks.

Environment-driven drafts. dev includes draft: true articles, prod excludes them. Don't invent a flag — set APP_ENV correctly in your build job. Local site:build for preview shows drafts; the deployed build must run as prod.

Fixtures for demo/review environments. --use-fixtures generates Faker-based content, which is useful for spinning up a populated review app or showcasing a theme without committing filler Markdown. It requires fakerphp/faker (only suggested, not required) — add it to require-dev.

Sub-path hosting. For GitHub Pages project sites, set base_url to the full URL including the path (e.g. https://user.github.io/project). The path is applied to every internal link and stylesheet, which is exactly what project-site hosting needs and what usually breaks hand-rolled generators.

Build in CI with --clean. Default site:build behavior plus --clean/--no-clean gives you a clean artifact for deploys. Use -v on failure to get the full exception — the summary output is terse enough that verbose mode is the practical debugging default.

Gotchas and Tips

It is not a Laravel package. This is the single biggest trap. No StaccatoServiceProvider, no config/staccato.php, no Blade, no Eloquent. Every helper (staccato_path(), staccato_url(), the staccato global) is Twig, and the command is Symfony Console. If your team is Laravel-only, adopting this means maintaining a second Symfony app — weigh that against a Laravel-native generator or just a Node-based SSG before committing.

/ is reserved. index.md files and any slug resolving to / are explicitly rejected because / is the generated homepage. This is validated rather than silently overwritten, so you'll get a clear error — but it means you cannot hand-author the homepage Markdown; the homepage is driven by content/articles/ and articles_per_page.

Draft leaking is an environment bug, not a config bug. If a draft shows up in production, the cause is almost always APP_ENV not being prod in the build container, not a draft: false mistake. Check the environment before touching front matter.

Failed builds keep stale output by design. Validation (config, content, duplicate output paths, pagination conflicts) runs before the build directory is cleaned, so a broken build leaves the previous build/ intact. Great for safety, dangerous for CI: a non-zero exit that nobody checks will happily deploy the last good artifact. Always gate deployment on the command's exit code.

Don't hand-edit build/assets/staccato/staccato.css. The default theme is copied on every build. Any manual edits vanish. Override through stylesheets config or include_default_styles: false instead.

--use-fixtures fails without Faker. It's a suggest, not a dependency, so a clean install will error rather than degrade. Add fakerphp/faker to dev dependencies if you rely on it.

Front matter is tolerant, but only so far. CRLF, a UTF-8 BOM, and trailing whitespace on delimiters are handled — so Windows-authored content won't mysteriously produce empty titles. Malformed YAML or a missing title is still your problem.

Changing articles_per_page changes URLs. Paginated home pages get absolute canonical links, and pagination conflicts are validated — but re-pagination alters your public URL surface. Treat the value as semi-frozen once indexed.

Extension points are template- and config-shaped. The release notes describe no PHP extension points (no events, no compiler passes, no custom loader interfaces advertised). Customization lives in Twig overrides, stylesheets, highlighter_css, and the config tree. Don't plan on hooking ContentLoader or OutputPathResolver without reading the source first.

v0.1.0 — pin it. First release, pre-1.0, no stated BC policy. Pin the exact version in composer.json; the config tree is large and validated, which makes breaking renames loud but not impossible.

Quality signals are real but narrow. PHPStan level 7, PHP CS Fixer, PHPUnit, and a composer qa gate suggest disciplined maintenance. That raises confidence in the validated-config and build-safety claims; it does not tell you anything about the size of the test suite or coverage of edge cases like unicode slugs. Run composer qa yourself if you plan to fork or contribute.