Statamic Anchor Navigation Laravel Package

Technical Evaluation

Architecture fit

• visuellverstehen/statamic-anchor-navigation is a Statamic addon rather than a general-purpose Laravel package. It only delivers value on a Statamic-backed Laravel application; it is inert in a plain Laravel/API codebase.
• Fits the standard Statamic addon contract: Composer-installed, auto-discovered service provider, consumed from Antlers/Blade templates as a tag. This is a well-understood, low-coupling integration pattern that does not alter application architecture.
• Scope is narrow (anchor/table-of-contents generation from page headings), so it should be treated as a presentation-layer utility, not infrastructure.

Integration feasibility

• Install path is a single composer require, with optional config/view publishing. No database migrations or queue workers expected for this class of addon.
• v1.1.0 explicitly targets Statamic 6 and adds a test suite — the first evidence of automated verification, which materially improves confidence versus v1.0.0.
• Real effort is in verifying output correctness against our content model (heading levels, duplicate headings, non-ASCII/special characters, headings injected by other addons or Replicator sets), not in wiring.

Technical risk

• Breaking change in v1.1.0: "drop v4 support." The release note is ambiguous — it most plausibly means Statamic 4, but could refer to a test/CI toolchain major. This must be disambiguated before any upgrade decision, because it determines whether existing Statamic 4 sites are stranded on v1.0.x.
• Vendor/maintainer risk: single-agency package, one prior release, two contributors (one first-time) in this release. Low bus factor and no stated support policy.
• Dependency-surface risk: an addon that tracks Statamic majors inherits Statamic's own upgrade cadence; being early to Statamic 6 support is positive but may mean Statamic 6-era code paths are less battle-tested.
• Test suite was introduced in this release, so v1.0.0 had no visible automated coverage — treat historical stability claims as unverified.

Key questions

• Does "drop v4 support" mean Statamic 4, Laravel 4, or a dev-tooling major? What is the exact supported matrix (Statamic 4/5/6 × Laravel × PHP) per release?
• Is Statamic 5 still supported in v1.1.0, or is the constraint ^5|^6-style with 4 removed only?
• What is the concrete composer.json constraint set, and does it conflict with anything already in our lockfile?
• What does the new test suite actually cover — rendering, anchor slug generation, or only smoke/install?
• Is there a documented upgrade guide or changelog beyond the auto-generated release notes?
• Who maintains the package, and is there a stated commitment to Statamic 7 and security patching?

Integration Approach

Stack fit

• Appropriate only for Statamic-based Laravel applications. Confirm our Statamic major first: on Statamic 6, v1.1.0 is the only viable line; on Statamic 5, verify the constraint still admits 5; on Statamic 4, v1.0.x is the terminal version.
• Fits both Antlers and Blade-based Statamic themes, though usage syntax and any partials should be validated against our rendering strategy.

Migration path

• Greenfield usage: adopt v1.1.0 pinned with ^1.1.
• Existing v1.0.0 usage: treat as a minor upgrade but validate as if major — the dropped-support line is a compatibility change even if the SemVer number says otherwise. Roll out behind a branch, diff rendered HTML for affected pages, then merge.
• Statamic 4 estates: no upgrade path from this release. Either stay pinned to v1.0.x with a documented exit plan, or sequence the Statamic 4→5/6 platform upgrade first and adopt the addon afterwards.

Compatibility

• Resolve the full constraint triangle (Statamic × Laravel × PHP) from composer.json before committing; do not infer from release notes.
• Check for collisions with existing addons that also post-process content or headings (SEO addons, Bard/Replicator renderers, anchor-ID generators) — overlapping responsibilities here are the most likely source of subtle regressions.
• Verify published config/views do not clash with project-level overrides if we customize output.

Sequencing

1. Confirm Statamic/Laravel/PHP versions in the target application and resolve the "v4" ambiguity.
2. Install v1.1.0 in a non-production branch; confirm auto-discovery and tag registration.
3. Build a fixture page set: nested headings, duplicate heading text, special characters, headings inside components.
4. Compare generated anchors and TOC output against expected; check for duplicate IDs and broken in-page links.
5. Verify front-end behavior (smooth scroll, sticky nav, mobile) and accessibility (focus management, aria attributes).
6. Promote to staging, then production; record the pinned version and the upgrade trigger for Statamic 7.

Operational Impact

Maintenance

• Low ongoing maintenance burden on our side: one Composer dependency, no schema, no scheduled jobs.
• Vendor maintenance is the concern — one release in the project's visible history and a small contributor base. Budget for the possibility of forking or replacing with in-house heading-parsing logic if the addon lags a future Statamic major.
• Pin the exact version and rely on Renovate/Dependabot with manual review; do not auto-merge Statamic-major-adjacent bumps.

Support

• Support channel is GitHub issues only; no SLA, no commercial backing evident. Acceptable for a non-critical presentation feature, not acceptable for anything load-bearing.
• Internal ownership should sit with the team owning the Statamic front end, with a short runbook noting the pinned version and the fallback (disable the tag; content still renders, navigation degrades gracefully).

Scaling

• Negligible server-side footprint: work is per-request heading extraction and template rendering. No additional memory, storage, or cache layers.
• Front-end cost is a small amount of markup plus optional JavaScript for scroll behavior; no measurable impact on Core Web Vitals at typical content volumes.
• Output is cacheable with the rest of the page, so CDN/static caching strategy is unaffected.

Failure modes

• Statamic major upgrade: addon constraint excludes the new major → Composer resolution fails or the tag silently stops rendering. Highest-probability failure; mitigate with a pre-upgrade dependency audit.
• Duplicate/missing anchors: repeated heading text or headings containing punctuation can yield colliding IDs and broken in-page links. Needs a content-convention check or a custom slug callback.
• Content-model blind spots: headings rendered by other addons or inside dynamic components may be excluded from the TOC, producing a nav that under-represents the page.
• Customization drift: if published views are overridden, addon upgrades may not apply cleanly; track overrides explicitly.
• Silent degradation: a rendering failure may produce an empty nav rather than an error — add a lightweight smoke test asserting non-empty TOC output on a known fixture page.

Ramp-up

• Very low: roughly half a day for a Laravel developer unfamiliar with Statamic to install, wire the tag, and validate output; near-zero for an existing Statamic developer.
• The real ramp-up cost is domain knowledge of our content structure and heading conventions, not the package API.
• Document the supported version matrix and the v1.0.x fallback so the next maintainer does not rediscover the "v4" ambiguity during an incident.