Static Generator Laravel Package

Product Decisions This Supports

• Rendering/deployment model selection. The strongest decision this informs is where your content is served from: dynamic PHP workers vs. a deterministic static build artifact. Pushword's generator is opinionated about the latter — the build's skip-unchanged logic depends on renders being byte-deterministic, which forces a real answer to "is our rendering reproducible?" If the answer is no, that's a bug in the CMS, not a nice-to-have.
• Authoring-surface roadmap. The package's premise — one admin, one Git repo, one AI agent, all writing the same content model — supports a roadmap where editorial (web UI), developer (Git), and automated (agent) authorship coexist without separate pipelines. If your roadmap has any "agents will draft/publish content" item, this is a credible reference implementation of the seam between agent writes and published output.
• Cache-invalidation policy as a product contract. The documented MarkdownParser::CACHE_VERSION / SplitContent::TOC_CACHE_VERSION bump discipline turns caching from an infra detail into an explicit, testable contract: change rendered output → bump the version. That's a decision template worth copying regardless of vendor.
• Agent ergonomics as a first-class requirement. Commands emit single-line JSON under agent detection and gate human output behind a flag. This supports a roadmap decision to treat "machine-readable CLI output" as a supported interface rather than a hack — relevant if you're building internal tooling or MCP-adjacent surfaces.
• Build vs. buy for static export. Buying means adopting a Symfony CMS plus its extension model; building means writing a serializer over your existing content store. This package is the reference spec for the "buy" side: what a static exporter must handle (fragment pools, TOC splitting, incremental builds, byte-stable output).
• Extensibility budget. Its bundles-plus-tags model (e.g. EditorJS tools registered via pushword.editorjs_tool_provider, merged by AppExtension) is a concrete answer to "how do third parties add editor capability without forking?" — useful when scoping whether your own admin should support plugin-style extension.

When to Consider This Package

Consider it when:

• You are already on Symfony (or willing to be) and want a CMS whose output can be shipped as static files.
• Deterministic, reproducible builds matter — you need content-hash caching that actually hits, or incremental deploys that skip unchanged pages.
• Agents are real participants in your content workflow, not a demo: the repo documents agent-mode output, skill routing, and post-change review as norms.
• You want a small, MIT-licensed codebase you can read and adapt rather than a platform you negotiate with.

Look elsewhere when:

• You are a Laravel shop. This is a Symfony CMS monorepo; there is no Laravel integration path, and the extension model is Symfony-bundle-shaped. Borrow the patterns; do not adopt the dependency.
• You need adoption evidence. ~30 stars and zero dependents means no third-party production signal, no community answers, and a single-maintainer bus factor. Do not put this on a revenue path without an internal owner.
• You need managed hosting, SLAs, or a support contract. None of that exists here.
• Your content model is already settled. Migration cost will dominate any benefit; a bespoke exporter against your existing store is cheaper.
• You require migration-based schema management. The project uses doctrine:schema:update --force by design — fine for a self-managed app, incompatible with a governed DBA workflow.

Treat it as reference architecture first, dependency second. The reusable ideas — byte-deterministic rendering, explicit cache version contracts, agent-output traits, tag-based editor extension — are valuable independent of the code.

How to Pitch It (Stakeholders)

To executives (one paragraph): This is a small, MIT-licensed static-site generator for a Symfony CMS. We are not recommending adoption as a platform — it has minimal community traction and no commercial support. We are recommending it as a design reference for two things already on our roadmap: publishing content as deterministic static artifacts, and letting AI agents write into the same content pipeline as humans. Studying it costs days; reinventing its cache-invalidation and reproducibility rules after a production incident costs far more.

To engineering:

• What's genuinely good: renders are required to be byte-deterministic (no random() in a render path), caching is versioned explicitly per renderer, static builds skip unchanged pages off a content hash, and CLI commands support a machine-readable output mode. Each of those is a rule we should adopt whether or not we use the code.
• What's a cautionary tale: the documented footguns are all real product risk — a silently dropped Twig block returning HTTP 200 with missing buttons, an inline editor tool that "looks broken" but isn't, build-order coupling where one package's Vite build deletes another's output. If we build an editor surface, these are the failure classes to test for explicitly.
• Cost to evaluate: a spike is cheap — read packages/docs/content/architecture.md and the static-build path, map its concepts onto our stack, decide. No procurement, no license review beyond MIT.
• Decision requested: fund a short evaluation spike to extract patterns, not a migration project. Revisit actual adoption only if we standardise on Symfony, which we have not.

Bottom line: low adoption, low dependents, single-maintainer — treat as read, not depend. The score reflects maturity risk, not the quality of the ideas inside.