WORK-092
ID:WORK-092Status:done

Create @refrakt-md/eleventy adapter package

Build the Eleventy (11ty v3) framework adapter. The simplest integration — no Vite, no bundler, no framework. Just global data files, templates, and renderToHtml().

Priority:lowComplexity:simpleMilestone:v1.0.0Source:ADR-002,SPEC-030
changeset-release/main View source

Criteria completion

No incremental history — criteria tracking started on Apr 19.

Relationships

Implements 2
Related 2
Branches 3
changeset-release/main current done
main doneclaude/file-naming-convention-LJdwR doneclaude/align-sidenav-styling-4MuxV done
History 8
  1. f2b3512
    Content editedby Claude
    Add {ID}-{slug}.md filename convention + migrate filenames subcommand
  2. 59ded4a
    Content editedby Claude
    Implement SPEC-037 plan package hardening: all 7 work items
  3. f262d7b
    Content editedby Claude
    Backfill source attributes on all 123 work items
  4. 4765c91
    Content editedby Claude
    Mark WORK-090, WORK-091, WORK-092 as done with resolution summaries
  5. b94f7d8
    Content editedby Claude
    Implement SPEC-030 Phases 2-4: Nuxt, Next.js, and Eleventy adapters
  6. 11e81a8
    Content editedby Claude
    Add framework work items to v1.0.0 milestone
  7. 982a9db
    Content editedby Claude
    Add documentation ACs to adapter work items and create WORK-093
  8. ead9531
    Created (done)by Claude
    Add work items WORK-088 through WORK-092 for framework adapter system

Acceptance Criteria

  • packages/eleventy/ package exists with correct package.json (peer dep @11ty/eleventy@^3.0.0)
  • Eleventy plugin (plugin.js) configures passthrough copy for Lumina CSS and optionally behaviors JS
  • Data file factory (data.js) calls loadContent() + createTransform() + layoutTransform() + renderToHtml() for each page
  • Example base template (base.njk) renders page HTML via | safe, includes SEO meta tags, links CSS, and initializes behaviors
  • Content directory is kept separate from Eleventy's template discovery (no Markdown-it collision)
  • Pagination config generates one page per content item with correct permalinks
  • Behavior initialization via <script type="module"> in template (with bundled or passthrough-copied behaviors JS)
  • Works with Eleventy 3.0 ESM-native mode
  • Example site renders core runes, layouts, behaviors, and web components correctly
  • Adapter documentation page at site/content/docs/adapters/eleventy.md with installation, project structure, configuration, code examples (plugin setup, global data file, base template, pagination config, behavior script, CSS passthrough), and getting-started guide matching the depth of existing SvelteKit adapter docs

Approach

Eleventy's data cascade is the natural integration point. A global data file runs the entire refrakt pipeline at build time, producing pre-rendered HTML for each page. Eleventy pagination creates one output page per content item. The template is a thin Nunjucks wrapper providing the <html> shell.

No HMR infrastructure needed — Eleventy's --serve mode with BrowserSync triggers full rebuilds on content change, and loadContent() re-reads on each call.

For behaviors JS, either use a simple esbuild step to bundle @refrakt-md/behaviors for the browser, or serve directly from node_modules via passthrough copy.

Dependencies

  • WORK-088 (shared utility extraction)

References

  • SPEC-030 (Phase 4)
  • ADR-002 (Eleventy section)

Resolution

Completed: 2026-04-04

Branch: claude/implement-spec-030-F0LFn

What was done

  • Created packages/eleventy/ with createDataFile factory, refraktPlugin, base.njk template
  • Data file loads content, applies layout transform + renderToHtml, produces pre-rendered pages
  • Lumina Eleventy adapter at packages/lumina/eleventy/index.ts
  • Docs page at site/content/docs/adapters/eleventy.md

Notes

  • Simplest adapter: no Vite, no bundler — just data files and templates
  • Uses dynamic import for @refrakt-md/content to avoid bundling issues
  • Template uses Nunjucks | safe filter for HTML injection