@lullabot/eleventy-decision-records 1.0.0

package/src/defaultConfig.json

@@ -0,0 +1,99 @@
+{
+  "site": {
+    "organization": "Lullabot",
+    "url": "https://architecture.lullabot.com/",
+    "legalName": "Lullabot, Inc.",
+    "title": "Decision Records",
+    "description": "Documented architectural decisions and best practices for Lullabot's team",
+    "icon": "brand_family-fill",
+    "social": [
+      {
+        "label": "RSS",
+        "url": "/feed.xml",
+        "icon": "rss_feed"
+      },
+      {
+        "label": "GitHub",
+        "url": "https://www.github.com/Lullabot",
+        "icon": "github"
+      },
+      {
+        "label": "X",
+        "url": "https://x.com/lullabot",
+        "icon": "x"
+      },
+      {
+        "label": "LinkedIn",
+        "url": "https://www.linkedin.com/company/lullabot",
+        "icon": "linkedin"
+      },
+      {
+        "label": "YouTube",
+        "url": "https://www.youtube.com/c/lullabot",
+        "icon": "youtube"
+      },
+      {
+        "label": "Mastodon",
+        "url": "https://toot.cafe/@lullabot",
+        "icon": "mastodon"
+      },
+      {
+        "label": "Facebook",
+        "url": "https://www.facebook.com/lullabot",
+        "icon": "facebook"
+      },
+      {
+        "label": "Terms of Service",
+        "url": "https://www.lullabot.com/terms",
+        "icon": "contract"
+      }
+    ]
+  },
+  "navigation": {
+    "primary": [
+      {
+        "label": "Home",
+        "url": "/",
+        "icon": "home-fill"
+      },
+      {
+        "label": "All decisions",
+        "url": "/{decisions}/",
+        "icon": "verified"
+      }
+    ],
+    "utility": [
+      {
+        "label": "Contributors",
+        "url": "/contributors/",
+        "icon": "group"
+      },
+      {
+        "label": "About",
+        "url": "/about/",
+        "icon": "info"
+      }
+    ]
+  },
+  "practiceAreas": [
+    {
+      "name": "Project Management",
+      "icon": "checklist"
+    },
+    {
+      "name": "Strategy",
+      "icon": "lightbulb"
+    },
+    {
+      "name": "Design",
+      "icon": "design_services"
+    },
+    {
+      "name": "Engineering",
+      "icon": "settings"
+    }
+  ],
+  "dirs": {
+    "decisions": "decisions"
+  }
+}

package/src/index.js

@@ -0,0 +1,227 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, relative, dirname, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+import collections from './lib/collections/index.js';
+import data from './lib/data/index.js';
+import filters from './lib/filters/index.js';
+import plugins from './lib/plugins/index.js';
+import shortcodes from './lib/shortcodes/index.js';
+import themeConfig from './config.js';
+
+const themeRoot = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+/**
+ * Resolves the on-disk root of an installed package, regardless of
+ * whether its export map exposes package.json.
+ */
+function packageRoot(name, probe = name) {
+  const entry = require.resolve(probe);
+  const marker = join('node_modules', ...name.split('/'));
+  return entry.slice(0, entry.indexOf(marker) + marker.length);
+}
+
+/**
+ * Adds the theme's template directories to the Nunjucks environment
+ * Eleventy builds for the project.
+ *
+ * The theme deliberately extends that environment rather than supplying
+ * one of its own. Constructing an environment here would mean loading a
+ * second copy of Nunjucks, which will conflict with Eleventy's.
+ *
+ * Eleventy's own search paths (the project's includes directory, then
+ * its working directory) stay ahead of the theme's, so a project file
+ * of the same name still takes precedence.
+ */
+function addThemeSearchPaths(eleventyConfig, searchPaths) {
+  eleventyConfig.on('eleventy.engine.njk', ({ environment }) => {
+    for (const loader of environment.loaders ?? []) {
+      if (Array.isArray(loader.searchPaths)) {
+        loader.searchPaths.push(...searchPaths);
+      }
+    }
+  });
+}
+
+/**
+ * Pages the theme provides. Each is registered as a virtual template
+ * unless the project has a real file at the same input path.
+ */
+const PAGES = [
+  'decisions.njk',
+  'topics.njk',
+  'practice-areas.njk',
+  'contributors.njk',
+  'contributor.njk',
+];
+
+/**
+ * Layouts the theme provides, registered as virtual templates in the
+ * includes directory unless the project overrides them on disk.
+ */
+const LAYOUTS = ['page.njk', 'adr.njk'];
+
+const ASSETS = ['favicon.njk', 'search_index.njk'];
+
+/**
+ * Default content the theme ships so a fresh project has a homepage and
+ * an about page. These live at the theme root rather than under
+ * templates/ because they are prose a project is expected to replace.
+ */
+const CONTENT = ['index.md', 'about.md'];
+
+/**
+ * Extensions Eleventy will render a page from, used to decide whether a
+ * project already provides its own version of a theme page.
+ */
+const TEMPLATE_EXTENSIONS = ['md', 'njk', 'html', 'liquid', '11ty.js'];
+
+/**
+ * True when the project has its own template that would take the theme
+ * page's place. The extension is ignored so a project's about.njk
+ * replaces the theme's about.md rather than fighting it for /about/.
+ */
+function hasOverride(dir, name) {
+  const base = name.slice(0, name.indexOf('.'));
+  return TEMPLATE_EXTENSIONS.some((ext) =>
+    existsSync(join(dir, `${base}.${ext}`)),
+  );
+}
+
+/**
+ * Development only (DECISION_RECORDS_DEV=1, set by `npm start`): watches
+ * the theme's own files so a linked checkout rebuilds on edit. The virtual
+ * templates are read at config time, so the watch also resets the config.
+ *
+ * Registered as a glob because Eleventy 4 keeps directory targets bare and
+ * then rejects every file under them as unmatched. Eleventy 3 has a
+ * different problem: it reports changes outside the project relative to
+ * the nearest shared parent directory, so the reset target is registered
+ * a second time in that form, without its leading `../` segments.
+ */
+function watchTheme(eleventyConfig) {
+  if (!process.env.DECISION_RECORDS_DEV) {
+    return;
+  }
+  const rel = relative('.', themeRoot).split(sep).join('/');
+  eleventyConfig.addWatchTarget(`${rel}/**`, { resetConfig: true });
+
+  const remapped = rel.replace(/^(\.\.\/)+/, '');
+  if (remapped !== rel && !isEleventy4(eleventyConfig)) {
+    eleventyConfig.addWatchTarget(`${remapped}/**`, { resetConfig: true });
+  }
+}
+
+function isEleventy4(eleventyConfig) {
+  try {
+    eleventyConfig.versionCheck('>=4.0.0-0');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export default function (eleventyConfig, options = {}) {
+  const opts = themeConfig(options);
+
+  const inputDir = eleventyConfig.directories?.input ?? './src/';
+  const layoutsDir =
+    eleventyConfig.directories?.layouts ??
+    eleventyConfig.directories?.includes ??
+    './src/_includes/';
+
+  opts.iconDirs = [
+    ...(options.iconDirs ?? [join(inputDir, 'assets/icons')]),
+    join(themeRoot, 'assets/icons'),
+    join(
+      packageRoot(
+        '@material-symbols/svg-400',
+        '@material-symbols/svg-400/rounded/search.svg',
+      ),
+      'rounded',
+    ),
+  ];
+
+  eleventyConfig.addGlobalData('site', opts.site);
+  eleventyConfig.addGlobalData('navigation', opts.navigation);
+  eleventyConfig.addGlobalData('practiceAreas', opts.practiceAreas);
+  eleventyConfig.addGlobalData('dirs', opts.dirs);
+
+  // Nunjucks resolves includes from the project first, then the theme,
+  // so any theme partial or stylesheet can be overridden by creating a
+  // file of the same name in the project's includes directory.
+  addThemeSearchPaths(eleventyConfig, [
+    join(themeRoot, 'templates/partials'),
+    join(themeRoot, 'assets'),
+  ]);
+
+  collections(eleventyConfig, join(inputDir, opts.dirs.decisions, '*.md'));
+  data(eleventyConfig, opts.dirs.decisions);
+  filters(eleventyConfig);
+  plugins(eleventyConfig, opts);
+  shortcodes(eleventyConfig, opts);
+
+  // Theme assets copy file-by-file so a project file at the same path
+  // under src/assets/ replaces the theme's copy instead of colliding.
+  const projectAssets = join(inputDir, 'assets');
+  const themeAssets = join(themeRoot, 'assets');
+  for (const entry of readdirSync(themeAssets, {
+    recursive: true,
+    withFileTypes: true,
+  })) {
+    if (!entry.isFile()) continue;
+    const rel = relative(themeAssets, join(entry.parentPath, entry.name));
+    if (existsSync(join(projectAssets, rel))) continue;
+    eleventyConfig.addPassthroughCopy({
+      [relative('.', join(themeAssets, rel))]: `/${rel}`,
+    });
+  }
+  if (existsSync(projectAssets)) {
+    eleventyConfig.addPassthroughCopy({ [projectAssets]: '/' });
+  }
+  eleventyConfig.addPassthroughCopy({
+    [relative('.', join(packageRoot('@orama/orama'), 'dist/browser'))]:
+      '/js/orama',
+  });
+
+  watchTheme(eleventyConfig);
+
+  for (const name of LAYOUTS) {
+    if (!existsSync(join(layoutsDir, name))) {
+      eleventyConfig.addTemplate(
+        relative(inputDir, join(layoutsDir, name)),
+        readFileSync(join(themeRoot, 'templates/layouts', name), 'utf8'),
+      );
+    }
+  }
+
+  for (const name of PAGES) {
+    if (!hasOverride(inputDir, name)) {
+      eleventyConfig.addTemplate(
+        name,
+        readFileSync(join(themeRoot, 'templates/pages', name), 'utf8'),
+      );
+    }
+  }
+
+  for (const name of CONTENT) {
+    if (!hasOverride(inputDir, name)) {
+      eleventyConfig.addTemplate(
+        name,
+        readFileSync(join(themeRoot, name), 'utf8'),
+        { templateEngineOverride: 'njk,md' },
+      );
+    }
+  }
+
+  for (const name of ASSETS) {
+    if (!hasOverride(inputDir, name)) {
+      eleventyConfig.addTemplate(
+        name,
+        readFileSync(join(themeRoot, 'templates/assets', name), 'utf8'),
+      );
+    }
+  }
+}

package/src/index.md

@@ -0,0 +1,28 @@
+---
+title: Decision Records
+description: Documented architectural decisions and best practices
+eleventyExcludeFromCollections: true
+---
+
+# {{ title }}
+
+An Architectural Decision Record (ADR) captures a single software design choice that addresses an architecturally significant requirement. Our collection of ADRs forms a decision log that helps the team understand the history and reasoning behind key choices.
+
+Maintaining these records helps us:
+
+- Speed up onboarding for new team members
+- Avoid blindly accepting or reversing past decisions
+- Formalize the decision-making process across the team
+
+<h2 class="section-heading" id="practice-areas">Explore by Practice Area</h2>
+
+<div class="practice-areas">
+{%- for area in practiceAreas %}
+  {%- set areaAdrs = collections.adrs | withPracticeArea(area.name) %}
+  <a href="/practice-areas/{{ area.name | slugify }}/" class="practice-area">
+    <span class="icon">{% icon area.icon %}</span>
+    <span class="name">{{ area.name }}</span>
+    <span class="count">{{ areaAdrs | length }}</span>
+  </a>
+{%- endfor %}
+</div>

package/src/lib/collections/adrs.js

@@ -0,0 +1,10 @@
+/**
+ * All ADRs sorted by date descending.
+ */
+export function makeAdrs(glob) {
+  return function adrs(collectionApi) {
+    return collectionApi
+      .getFilteredByGlob(glob)
+      .sort((a, b) => b.date - a.date);
+  };
+}

package/src/lib/collections/contributors.js

@@ -0,0 +1,15 @@
+/**
+ * Unique set of all contributors across ADRs.
+ */
+export function makeContributors(glob) {
+  return function contributors(collectionApi) {
+    const adrs = collectionApi.getFilteredByGlob(glob);
+    const contributors = new Set();
+    for (const adr of adrs) {
+      for (const contributor of adr.data.contributors || []) {
+        contributors.add(contributor);
+      }
+    }
+    return [...contributors].sort();
+  };
+}

package/src/lib/collections/index.js

@@ -0,0 +1,14 @@
+import { makeAdrs } from './adrs.js';
+import { makeTopics } from './topics.js';
+import { makeContributors } from './contributors.js';
+
+/**
+ * Register all custom collections with Eleventy. All three derive from the
+ * same glob, so `dirs.decisions` is the single place a project changes to
+ * move its records.
+ */
+export default function (eleventyConfig, glob) {
+  eleventyConfig.addCollection('adrs', makeAdrs(glob));
+  eleventyConfig.addCollection('topics', makeTopics(glob));
+  eleventyConfig.addCollection('contributors', makeContributors(glob));
+}

package/src/lib/collections/topics.js

@@ -0,0 +1,18 @@
+/**
+ * Topics with counts, sorted by count descending.
+ */
+export function makeTopics(glob) {
+  return function topics(collectionApi) {
+    const adrs = collectionApi.getFilteredByGlob(glob);
+    const counts = new Map();
+    for (const adr of adrs) {
+      for (const topic of adr.data.topics || []) {
+        const key = topic.toLowerCase();
+        counts.set(key, (counts.get(key) || 0) + 1);
+      }
+    }
+    return [...counts.entries()]
+      .map(([label, count]) => ({ label, count }))
+      .sort((a, b) => b.count - a.count);
+  };
+}

package/src/lib/data/index.js

@@ -0,0 +1,19 @@
+/**
+ * Register all global data with Eleventy. Markdown files inside the
+ * decisions directory get the ADR layout; everything else gets the
+ * plain page layout.
+ */
+export default function (eleventyConfig, decisionsDir) {
+  eleventyConfig.addGlobalData('layout', 'page.njk');
+  eleventyConfig.addGlobalData('eleventyComputed', {
+    layout: (data) => {
+      if (
+        data.page.inputPath.includes(`/${decisionsDir}/`) &&
+        data.page.inputPath.endsWith('.md')
+      ) {
+        return 'adr.njk';
+      }
+      return data.layout;
+    },
+  });
+}

package/src/lib/filters/collections.js

@@ -0,0 +1,63 @@
+/**
+ * Filters a collection of ADRs to those with a given contributor.
+ *
+ * @example
+ * {{ collections.adrs | byContributor("Jane Doe") }}
+ * → [adr1, adr3]
+ */
+export function byContributor(collection, contributor) {
+  return collection.filter((item) =>
+    (item.data.contributors || []).includes(contributor),
+  );
+}
+
+/**
+ * Filters a collection of ADRs to those with a given topic.
+ *
+ * @example
+ * {{ collections.adrs | withTopic("accessibility") }}
+ * → [adr2, adr5]
+ */
+export function withTopic(collection, topic) {
+  const needle = topic.toLowerCase();
+  return collection.filter((item) =>
+    (item.data.topics || []).some((t) => t.toLowerCase() === needle),
+  );
+}
+
+/**
+ * Filters a collection of ADRs to those with a given practice area.
+ *
+ * @example
+ * {{ collections.adrs | withPracticeArea("Engineering") }}
+ * → [adr1, adr4]
+ */
+export function withPracticeArea(collection, practiceArea) {
+  return collection.filter((item) => item.data.practiceArea === practiceArea);
+}
+
+/**
+ * Returns a new object with the given key set to the given value.
+ * Useful for accumulating counts in Nunjucks loops.
+ *
+ * @example
+ * {% set counts = counts | setKey("css", 3) %}
+ */
+export function setKey(obj, key, value) {
+  return { ...obj, [key]: value };
+}
+
+/**
+ * Returns the top N topic labels from a { topic: count } map,
+ * sorted by count descending.
+ *
+ * @example
+ * {{ topicCounts | topTopics(3) }}
+ * → ["css", "accessibility", "react"]
+ */
+export function topTopics(counts, n) {
+  return Object.entries(counts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, n)
+    .map(([label]) => label);
+}

package/src/lib/filters/dates.js

@@ -0,0 +1,68 @@
+const Temporal =
+  globalThis.Temporal ?? (await import('@js-temporal/polyfill')).Temporal;
+
+/**
+ * Returns a relative time string (e.g. "3 months ago").
+ *
+ * @example
+ * {{ adr.data.date | timeSince }}
+ * → "3 months ago"
+ */
+export function timeSince(date) {
+  const from = Temporal.PlainDate.from(
+    new Date(date).toISOString().slice(0, 10),
+  );
+  const now = Temporal.Now.plainDateISO();
+  const duration = from.until(now, { largestUnit: 'years' });
+  const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'always' });
+
+  if (duration.years > 0) {
+    return rtf.format(-duration.years, 'year');
+  }
+  if (duration.months > 0) {
+    return rtf.format(-duration.months, 'month');
+  }
+  if (duration.days > 0) {
+    return rtf.format(-duration.days, 'day');
+  }
+  return 'today';
+}
+
+/**
+ * Formats a date as "Month DD, YYYY".
+ *
+ * @example
+ * {{ adr.data.date | datetimeFormat }}
+ * → "January 1, 2024"
+ */
+export function datetimeFormat(date) {
+  const d = new Date(date);
+  return d.toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    timeZone: 'UTC',
+  });
+}
+
+/**
+ * Returns the current four-digit year.
+ *
+ * @example
+ * {{ null | year }}
+ * → "2026"
+ */
+export function year() {
+  return new Date().getFullYear().toString();
+}
+
+/**
+ * Returns an ISO date string (YYYY-MM-DD) for use in <time datetime>.
+ *
+ * @example
+ * {{ adr.data.date | isoDate }}
+ * → "2024-01-01"
+ */
+export function isoDate(date) {
+  return new Date(date).toISOString().slice(0, 10);
+}

package/src/lib/filters/index.js

@@ -0,0 +1,26 @@
+import { timeSince, datetimeFormat, year, isoDate } from './dates.js';
+import {
+  byContributor,
+  withTopic,
+  withPracticeArea,
+  setKey,
+  topTopics,
+} from './collections.js';
+import { spaceless, scrollable } from './strings.js';
+
+/**
+ * Register all custom filters with Eleventy.
+ */
+export default function (eleventyConfig) {
+  eleventyConfig.addFilter('timeSince', timeSince);
+  eleventyConfig.addFilter('datetimeFormat', datetimeFormat);
+  eleventyConfig.addFilter('year', year);
+  eleventyConfig.addFilter('isoDate', isoDate);
+  eleventyConfig.addFilter('byContributor', byContributor);
+  eleventyConfig.addFilter('withTopic', withTopic);
+  eleventyConfig.addFilter('withPracticeArea', withPracticeArea);
+  eleventyConfig.addFilter('setKey', setKey);
+  eleventyConfig.addFilter('topTopics', topTopics);
+  eleventyConfig.addFilter('spaceless', spaceless);
+  eleventyConfig.addFilter('scrollable', scrollable);
+}

package/src/lib/filters/strings.js

@@ -0,0 +1,23 @@
+import { parse } from 'node-html-parser';
+
+/**
+ * Strips whitespace at the start/end and between HTML tags.
+ */
+export function spaceless(html) {
+  return html.replace(/^\s+/, '').replace(/>\s+</g, '><').replace(/\s+$/, '');
+}
+
+/**
+ * Wraps each table in a box that can scroll sideways, so a wide table is
+ * not cut off by the content column. js/scrollable.js makes the box
+ * keyboard-reachable only while it actually overflows.
+ *
+ * {{ content | scrollable | safe }}
+ */
+export function scrollable(html) {
+  const root = parse(html);
+  for (const table of root.querySelectorAll('table')) {
+    table.replaceWith(`<div class="table-scroll">${table.toString()}</div>`);
+  }
+  return root.toString();
+}

package/src/lib/plugins/bundle.js

@@ -0,0 +1,23 @@
+import { transform } from 'lightningcss';
+import pluginBundle from '@11ty/eleventy-plugin-bundle';
+
+/**
+ * Register the bundle plugin with lightningcss minification.
+ */
+export function bundle(eleventyConfig) {
+  eleventyConfig.addPlugin(pluginBundle, {
+    transforms: [
+      function (content) {
+        if (this.type === 'css') {
+          const { code } = transform({
+            filename: 'bundle.css',
+            code: Buffer.from(content),
+            minify: true,
+          });
+          return code.toString();
+        }
+        return content;
+      },
+    ],
+  });
+}

package/src/lib/plugins/index.js

@@ -0,0 +1,16 @@
+import { bundle } from './bundle.js';
+import { markdown } from './markdown.js';
+import { toc } from './toc.js';
+import { rss } from './rss.js';
+import { syntaxHighlight } from './syntax-highlight.js';
+
+/**
+ * Register all plugins with Eleventy.
+ */
+export default function (eleventyConfig, opts) {
+  bundle(eleventyConfig);
+  markdown(eleventyConfig);
+  toc(eleventyConfig);
+  rss(eleventyConfig, opts.site);
+  syntaxHighlight(eleventyConfig);
+}

package/src/lib/plugins/markdown.js

@@ -0,0 +1,10 @@
+import MarkdownIt from 'markdown-it';
+import markdownItAnchor from 'markdown-it-anchor';
+
+/**
+ * Configure the Markdown library with anchor links.
+ */
+export function markdown(eleventyConfig) {
+  const mdLib = new MarkdownIt({ html: true }).use(markdownItAnchor);
+  eleventyConfig.setLibrary('md', mdLib);
+}