Laravel Docs Laravel Package

Product Decisions This Supports

• Where documentation lives — build vs. buy vs. embed. The real decision isn't "install a package," it's whether docs are a separate platform (ReadMe, GitBook, Docusaurus, Confluence), a static site, or a route inside the Laravel app you already run. This package makes the third option cheap enough to be a genuine choice, because rendering reuses your routing, auth, Blade layout, cache, and deploy pipeline. That's a roadmap-level decision about ownership and run cost, not a technical footnote.
• In-product help as a support-deflection feature. Because docs render as ordinary routes and views, one pipeline can serve end-user guides, API notes, changelogs, internal handbooks, and onboarding material. It enables roadmap bets like "reduce ticket volume with in-app guidance" or "improve developer time-to-first-call" without a second CMS, a second login, or a second publishing process.
• Documentation versioning as an explicit policy. Configurable source resolution lets you pin the docs a user sees to the product version they're running. "Which docs did this customer read?" moves from accident to deliberate decision — important if you support multiple release trains and don't want customers reading guidance for an unreleased version. Retrofitting version-aware paths after URLs are public is painful, so decide early.
• Packaging and access control as a pricing lever. Docs are just routes with a prefix and middleware. Public, authenticated, tenant-scoped, or entitlement-gated ("API reference on Team tier and above") becomes a config-level packaging choice rather than new infrastructure.
• Sequencing the Symfony 8 upgrade. v1.2.0 is compatibility-only — it widens symfony/yaml to include 8.x, with no features or behavior changes. Not a roadmap item, but the kind of small transitive package that surfaces mid-upgrade as a confusing blocker. Clear it early so it stops appearing in composer why-not.
• Deciding explicitly not to build. The alternative is owning front-matter parsing, Markdown rendering, routing, caching, and a view layer forever — a small but permanent, non-differentiating maintenance surface. A defensible "buy," conditional on accepting the maturity risk.
• Discovery task before commitment: the published materials describe two materially different products — local Markdown rendering versus reflection-based doc generation from PHP source. These are different operating models with different failure modes. Resolve which one you're actually adopting before it appears in any roadmap or stakeholder deck.

Signal to weigh honestly: 4 stars, 0 dependents, one maintainer, and a first-time-contributor compatibility PR as the headline release. That is not a healthy ecosystem; it's a personal-scale project. Treat it as off the critical path, or wrap it behind an abstraction you own.

When to Consider This Package

Consider it when:

• You already run a Laravel app and want documentation — internal handbook, developer guides, API notes, end-user help — served inside that app, inheriting its layout, auth, and middleware.
• You're willing to own the Markdown in your own repository (vendored or scheduled-synced), so rendering has no runtime network dependency.
• You want front-matter and index parsing handled by a dependency instead of custom code, and need it to resolve against symfony/yaml 8.x — v1.2.0 is the enabling release.
• Docs are off the critical path: a rendering failure is an inconvenience, never a customer-facing outage. Feature-flag it and degrade to a static fallback link rather than a 500 on your shared layout.
• You prefer a small, readable surface — one config file plus publishable Blade views you can diff and restyle — over a batteries-included platform.
• You'll take the cheap exit hatch: a one-method DocsRenderer interface (~30 lines) bound in a service provider, so swapping the package out is an afternoon, not a sprint.

Look elsewhere when:

• You need vendor support, an SLA, security-response commitments, or multi-maintainer bus factor. With one maintainer and negligible adoption, upstream going quiet is a realistic scenario, not a hypothetical.
• You need real platform capabilities: full-text search at scale, versioned doc hosting, translation workflows, editorial review/approval, analytics, or a headless content API. This is a renderer, not a platform — don't promise search you don't have.
• Documentation will be authored and published by non-engineers. Markdown-in-a-repo plus Composer deploys is a poor editorial workflow for marketing, support, or technical writers.
• You can't control the runtime dependency graph, or you're pinned below Symfony 8 and can't verify that v1.2.0 widened rather than replaced the constraint.
• Docs would be public, SEO-indexed, and customer-facing on day one — the highest-risk configuration, and the one this package is least suited to (no sitemap, no structured data, no CDN story).

Adoption guardrails if you proceed: pin to a minor version (~1.2.0), commit the published config and views so upgrades are a visible diff, gate the route with a named middleware group from the first commit (the route is likely registered unconditionally), check php artisan route:list for prefix collisions on docs, and smoke-test the docs index in CI.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version. We have a recurring decision about where product documentation lives, and separately about whether we keep paying for or maintaining a second system to host it. This package lets us serve Markdown docs from inside the Laravel app we already run, inheriting our login, permissions, and design system. That means documentation becomes a feature of the product rather than a separate platform: it can be versioned per release, gated by tier as a packaging lever, and shipped through our existing deploy pipeline. The cost is small; the risk is vendor maturity — the project has one maintainer and effectively no adoption. We mitigate that by keeping it off the critical path, behind a feature flag with a static fallback, and behind an abstraction roughly 30 lines long that lets us replace it in an afternoon. Recommendation: approve a time-boxed pilot on an internal, authenticated docs surface — the lowest-risk configuration — and revisit for customer-facing docs once it's proven.

For engineering — what we're actually signing up for. Install, publish the config and views, and read the published config end to end; it is the entire API surface. Choose the source model on day one: local Markdown committed to the repo is the correct default; remote fetch adds egress, a 60 req/hour/IP unauthenticated GitHub budget, and a cold-cache failure mode that needs a persistent store warmed at deploy. Wrap the package behind a DocsRenderer interface, gate the route with a named middleware group, make the route's existence environment-dependent, and add one feature test asserting the docs index returns 200 with a known heading — that single test catches config drift, missing source files, cache misconfiguration, and dependency bumps at once. v1.2.0 is dependency hygiene only; take it early so symfony/yaml 8 doesn't surface as a confusing transitive conflict later, and diff the rendered output afterward. Budget a few hours a quarter on changelog review — the ongoing cost here is governance, not code.