Staccato Bundle Laravel Package

Product Decisions This Supports

• Framework fit is the first decision, and it's a "no" for Laravel. Despite the PHP framing, staccato-bundle is a Symfony bundle (AbstractBundle, Twig templates, site:build Symfony console command). It will not drop into a Laravel app; adopting it means committing to (or already having) a Symfony runtime. Do not let "it's PHP, we're PHP" collapse this into a free swap.
• Build vs. buy for a content site. This is a credible "assemble, don't build" option for Markdown-driven sites: Markdown + YAML front matter in git, no database, static HTML out. If the product is docs, a company blog, a changelog, or a marketing microsite, adoption removes weeks of glue code (content loading, routing, pagination, RSS, sitemap, 404, asset mirroring) that teams routinely rebuild badly.
• Hosting and cost decisions. Generated static output plus sub-path support (base_url path applied to every internal link and stylesheet) makes GitHub Pages project sites, S3/CloudFront, and Netlify-style targets viable. That's a real infra-cost line item, not a footnote.
• SEO/roadmap scope. The default templates ship <html lang>, meta description (excerpt or site description), absolute canonicals for pages and paginated home pages, and an RSS alternate link. For a content-led growth roadmap, that means baseline SEO is a config exercise, not a backlog ticket — but also that anything beyond baseline (structured data, OG/Twitter cards, hreflang) is still your work.
• Content-authoring workflow. Front matter (title, slug, date, excerpt, draft) with tolerant parsing (CRLF, BOM, trailing whitespace) and environment-aware drafts (dev includes, prod excludes) supports a "write in a PR, preview in dev, publish on merge" process. That's a decision about editorial tooling, not just code.
• Design investment level. A dependency-free default theme copied on every build, plus include_default_styles / stylesheets / highlighter_css config, means launch quality is achievable with config alone and no designer in the critical path; per-template overrides live at the standard templates/bundles/StaccatoBundle/ path, so customization doesn't fork the vendor.
• Confidence in deploys. Configuration, content, duplicate output paths, and pagination conflicts are validated before the build directory is cleaned, so a failing build preserves the previous output. That is a release-safety property worth weighting in a build-vs-buy comparison.
• Demo and enablement cost. --use-fixtures (Faker-based, optional dependency) generates demo content without committing real articles — useful for design review, sales demos, and stakeholder walkthroughs pre-launch.
• Roadmap gaps to plan around, not discover later. No tags/taxonomies, no site search, no i18n beyond a single language value, no incremental builds, and index.md / slugs resolving to / are explicitly rejected because / is the generated homepage. If any of those are near-term roadmap items, budget for extension work or choose differently now.
• Maturity risk as a scheduling input. v0.1.0, single-maintainer package, pre-1.0 — acceptable for internal docs and low-stakes microsites; a different risk conversation for a revenue-generating marketing site.

When to Consider This Package

Adopt when all of these hold:

• The application is Symfony (or you are willing to run a separate Symfony app purely as a site generator). This is a hard gate.
• Content is Markdown, versioned in git, edited via PR by people comfortable with front matter.
• The site shape is blog / docs / paginated article index — exactly what the defaults cover (content/articles/, content/docs.md → /docs/).
• You want static hosting, including sub-path project sites.
• You value the build-safety guarantee (validation before clean) and a one-command build (site:build with --clean / --no-clean).
• Out-of-the-box Twig templates and a zero-dependency stylesheet are an acceptable starting aesthetic.

Look elsewhere when:

• You are on Laravel. Use a Laravel-native generator or a standalone SSG; do not introduce Symfony to get a blog.
• You need search, tagging/taxonomies, multi-language content, author pages, or incremental builds today.
• You need a rich editorial experience (CMS UI, scheduled publishing, roles) — this is a git-and-markdown tool.
• You need programmatic/dynamic pages, personalization, or forms; static output is the whole product.
• Pre-1.0 single-maintainer risk is unacceptable — in that case compare against Hugo/Eleventy/Astro (more mature, larger ecosystems) and accept the different stack, or build in-house.
• Your team has no Twig/Symfony familiarity and template overrides would become a support burden.

Practical evaluation step before committing: run bin/create-blog.sh, do one build, then deliberately break a front-matter field and one slug to confirm the failure mode preserves the prior output. That single test exercises the package's main differentiator (build safety) and its main constraint (strict path rules).

How to Pitch It (Stakeholders)

For executives (one paragraph): Staccato is a small open-source Symfony add-on that turns Markdown files in our repo into a complete static website — blog, docs, pagination, RSS, sitemap, 404, and basic SEO — with one command. It replaces custom glue code we would otherwise build and maintain, produces plain static files we can host cheaply (including on GitHub Pages sub-paths), and refuses to overwrite a working site if a build is broken. It is a v0.1.0, single-maintainer package and it is Symfony-only, not Laravel — so the recommendation is to pilot it on an internal docs site or microsite, not to standardize on it for revenue-critical properties until we've validated it in our own pipeline.

For engineering (the short version): Composer-installable Symfony bundle, validated staccato: config tree (12 keys: title, base_url, description, language, articles_per_page, footer_text, include_default_styles, stylesheets, highlighter_css, content_dir, build_dir, assets_dir). Markdown + YAML front matter via tempest/markdown, highlighting via tempest/highlight. Default templates under the @Staccato Twig namespace, individually overridable at templates/bundles/StaccatoBundle/<file>.twig — no forking. Helpers staccato_path(), staccato_url(), and a staccato config global. site:build with --clean / --no-clean / --use-fixtures; drafts included in dev, excluded in prod. Build validates config, content, duplicate output paths, and pagination conflicts before cleaning, so failed builds preserve prior output. Quality gate is real: PHP CS Fixer, PHPStan level 7, PHPUnit, composer qa.

For engineering (the caveats to state up front): Symfony only — no Laravel service provider, no Blade. Directory-style URLs; index.md and any slug resolving to / are rejected by design. No tags, search, or i18n. Full rebuilds only. Faker is an optional dependency and only needed for --use-fixtures. Pre-1.0 API: pin the version and expect config surface to move.

Ask: timebox a spike — scaffold with bin/create-blog.sh, build twice (success and induced failure), wire it into CI, and report on the override experience and upgrade risk. Decision gate: promote to a production-facing site only after the spike and after confirming no roadmap-adjacent need for search, tagging, or i18n within the next two quarters.