dniccum/nova-documentation
dniccum/nova-documentation adds a complete documentation system to Laravel Nova. Write, organize, and publish Markdown-based guides, help pages, and internal docs directly inside Nova with a built-in editor, navigation, and versioning—no separate CMS needed.
Architecture fit. This is a Nova tool, not a general-purpose documentation platform. Its entire value is proximity: markdown files render inside the admin dashboard that operators already use. Fit is binary — if the estate runs Laravel Nova, the architectural surface is a tools() registration in NovaServiceProvider plus a config file and a markdown directory. If the estate does not run Nova, there is no fit at all; an authenticated route plus a markdown renderer is the equivalent outcome at lower cost. Assess this as an internal-enablement component of the admin panel, not a documentation system of record.
Integration feasibility. Low. composer require + vendor:publish + one line in tools(), then seed home.md on the configured disk. Realistic time-to-first-value is hours, not days. The genuine integration work is not code — it is deciding the disk/path resolution (the disk config resolves relative to that filesystem root, commonly storage/app, not the public disk), establishing that markdown lives in the repo and deploys with the application, and putting a PR checklist item in place so the runbooks do not rot. Multiple doc sets (Developer Docs vs. Support Playbooks) mean multiple registered tool instances, since the package is single-path per instance.
Technical risk. The dominant risk is project size and longevity, not technology. ~37 stars, effectively zero dependents, two contributors arriving in v3.6.0 — a positive bus-factor signal but not a resolution. Treat this as a thin, forkable utility. v3.6.0 is a maintenance release (Laravel 13 compatibility via the automated laravel-shift PR, plus markdown link-processing fixes for #45/#36); it closes no capability gaps. Feature ceiling is real and should be priced in up front: no full-text search, no per-document permissions (access control is tool-level via Nova's canSee), no versioning, no workflow or approvals. Customization is limited to three seams — config, published views, and canSee — with no events or middleware hooks. Secondary risk is silent failure modes that generate support noise rather than outages: malformed front matter drops a page from the nav without error; a missing home.md renders an empty state easily mistaken for a routing failure; filenames are stable URLs so renames break inbound links.
Key questions.
canSee gate is insufficient and the requirement is out of scope.Stack fit. Requires Laravel Nova plus a supported Laravel version — start at v3.6.0 or later, which targets Laravel 13.x. On Laravel 13, earlier tags predate support. Re-read composer.json constraints after bumping; the automated compatibility PR may have shifted the supported range at either end. No database migrations of substance, no queue or worker dependencies, no external service — deployment footprint is markdown files plus config.
Migration path. There is no migration in the data sense; the migration is content and ownership. Sequence it as: (1) stand up the tool against a single home.md to prove disk/path resolution; (2) port the two or three highest-value operational documents — a getting-started guide, a billing or permissions runbook — into the configured path; (3) verify the folder-derived navigation tree renders acceptably at two levels; (4) only then formalize the corpus and the ownership model. Do not bulk-convert a wiki before step 2 proves the rendering and the disk configuration. If versioned docs are required later, the workaround is duplicating the directory tree and pointing a second tool instance at the copy — manual, cheap, and explicitly not a product feature.
Compatibility. Two compatibility axes. Framework: pin to a tested tag and diff the published config after every minor upgrade, since new keys appear without loud breaking changes and missing keys fall back to defaults that may not match intent. Content: v3.6.0 changes markdown link processing behaviour, so after upgrading re-test pages with anchors, query strings, links to non-markdown files, links inside code blocks, and any workaround markup added around the previously broken cases. Prefer relative cross-document links (../billing/invoices.md) over hardcoded absolute URLs, which break if the base URI changes. If views are overridden for branding, pin the package version — view paths shift between releases.
Sequencing. Land the dependency and tool registration in one PR with a single home document. Land the initial corpus in a second PR so the dependency and the content can be rolled back independently. Defer published-view customization and any canSee-based access scoping to a third change once the pattern is proven and the audience is confirmed. Registering the tool conditionally inside tools() via Gate::allows(...) is the right shape for keeping sensitive runbooks out of the menu for non-privileged Nova users — but decide the audience before writing the gate.
Maintenance. Low code maintenance, non-trivial content maintenance. The package ships no hook API, so customizations stay confined to config, published views, and canSee — keep them there and upgrades stay boring. The recurring engineering cost is small but perpetual: config diffs on minor upgrades, a cache clear after production content edits, and eventually a fork if upstream activity lapses. Budget for one engineer to own the fork-readiness posture, not a team.
Support. Support burden lands on two populations. End users hit content problems — a page that silently vanished from the nav because of a malformed front-matter fence or a quoted order value, or a broken inbound link after a filename change. Engineers hit configuration problems, and the debugging order is deterministic: is the tool registered and not filtered by canSee; does the disk config resolve; does path/home.md exist on that disk; is config cached; does the route appear in route:list. Publish that checklist internally so tier-one support does not escalate step-1 issues. Expect a small spike in "docs don't show" tickets in the first weeks, almost always a disk/path mismatch.
Scaling. Scaling dimensions here are content volume and audience, not traffic. Audience scaling is handled by canSee and by registering separate tool instances for separate audiences. Content scaling is the weak axis: no search means navigation-tree browsing only, mitigated by shallow directory depth and a hand-maintained index.md. Plan an explicit reassessment trigger — for example, when the corpus exceeds roughly 15–20 pages or when a second author team joins — at which point the honest options are a real documentation platform or a fork that adds search. Multi-language, approval workflows, and granular RBAC are out of scope and should be treated as signals to re-platform rather than as backlog items against this package.
Failure modes. Rank by likelihood and blast radius. (1) Silent content omission from malformed front matter — highest likelihood, low blast radius, high confusion; mitigate with a PR-time check. (2) Disk/path misconfiguration producing an empty tool — high likelihood during setup, remediated permanently by documenting the resolution rule. (3) Missing home document rendering an empty state that reads as a routing failure. (4) Stale caches after production edits, where content is correct but invisible. (5) Filename renames breaking inbound links, since filenames are effectively stable URLs — change the displayed title via front matter instead. (6) Nova menu label collisions if the tool is renamed to something another tool already uses. (7) Upstream abandonment — low probability near term given the recent maintenance release, high impact, mitigated by keeping the footprint at the three supported seams so a fork is a small lift. All of these are degradations of an internal convenience surface; none touch the application's customer-facing path.
Ramp-up. For engineers: under a day to register the tool, understand the disk/path resolution, and learn the front-matter contract. For content authors: minutes, provided the front-matter rules are documented in a template file rather than discovered by trial. The real ramp-up cost is organizational — establishing the "docs ship with code" habit and the review checklist that keeps runbooks current. Without that, the tool works perfectly and the content quietly goes stale, which is the failure mode that matters most and the one no amount of engineering mitigates.
How can I help you explore Laravel packages today?