mazipan / mazipan/html-tools

Evaluate migration to Eleventy after #1/#3/#8 land

Open
#19 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

build enhancement tracking
Dominant language
HTML
Stars
5
Forks
0
No merged PRs in 30d

Description

Background

We adopted posthtml-include in #18 to deduplicate static partials. It works, but already revealed friction:

  • The site header (HTML Tools / Tool Name) couldn't be extracted because posthtml-include doesn't natively support per-include locals.
  • Cross-tool footer links (#3), per-tool JSON-LD (#1), and FAQ blocks (#8) are all "loop over the tools, render a block" patterns. With Parcel + posthtml-include we'll end up hand-rolling that logic in scripts/build.mjs.

Eleventy (with Nunjucks/Liquid/etc.) handles all of that natively. The question is whether the migration cost is worth it.

When to revisit

Defer for now. Land #1, #3, and #8 with a tools.json manifest driven from scripts/build.mjs first (matching the pattern we already use for sitemap and _redirects). After that lands, re-read this issue and decide:

  • ✅ Migrate if scripts/build.mjs is starting to feel like a templating engine in disguise — repeated render-loop logic, awkward string interpolation, hard-to-maintain conditionals.
  • ❌ Stay on Parcel if the manifest-driven approach is comfortable and the queue plateaus after #8.

The data extraction work for #1/#3/#8 isn't wasted either way — the same tools.json manifest plugs straight into Eleventy as a global data file.

What we'd gain (concrete to this project)

  • Site header partial — finally extractable via {{ tool.icon }} {{ tool.title }}.
  • Cross-tool footer links (#3) — one Nunjucks loop with where slug !== current.slug.
  • Per-tool JSON-LD (#1) — emit WebApplication + BreadcrumbList from frontmatter; layout renders the script tag.
  • FAQ + FAQPage (#8) — frontmatter array drives both the visible <details> markup and the JSON-LD; one source of truth.
  • Per-tool content sections (#6/#15) — natural as Markdown body with frontmatter for the structural fields.
  • Stable URLs — parcel-namer-no-hash workaround disappears; Eleventy outputs filenames as written.

What we'd give up

  • Parcel's asset graph + HMR. Eleventy's dev loop is "rebuild on save" — fast for this size but loses incremental JS/CSS compilation.
  • Built-in JS bundling. The current theme.js + json-utils.js get inlined automatically. Under Eleventy we'd either (a) keep them tiny and inline literally, (b) add esbuild as a separate watch step, or (c) pre-build with a small node script.
  • Tailwind CSS v4 zero-config. Needs explicit wiring under Eleventy: Tailwind CLI watching → output file → Eleventy passthrough copy.
  • A few days of focused migration time.

Migration checklist (for the future PR)

If/when we decide to migrate:

Source layout
  • src/_layouts/base.njk — wraps <head> partials + body + footer
  • src/_layouts/tool.njk — extends base, adds the tool header strip and content section scaffolding
  • src/_includes/ — port the existing _partials/*.html (most of them stay as-is)
  • src/_data/tools.js (or .json) — single source of truth: slug, title, description, icon, canonical URL, category. Drives index page, sitemap, cross-links, JSON-LD, breadcrumbs.
  • Each tool becomes either src/<slug>.njk (Nunjucks-only) or src/<slug>.md with frontmatter (better for content-heavy tools)
Asset pipeline
  • Tailwind: separate watcher (tailwindcss -i input.css -o dist/styles.css --watch) wired into npm run dev
  • JS files (theme.js, json-utils.js): decide between inline-literal or esbuild bundle step
  • Static passthrough: og-image.png, robots.txt, _headers, google254ec9b78a3c3c38.html, favicon SVGs
Build script port
  • sitemap.xml — Eleventy collection + Nunjucks template (sitemap.njk with permalink: sitemap.xml)
  • _redirects — same pattern
  • Post-processing for __BUILD_TIME__ placeholder — Eleventy global data file or shortcode
  • index.html-link rewriting (the href="/" substitution) — handled naturally by Eleventy permalinks
  • JS inlining post-pass — replaced by either esbuild or literal inline templates
Verification
  • Diff dist/ output before/after migration; aside from formatting, content should be byte-equivalent
  • Build time comparison
  • Dev server experience (npm run dev) is acceptable
  • All existing routes and meta tags survive

Notes

  • 11ty is mature, MIT-licensed, and well-aligned with the project's "no client-side framework" mantra — it produces plain static HTML.
  • An in-between option (run Eleventy, then pipe its output through Parcel for asset bundling) is technically possible but adds a second build system to maintain. Pick one.
  • If the eventual answer is "yes migrate", expect ~2–3 days of focused work, mostly in the verification phase.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Revisit this after issues #1, #3, and #8 land, starting with scripts/build.mjs and the resulting tools.json manifest. Compare the current Parcel output with the proposed src/_layouts, src/_includes, and src/_data structure; completion means choosing a build system and verifying routes, meta tags, dist/ equivalence, build time, and npm run dev.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, tailwindcss
Domain
build-system
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.