Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

12.9 KB
Raw Blame
import syntaxHighlight from "@11ty/eleventy-plugin-syntaxhighlight";
import { DateTime } from "luxon";
import markdownIt from "markdown-it";
import markdownItAnchor from "markdown-it-anchor";
import { readFileSync } from "node:fs";

// The blog is always served under this path on munderdiffl.in. We prefix links
// explicitly (via the `u` filter) instead of Eleventy's pathPrefix, whose HTML
// auto-transform double-applies the prefix when combined with the `url` filter.
// Theme previews override both via env (see package.json preview:* scripts).
const BASE = process.env.BLOG_BASE || "/blog";
const OUT = process.env.BLOG_OUT || "../docs/blog";

// The single media manifest: every hero image, inline figure, and video for
// every post lives in this one file (built by scripts/build-media-manifest.mjs,
// filled in by the image-generation script).
const media = JSON.parse(readFileSync("src/_data/media.json", "utf8"));

export default function (eleventyConfig) {
  // ---- markdown: heading anchors so the TOC + deep links work ----
  const md = markdownIt({ html: true, linkify: true, typographer: true }).use(
    markdownItAnchor,
    {
      permalink: markdownItAnchor.permalink.linkInsideHeader({
        symbol: "#",
        class: "anchor",
        placement: "after",
        ariaHidden: true,
      }),
      level: [2, 3],
      slugify,
    }
  );
  // A markdown table of npm commands is wider than a phone. Left bare it widens
  // the whole document, which drags the sticky masthead off-screen with it.
  // Wrapping every table in its own scroll box keeps the overflow local.
  md.renderer.rules.table_open = () => '<div class="table-scroll">\n<table>\n';
  md.renderer.rules.table_close = () => '</table>\n</div>\n';

  eleventyConfig.setLibrary("md", md);

  // ---- plugins ----
  eleventyConfig.addPlugin(syntaxHighlight);

  // ---- passthrough static assets ----
  eleventyConfig.addPassthroughCopy({ "src/assets": "assets" });

  // ---- collections ----
  // All published posts, newest first.
  eleventyConfig.addCollection("posts", (api) =>
    api
      .getFilteredByGlob("src/posts/*.md")
      .filter((p) => !p.data.draft)
      .sort((a, b) => b.date - a.date)
  );

  // Pinned pillar guides (`pinned: true`), in `pinOrder`. They sit above the
  // newest post on the index and first on their topic page, so a fast publishing
  // pace never pushes the reference guides off the top.
  const pinRank = (p) => (p.data.pinned ? (p.data.pinOrder ?? 99) : 1e9);
  eleventyConfig.addCollection("pinned", (api) =>
    api
      .getFilteredByGlob("src/posts/*.md")
      .filter((p) => !p.data.draft && p.data.pinned)
      .sort((a, b) => pinRank(a) - pinRank(b) || b.date - a.date)
  );

  // Everything else, newest first: the index features the first of these.
  eleventyConfig.addCollection("unpinned", (api) =>
    api
      .getFilteredByGlob("src/posts/*.md")
      .filter((p) => !p.data.draft && !p.data.pinned)
      .sort((a, b) => b.date - a.date)
  );

  // "Start here" on the blog index: the guides marked `startHere: true`, in
  // `startOrder`. The index adds the newest posts after them. Pillars keep
  // `pinned` for topic pages; it no longer puts them in Start here.
  eleventyConfig.addCollection("startHere", (api) =>
    api
      .getFilteredByGlob("src/posts/*.md")
      .filter((p) => !p.data.draft && p.data.startHere)
      .sort((a, b) => (a.data.startOrder ?? 99) - (b.data.startOrder ?? 99) || b.date - a.date)
  );

  // Every other post, newest first: the newest few join Start here and the
  // rest fill the index grid, pillars included.
  eleventyConfig.addCollection("notStartHere", (api) =>
    api
      .getFilteredByGlob("src/posts/*.md")
      .filter((p) => !p.data.draft && !p.data.startHere)
      .sort((a, b) => b.date - a.date)
  );

  // Featured posts for the blog home hero, newest first. Opt a post in with
  // `featured: true` in its frontmatter; the newest one leads the hero.
  eleventyConfig.addCollection("featured", (api) =>
    api
      .getFilteredByGlob("src/posts/*.md")
      .filter((p) => !p.data.draft && p.data.featured)
      .sort((a, b) => b.date - a.date)
  );

  // Topic clusters (categories) — derived from each post's `category` field.
  eleventyConfig.addCollection("categories", (api) => {
    const map = {};
    for (const post of api.getFilteredByGlob("src/posts/*.md")) {
      if (post.data.draft) continue;
      const cat = post.data.category;
      if (!cat) continue;
      (map[cat] ||= []).push(post);
    }
    return Object.entries(map)
      .map(([name, posts]) => ({
        name,
        slug: slugify(name),
        posts: posts.sort((a, b) => pinRank(a) - pinRank(b) || b.date - a.date),
      }))
      .sort((a, b) => b.posts.length - a.posts.length);
  });

  // Flat tag list with counts.
  eleventyConfig.addCollection("tagList", (api) => {
    const counts = {};
    for (const post of api.getFilteredByGlob("src/posts/*.md")) {
      if (post.data.draft) continue;
      for (const tag of post.data.tags || []) {
        counts[tag] = (counts[tag] || 0) + 1;
      }
    }
    return Object.entries(counts)
      .map(([name, count]) => ({ name, slug: slugify(name), count }))
      .sort((a, b) => b.count - a.count);
  });

  // ---- filters ----
  eleventyConfig.addFilter("slug", slugify);

  // Root-relative URL with the /blog base. Leaves absolute URLs untouched.
  eleventyConfig.addFilter("u", (p) => {
    if (p === undefined || p === null || p === "") return BASE + "/";
    if (/^https?:\/\//.test(String(p))) return p;
    const path = String(p).startsWith("/") ? p : "/" + p;
    return (BASE + path).replace(/([^:])\/{2,}/g, "$1/");
  });

  eleventyConfig.addFilter("readableDate", (d, zone = "utc") =>
    DateTime.fromJSDate(d, { zone }).toFormat("LLL d, yyyy")
  );
  eleventyConfig.addFilter("isoDate", (d) =>
    DateTime.fromJSDate(d, { zone: "utc" }).toISO()
  );
  eleventyConfig.addFilter("htmlDate", (d) =>
    DateTime.fromJSDate(d, { zone: "utc" }).toFormat("yyyy-LL-dd")
  );
  // Newest publish or update date across posts. The sitemap uses it for the
  // home page lastmod so a rebuild on a later day does not change the file.
  eleventyConfig.addFilter("newestPostDate", (posts) =>
    (posts || []).reduce((max, p) => {
      const d = new Date(p.data.updated || p.date);
      return d > max ? d : max;
    }, new Date(0))
  );

  // Reading time from rendered HTML / raw content (~225 wpm).
  eleventyConfig.addFilter("readingTime", (content) => {
    const text = String(content || "").replace(/<[^>]+>/g, " ");
    const words = text.split(/\s+/).filter(Boolean).length;
    return Math.max(1, Math.round(words / 225));
  });

  eleventyConfig.addFilter("absoluteUrl", (path, base) => {
    try {
      return new URL(path, base).toString();
    } catch {
      return path;
    }
  });

  // Related posts: same category, excluding self, newest first.
  eleventyConfig.addFilter("relatedPosts", (collection, url, category, limit = 3) =>
    (collection || [])
      .filter((p) => p.url !== url && p.data.category === category)
      .sort((a, b) => b.date - a.date)
      .slice(0, limit)
  );

  // Build a table of contents from rendered post HTML (h2 + h3).
  eleventyConfig.addFilter("toc", (html) => {
    const items = [];
    const re = /<h([23])[^>]*\bid="([^"]+)"[^>]*>(.*?)<\/h\1>/gis;
    let m;
    while ((m = re.exec(String(html || "")))) {
      const level = Number(m[1]);
      const id = m[2];
      // strip the appended anchor link + any inline tags
      const text = m[3]
        .replace(/<a class="anchor"[\s\S]*?<\/a>/gi, "")
        .replace(/<[^>]+>/g, "")
        .trim();
      if (text) items.push({ level, id, text });
    }
    return items;
  });

  eleventyConfig.addFilter("byTag", (posts, tag) =>
    (posts || []).filter((p) => (p.data.tags || []).includes(tag))
  );

  eleventyConfig.addFilter("limit", (arr, n) => (arr || []).slice(0, n));
  eleventyConfig.addFilter("excludeSelf", (arr, url) =>
    (arr || []).filter((p) => p.url !== url)
  );

  // ---- media: figures + video, all driven by src/_data/media.json ----

  // Render one manifest entry (hero or inline slot) as a <figure>. Until the
  // generation script flips status to "ready", we render a designed placeholder
  // tinted by the post's topic — never a broken <img>.
  const renderFigure = (entry, category, extraClass = "", caption = "") => {
    if (!entry) return "";
    const cat = slugify(category || "notes");
    const cap = caption ? `<figcaption>${caption}</figcaption>` : "";
    if (entry.status === "ready") {
      return `<figure class="fig ${extraClass}"><img src="${BASE}/${entry.file}" alt="${(
        entry.alt || ""
      ).replace(/"/g, "&quot;")}" loading="lazy" decoding="async" />${cap}</figure>`;
    }
    return `<figure class="fig fig-placeholder t-${cat} ${extraClass}" role="img" aria-label="${(
      entry.alt || "Illustration coming soon"
    ).replace(/"/g, "&quot;")}"><div class="ph-art" aria-hidden="true"><span class="ph-glyph">✶</span><span class="ph-note">illustration on its way</span></div>${cap}</figure>`;
  };

  // {% img "slot-id" %} or {% img "slot-id", "Caption" %} inside a post's
  // markdown — looks up media.json → <this post>.inline["slot-id"].
  eleventyConfig.addShortcode("img", function (slot, caption = "") {
    const slug = this.page?.fileSlug;
    const post = media[slug];
    const entry = post?.inline?.[slot];
    if (!entry) return ""; // slot not declared in the manifest yet — render nothing
    return renderFigure(entry, post.category, "fig-inline", caption);
  });

  // Hero figure for a given slug — used by post.njk (and card thumbs).
  eleventyConfig.addShortcode("hero", function (slugArg) {
    const slug = slugArg || this.page?.fileSlug;
    const post = media[slug];
    if (!post?.hero) return "";
    return renderFigure(post.hero, post.category, "fig-hero");
  });

  // {% youtube "VIDEO_ID", "Human title" %} — click-to-load embed: renders the
  // thumbnail + play button (fast, no third-party JS on page load), swaps in
  // the youtube-nocookie iframe on click. Script lives in base.njk.
  // An empty id (or one starting with "TODO") renders a styled placeholder —
  // same publish-now-fill-later flow as the image manifest.
  eleventyConfig.addShortcode("youtube", (id, title = "Watch on YouTube") => {
    const safeTitle = String(title).replace(/"/g, "&quot;");
    if (!id || String(id).startsWith("TODO")) {
      return `<div class="yt yt-placeholder" role="img" aria-label="Video coming soon: ${safeTitle}">
  <div class="ph-art"><span class="yt-badge" aria-hidden="true"><svg viewBox="0 0 24 24" width="26" height="26" fill="currentColor" aria-hidden="true"><path d="M8 5.5v13l11-6.5z"/></svg></span><span class="ph-note">video on its way</span><span class="yt-ph-title">${safeTitle}</span></div>
</div>`;
    }
    if (!/^[A-Za-z0-9_-]{11}$/.test(String(id))) {
      throw new Error(`youtube shortcode: "${id}" is not an 11 character YouTube video id`);
    }
    return `<div class="yt" data-yt="${id}" data-title="${safeTitle}">
  <button type="button" class="yt-load" aria-label="Play video: ${safeTitle}">
    <img src="https://i.ytimg.com/vi/${id}/hqdefault.jpg" alt="" loading="lazy" decoding="async" />
    <span class="yt-badge" aria-hidden="true"><svg viewBox="0 0 24 24" width="26" height="26" fill="currentColor" aria-hidden="true"><path d="M8 5.5v13l11-6.5z"/></svg></span>
    <span class="yt-title">${safeTitle}</span>
  </button>
</div>`;
  });

  // Card thumbnails: expose the manifest to templates that already have data
  // (media.json is also on the data cascade as `media`), plus a tiny helper.
  eleventyConfig.addFilter("heroReady", (slug) => media[slug]?.hero?.status === "ready");
  eleventyConfig.addFilter("heroFile", (slug) => media[slug]?.hero?.file || "");
  eleventyConfig.addFilter("heroAlt", (slug) => media[slug]?.hero?.alt || "");

  // Link preview (og:image / twitter:image) for a post: its own hero once it is
  // ready, so a shared link shows the post's picture instead of the site default.
  // Width and height come from the PNG header so Facebook and LinkedIn can draw
  // the card on the first share without fetching the file first.
  eleventyConfig.addFilter("heroOg", (slug) => {
    const hero = media[slug]?.hero;
    if (hero?.status !== "ready" || !hero.file) return false;
    const png = readFileSync(`src/${hero.file}`);
    const isPng = png.toString("ascii", 12, 16) === "IHDR";
    return {
      path: `${BASE}/${hero.file}`,
      alt: hero.alt || "",
      width: isPng ? png.readUInt32BE(16) : 0,
      height: isPng ? png.readUInt32BE(20) : 0,
    };
  });

  // ---- config ----
  return {
    dir: {
      input: "src",
      output: OUT,
      includes: "_includes",
      data: "_data",
    },
    markdownTemplateEngine: "njk",
    htmlTemplateEngine: "njk",
    templateFormats: ["njk", "md", "11ty.js"],
  };
}

function slugify(str) {
  return String(str)
    .toLowerCase()
    .trim()
    .replace(/[^\w\s-]/g, "")
    .replace(/[\s_]+/g, "-")
    .replace(/-+/g, "-");
}