Statamic Bard Footnotes Laravel Package

Technical Evaluation

Architecture fit: v2.1.0 deepens the package’s fit for Statamic Bard-based editorial workflows by adding an in-editor Sources panel and stabilizing footnote numbering across partial renders. The design remains aligned with a Laravel/Statamic addon architecture: PHP handles field augmentation and rendering, while a ProseMirror/TipTap plugin view handles editor UX through VueRenderer. This is appropriate for citation-heavy content, but the centre of gravity shifts further into frontend editor integration, making TipTap/ProseMirror compatibility a first-class architectural concern.

Integration feasibility: The release appears additive rather than breaking. Existing Bard fields without footnotes mount nothing, read-only fields omit Edit, and existing rendering behaviour is preserved when fields are rendered whole. New helpers in footnotes.js and documented partial-rendering behaviour lower integration risk for teams that split Bard content across templates. However, teams must verify their Statamic, Bard, TipTap, Vue, and asset-build versions against the package’s expectations.

Technical risk: Moderate. The main risks are frontend integration risk around ProseMirror plugin lifecycle, fullscreen remounting, and VueRenderer context/provides; editorial correctness risk around editing a source that affects every citation; and rendering risk around numbering when teams incorrectly number parts independently. The idempotent Footnotes::number() reduces risk, but only if integrators follow the “number whole field once, then split” pattern. New i18n strings are a positive signal, but non-en/de locales will need translation coverage.

Key questions:

• Which Statamic, Bard, TipTap, Vue, and Node versions are officially supported?
• Are there breaking changes for custom themes or overridden Bard/ProseMirror views?
• How are source edits audited or revisioned, given that Apply Source changes every occurrence?
• Does the citation highlight plugin interact safely with undo/redo, collaborative editing, or autosave?
• What is the recommended migration for sites currently rendering field parts with per-part numbering?
• Are the new helpers exported as a stable public API or internal utilities?

Integration Approach

Stack fit: Strong for Laravel/Statamic projects using Bard and TipTap. The package should remain a composer-installed Statamic addon with published assets, but the new editor panel means frontend build and asset publishing are part of the deployment, not just PHP dependency updates. Teams using headless or non-Bard rendering can still benefit from the PHP numbering and augmentation changes, while the Sources UI applies to Bard editor users.

Migration path: Treat v2.1.0 as a minor upgrade with validation gates. Update the package, republish assets, clear Statamic/application caches, rebuild frontend assets if the host app compiles package JS, and verify translations. Existing content should not need data migration. Sites that render Bard fields in parts should adopt the documented pattern: call Footnotes::number() on the whole field once, split, then render each part through Augmentor::convertToHtml(). Remove any workaround that renumbers each part independently.

Compatibility: Confirm compatibility with the project’s Statamic major version, Bard field configuration, TipTap/ProseMirror versions, Vue version, and fullscreen implementation. Check read-only field behaviour, multilingual sites using en/de or custom locales, and custom CSS around the Bard footer toolbar because the new Sources panel mounts before core’s footer toolbar. Verify CSP rules for external links opening in a new tab and any custom sanitization of source URLs.

Sequencing:

1. Inventory Bard fields with footnotes and any partial-rendering templates.
2. Upgrade in a staging environment with representative content, including multiple sources, repeated sources, fullscreen usage, read-only fields, and translated content.
3. Validate source editing updates all citations and that highlights appear while the panel is open.
4. Validate whole-field numbering and fnref-n placement across split renders.
5. Confirm no sources panel appears in fields without footnotes and no Edit control appears in read-only fields.
6. Roll out to editors with a short guide on the new Sources panel, citation navigation, and the fact that footnotes are removed in text rather than from the panel.
7. Deploy to production with asset cache busting and monitor editor console errors.

Operational Impact

Maintenance: Ongoing maintenance increases slightly because the package now owns more editor UI: a ProseMirror plugin view, VueRenderer mounting, fullscreen rebuild behaviour, citation highlighting, and new i18n strings. The PHP side remains relatively contained, but the JS helpers and plugin should be treated as production frontend code with tests. The new pure helpers are a maintainability positive because they are testable against a real ProseMirror schema.

Support: Editorial support needs updated guidance for the Sources panel, “Go to citation”/“Next citation,” source editing across all occurrences, and footnote removal via text. Support teams should know that source edits are global to that source and are not merged. Developers need clear documentation for partial rendering and the requirement to number the whole field once. Non-en/de locales require translation support.

Scaling: Runtime scaling is likely fine because the panel is client-side and mounts only when footnotes exist. Large documents with many citations may see editor-side rendering and highlight costs, so test long-form content. Server-side rendering is not materially heavier unless partial rendering is implemented incorrectly and causes repeated work. The idempotent numbering change is operationally beneficial for cached or partitioned rendering because it avoids inconsistent footnote references across parts.

Failure modes:

• Sources panel fails to mount because of TipTap/VueRenderer version mismatch or missing provides.
• Panel does not rebuild correctly after entering or leaving fullscreen.
• Duplicate or inconsistent footnote numbers when parts are rendered independently instead of numbering the whole field first.
• fnref-n appears in multiple parts, breaking anchor/link behaviour.
• Source edit unexpectedly changes many citations, surprising editors if the global behaviour is not communicated.
• Citation highlight or next-citation navigation fails with custom ProseMirror plugins or unusual document structures.
• Missing translations produce mixed-language editor UI.
• Read-only or non-footnote fields incorrectly expose edit affordances.

Ramp-up: Developer ramp-up is moderate: engineers need familiarity with Statamic Bard, TipTap/ProseMirror plugin views, VueRenderer, and the package’s PHP augmentation flow. Editorial ramp-up is low to moderate: the Sources panel is intentionally familiar, but editors must understand citation navigation, global source edits, and text-based footnote removal. A short demo plus a one-page support note should be sufficient for most content teams.