@lullabot/eleventy-decision-records 1.0.0

package/src/lib/plugins/rss.js

@@ -0,0 +1,24 @@
+import { feedPlugin } from '@11ty/eleventy-plugin-rss';
+
+/**
+ * Register the Atom feed plugin, served at /feed.xml.
+ */
+export function rss(eleventyConfig, site) {
+  eleventyConfig.addPlugin(feedPlugin, {
+    type: 'atom',
+    outputPath: '/feed.xml',
+    collection: {
+      name: 'adrs',
+      limit: 0,
+    },
+    metadata: {
+      language: 'en',
+      title: `${site.title} — ${site.organization}`,
+      subtitle: site.description,
+      base: site.url,
+      author: {
+        name: site.organization,
+      },
+    },
+  });
+}

package/src/lib/plugins/syntax-highlight.js

@@ -0,0 +1,8 @@
+import pluginSyntaxHighlight from '@11ty/eleventy-plugin-syntaxhighlight';
+
+/**
+ * Register the syntax highlighting plugin.
+ */
+export function syntaxHighlight(eleventyConfig) {
+  eleventyConfig.addPlugin(pluginSyntaxHighlight);
+}

package/src/lib/plugins/toc.js

@@ -0,0 +1,11 @@
+import pluginTOC from 'eleventy-plugin-toc';
+
+/**
+ * Register the table of contents plugin.
+ */
+export function toc(eleventyConfig) {
+  eleventyConfig.addPlugin(pluginTOC, {
+    tags: ['h2', 'h3'],
+    wrapper: '',
+  });
+}

package/src/lib/shortcodes/icons.js

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { parse } from 'node-html-parser';
+
+/**
+ * Resolves an icon name to a file path by checking each directory in
+ * order. The plugin assembles the list as: project icon overrides,
+ * then the theme's custom icons, then Material Symbols.
+ */
+function resolveIcon(iconDirs, name) {
+  for (const dir of iconDirs) {
+    const path = join(dir, `${name}.svg`);
+    if (existsSync(path)) {
+      return path;
+    }
+  }
+  throw new Error(`Icon "${name}" not found in: ${iconDirs.join(', ')}`);
+}
+
+/**
+ * Returns a standalone SVG suitable for use as a favicon.
+ * Embeds a <style> block so the icon adapts to light/dark mode.
+ *
+ * Usage: {% favicon "brand_family-fill" %}
+ */
+export function makeFavicon(iconDirs) {
+  return function favicon(name) {
+    const file = resolveIcon(iconDirs, name);
+    const root = parse(readFileSync(file, 'utf8'));
+    const svg = root.querySelector('svg');
+
+    svg.removeAttribute('width');
+    svg.removeAttribute('height');
+
+    const style = parse(`
+    <style>
+      svg {
+        background-color: #fff;
+      }
+
+      path {
+        fill: #01070b;
+      }
+
+      @media(prefers-color-scheme:dark) {
+        svg {
+          background-color: #01070b;
+        }
+        path {
+          fill: #fff;
+        }
+      }
+    </style>
+  `);
+    svg.insertAdjacentHTML('afterbegin', style.toString());
+
+    return root.toString();
+  };
+}
+
+/**
+ * Inlines an SVG icon. Checks the project's icon directory first, then
+ * the theme's custom SVGs, then falls back to Material Symbols.
+ *
+ * Usage: {% icon "home-fill" %}
+ *        {% icon "github", "GitHub" %}
+ */
+export function makeIcon(iconDirs) {
+  return function icon(name, label) {
+    const file = resolveIcon(iconDirs, name);
+    const root = parse(readFileSync(file, 'utf8'));
+    const svg = root.querySelector('svg');
+
+    svg.removeAttribute('width');
+    svg.removeAttribute('height');
+    svg.setAttribute('fill', 'currentColor');
+
+    for (const el of svg.querySelectorAll('[fill]')) {
+      el.setAttribute('fill', 'currentColor');
+    }
+
+    if (label) {
+      svg.setAttribute('role', 'img');
+      svg.setAttribute('aria-label', label);
+    } else {
+      svg.setAttribute('aria-hidden', 'true');
+    }
+
+    return root.toString();
+  };
+}

package/src/lib/shortcodes/index.js

@@ -0,0 +1,11 @@
+import { makeFavicon, makeIcon } from './icons.js';
+import { oramaIndex } from './search.js';
+
+/**
+ * Register all custom shortcodes with Eleventy.
+ */
+export default function (eleventyConfig, opts) {
+  eleventyConfig.addShortcode('favicon', makeFavicon(opts.iconDirs));
+  eleventyConfig.addShortcode('icon', makeIcon(opts.iconDirs));
+  eleventyConfig.addShortcode('oramaIndex', oramaIndex);
+}

package/src/lib/shortcodes/search.js

@@ -0,0 +1,32 @@
+import { create, insert, save } from '@orama/orama';
+import striptags from 'striptags';
+import he from 'he';
+import { isoDate } from '../filters/dates.js';
+
+const SCHEMA = {
+  url: 'string',
+  title: 'string',
+  topics: 'string[]',
+  context: 'string',
+  content: 'string',
+  status: 'string',
+  date: 'string',
+};
+
+export async function oramaIndex(adrs) {
+  const db = create({ schema: SCHEMA });
+
+  for (const adr of adrs) {
+    insert(db, {
+      url: adr.page.url,
+      title: adr.data.title,
+      topics: adr.data.topics || [],
+      context: adr.data.context || '',
+      content: he.decode(striptags(adr.content)),
+      status: adr.data.status,
+      date: isoDate(adr.data.date),
+    });
+  }
+
+  return JSON.stringify(save(db));
+}

package/src/templates/assets/favicon.njk

@@ -0,0 +1,7 @@
+---
+permalink: /favicon.svg
+eleventyExcludeFromCollections: true
+layout: false
+---
+
+{% favicon site.icon %}

package/src/templates/assets/search_index.njk

@@ -0,0 +1,13 @@
+---
+layout: false
+permalink: /searchindex.json
+eleventyExcludeFromCollections: true
+---
+
+{% filter spaceless %}
+  {% set rendercache %}
+    {% for adr in collections.adrs %}
+      {{ adr.content }}
+    {% endfor %}
+  {% endset %}
+{% endfilter %}{% oramaIndex collections.adrs %}

package/src/templates/layouts/adr.njk

@@ -0,0 +1,59 @@
+---
+layout: page.njk
+---
+
+<h1>{{ title }}</h1>
+
+<dl class="adr-detail-meta">
+  <dt>Date</dt>
+  <dd>
+    <time datetime="{{ date | isoDate }}">{{ date | datetimeFormat }}</time>
+  </dd>
+
+  {%- if practiceArea %}
+    <dt>Practice Area</dt>
+    <dd>
+      <a href="/practice-areas/{{ practiceArea | slugify }}/"
+        >{{ practiceArea }}</a
+      >
+    </dd>
+  {%- endif %}
+
+  {%- if contributors | length %}
+    <dt>Contributors</dt>
+    <dd>
+      {%- for contributor in contributors %}
+        <a href="/contributors/{{ contributor | slugify }}/"
+          >{{ contributor }}</a
+        >{% if not loop.last %},{% endif %}
+      {%- endfor %}
+    </dd>
+  {%- endif %}
+
+  {%- if topics | length %}
+    <dt>Topics</dt>
+    <dd class="adr-detail-topics">
+      {%- for topic in topics %}
+        <a class="tag" href="/topics/{{ topic | lower | slugify }}/"
+          >{{ topic }}</a
+        >
+      {%- endfor %}
+    </dd>
+  {%- endif %}
+</dl>
+
+{%- set tocList = content | toc %}
+<div class="adr-body{{ ' has-toc' if tocList }}">
+  {%- if tocList %}
+    <div class="toc-wrapper">
+      <nav class="toc" aria-labelledby="toc-heading">
+        <h2 id="toc-heading">On this page:</h2>
+        {{ tocList | safe }}
+      </nav>
+    </div>
+  {%- endif %}
+
+  <div class="adr-content">{{ content | scrollable | safe }}</div>
+</div>
+
+<script type="module" src="/js/scrollable.js"></script>

package/src/templates/layouts/page.njk

@@ -0,0 +1,136 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{ title or site.title }} — {{ site.organization }}</title>
+    <meta name="description" content="{{ description or site.description }}" />
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <style>
+      @view-transition {
+        navigation: auto;
+      }
+    </style>
+    <link
+      rel="preload"
+      href="/fonts/gabarito-v9-latin-regular.woff2"
+      as="font"
+      type="font/woff2"
+      crossorigin
+    />
+    <link
+      rel="preload"
+      href="/fonts/gabarito-v9-latin-500.woff2"
+      as="font"
+      type="font/woff2"
+      crossorigin
+    />
+    <link
+      rel="preload"
+      href="/fonts/gabarito-v9-latin-700.woff2"
+      as="font"
+      type="font/woff2"
+      crossorigin
+    />
+    {% css %}{% include "styles/reset.css" %}{% endcss %}
+    {% css %}{% include "styles/fonts.css" %}{% endcss %}
+    {% css %}{% include "styles/tokens.css" %}{% endcss %}
+    {% css %}{% include "styles/typography.css" %}{% endcss %}
+    {% css %}{% include "styles/layout.css" %}{% endcss %}
+    {% css %}{% include "styles/recent-decisions.css" %}{% endcss %}
+    {% css %}{% include "styles/search-dialog.css" %}{% endcss %}
+    {% css %}{% include "styles/footer.css" %}{% endcss %}
+    {% css %}{% include "styles/pages.css" %}{% endcss %}
+    {% css %}{% include "styles/content.css" %}{% endcss %}
+    {% css %}{% include "styles/tags.css" %}{% endcss %}
+    {% css %}{% include "styles/view-transitions.css" %}{% endcss %}
+    <link rel="stylesheet" href="{% getBundleFileUrl 'css' %}" />
+  </head>
+  <body>
+    <a href="#site-main" class="skip-link">Skip to main content</a>
+
+    {% include "site-nav.njk" %}
+
+    <main class="site-main" id="site-main">{{ content | safe }}</main>
+
+    {% include "recent-decisions.njk" %}
+    {% include "footer.njk" %}
+
+    <dialog id="search-dialog" aria-labelledby="search-dialog-title">
+      <header>
+        <h2 id="search-dialog-title">Search Decisions</h2>
+        <form method="dialog">
+          <button aria-label="Close search">{% icon "close" %}</button>
+        </form>
+      </header>
+      <input
+        type="search"
+        placeholder="Search decisions…"
+        aria-label="Search decisions"
+        autofocus
+      />
+      <p class="results-summary" aria-hidden="true"></p>
+      <p class="visually-hidden" aria-live="polite" aria-atomic="true"></p>
+      <ol>
+        <template>
+          <li>
+            <article>
+              <h3><a></a></h3>
+              <p class="snippet"></p>
+              <footer>
+                <span class="status"></span>
+                <span class="tags"></span>
+                <span class="age"></span>
+              </footer>
+            </article>
+          </li>
+        </template>
+      </ol>
+    </dialog>
+
+    <script>
+      document
+        .querySelector('.site-nav footer button')
+        .addEventListener('click', () => {
+          const nav = document.querySelector('.site-nav');
+          const btn = document.querySelector('.site-nav footer button');
+          const isExpanded = nav.classList.contains('expanded');
+          const isMobile = window.matchMedia('(max-width: 48rem)').matches;
+
+          if (isExpanded && isMobile) {
+            nav.classList.add('closing');
+            nav.classList.remove('expanded');
+            btn.setAttribute('aria-expanded', 'false');
+            nav.querySelector('.menu').addEventListener(
+              'animationend',
+              () => {
+                nav.classList.remove('closing');
+              },
+              { once: true },
+            );
+          } else {
+            const expanded = nav.classList.toggle('expanded');
+            btn.setAttribute('aria-expanded', String(expanded));
+          }
+        });
+
+      const searchDialog = document.getElementById('search-dialog');
+      document
+        .querySelector('.site-nav button[aria-label="Search"]')
+        .addEventListener('click', () => {
+          searchDialog.showModal();
+        });
+    </script>
+    <script type="module" src="/js/search.js"></script>
+    <script type="speculationrules">
+      {
+        "prefetch": [
+          {
+            "where": { "href_matches": "/*" },
+            "eagerness": "moderate"
+          }
+        ]
+      }
+    </script>
+  </body>
+</html>

package/src/templates/pages/contributor.njk

@@ -0,0 +1,51 @@
+---
+pagination:
+  data: collections.contributors
+  size: 1
+  alias: contributor
+permalink: 'contributors/{{ contributor | slugify }}/'
+eleventyExcludeFromCollections: true
+eleventyComputed:
+  title: 'Decisions by {{ contributor }}'
+  description: 'Architectural decision records contributed to by {{ contributor }}'
+---
+
+{%- set contributorAdrs = collections.adrs | byContributor(contributor) %}
+
+<h1>Decisions by {{ contributor }}</h1>
+<p class="page-description">{{ description }}</p>
+
+<div class="adr-filters">
+  <span class="adr-count"
+    >{{ contributorAdrs | length }}
+    decision{{ "s" if contributorAdrs | length != 1 }}</span
+  >
+</div>
+
+<ol class="adr-list" reversed>
+  {%- for adr in contributorAdrs %}
+    <li class="adr-item">
+      <div class="adr-header">
+        <span class="adr-status adr-status--{{ adr.data.status }}">
+          {% if adr.data.status == "accepted" %}{% icon "verified" %}{% else %}{% icon "cancel" %}{% endif %}
+          {{ adr.data.status }}
+        </span>
+        <time datetime="{{ adr.date | isoDate }}"
+          >{{ adr.date | timeSince }}</time
+        >
+      </div>
+      <a class="adr-title" href="{{ adr.url }}">{{ adr.data.title }}</a>
+      {%- if adr.data.context %}
+        <p class="adr-context">{{ adr.data.context }}</p>
+      {%- endif %}
+      <div class="adr-meta">
+        {%- if adr.data.practiceArea %}
+          <span class="tag">{{ adr.data.practiceArea }}</span>
+        {%- endif %}
+        {%- for topic in adr.data.topics %}
+          <span class="tag">{{ topic }}</span>
+        {%- endfor %}
+      </div>
+    </li>
+  {%- endfor %}
+</ol>

package/src/templates/pages/contributors.njk

@@ -0,0 +1,46 @@
+---
+title: Contributors
+description: Team members who have contributed to our decision records
+permalink: /contributors/
+eleventyExcludeFromCollections: true
+---
+
+<h1>{{ title }}</h1>
+<p class="page-description">{{ description }}</p>
+
+<table class="contributor-table">
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Decisions</th>
+      <th>Top Topics</th>
+    </tr>
+  </thead>
+  <tbody>
+    {%- for contributor in collections.contributors %}
+      {%- set adrs = collections.adrs | byContributor(contributor) %}
+      {%- set topicCounts = {} %}
+      {%- for adr in adrs %}
+        {%- for topic in adr.data.topics %}
+          {%- set key = topic | lower %}
+          {%- set topicCounts = topicCounts | setKey(key, (topicCounts[key] or 0) + 1) %}
+        {%- endfor %}
+      {%- endfor %}
+      <tr>
+        <td>
+          <a href="/contributors/{{ contributor | slugify }}/"
+            >{{ contributor }}</a
+          >
+        </td>
+        <td>{{ adrs | length }}</td>
+        <td>
+          <div class="tags">
+            {%- for topic in topicCounts | topTopics(3) %}
+              <span class="tag">{{ topic }}</span>
+            {%- endfor %}
+          </div>
+        </td>
+      </tr>
+    {%- endfor %}
+  </tbody>
+</table>

package/src/templates/pages/decisions.njk

@@ -0,0 +1,41 @@
+---
+title: All Decisions
+description: A complete list of architectural decision records
+permalink: /{{ dirs.decisions }}/
+eleventyExcludeFromCollections: true
+---
+
+<h1>{{ title }}</h1>
+<p class="page-description">{{ description }}</p>
+
+<div class="adr-filters">
+  <span class="adr-count">{{ collections.adrs | length }} decisions</span>
+</div>
+
+<ol class="adr-list" reversed>
+  {%- for adr in collections.adrs %}
+    <li class="adr-item">
+      <div class="adr-header">
+        <span class="adr-status adr-status--{{ adr.data.status }}">
+          {% if adr.data.status == "accepted" %}{% icon "verified" %}{% else %}{% icon "cancel" %}{% endif %}
+          {{ adr.data.status }}
+        </span>
+        <time datetime="{{ adr.date | isoDate }}"
+          >{{ adr.date | timeSince }}</time
+        >
+      </div>
+      <a class="adr-title" href="{{ adr.url }}">{{ adr.data.title }}</a>
+      {%- if adr.data.context %}
+        <p class="adr-context">{{ adr.data.context }}</p>
+      {%- endif %}
+      <div class="adr-meta">
+        {%- if adr.data.practiceArea %}
+          <span class="tag">{{ adr.data.practiceArea }}</span>
+        {%- endif %}
+        {%- for topic in adr.data.topics %}
+          <span class="tag">{{ topic }}</span>
+        {%- endfor %}
+      </div>
+    </li>
+  {%- endfor %}
+</ol>

package/src/templates/pages/practice-areas.njk

@@ -0,0 +1,48 @@
+---
+pagination:
+  data: practiceAreas
+  size: 1
+  alias: area
+permalink: 'practice-areas/{{ area.name | slugify }}/'
+eleventyExcludeFromCollections: true
+eleventyComputed:
+  title: '{{ area.name }} Decisions'
+  description: 'Architectural decision records for {{ area.name }}'
+---
+
+{%- set areaAdrs = collections.adrs | withPracticeArea(area.name) %}
+
+<h1>{{ area.name }} Decisions</h1>
+
+<p class="page-description">{{ description }}</p>
+
+<div class="adr-filters">
+  <span class="adr-count"
+    >{{ areaAdrs | length }} decision{{ "s" if areaAdrs | length != 1 }}</span
+  >
+</div>
+
+<ol class="adr-list" reversed>
+  {%- for adr in areaAdrs %}
+    <li class="adr-item">
+      <div class="adr-header">
+        <span class="adr-status adr-status--{{ adr.data.status }}">
+          {% if adr.data.status == "accepted" %}{% icon "verified" %}{% else %}{% icon "cancel" %}{% endif %}
+          {{ adr.data.status }}
+        </span>
+        <time datetime="{{ adr.date | isoDate }}"
+          >{{ adr.date | timeSince }}</time
+        >
+      </div>
+      <a class="adr-title" href="{{ adr.url }}">{{ adr.data.title }}</a>
+      {%- if adr.data.context %}
+        <p class="adr-context">{{ adr.data.context }}</p>
+      {%- endif %}
+      <div class="adr-meta">
+        {%- for topic in adr.data.topics %}
+          <span class="tag">{{ topic }}</span>
+        {%- endfor %}
+      </div>
+    </li>
+  {%- endfor %}
+</ol>

package/src/templates/pages/topics.njk

@@ -0,0 +1,50 @@
+---
+pagination:
+  data: collections.topics
+  size: 1
+  alias: topic
+permalink: 'topics/{{ topic.label | slugify }}/'
+eleventyExcludeFromCollections: true
+eleventyComputed:
+  title: 'Decisions about {{ topic.label }}'
+  description: 'Architectural decision records tagged with {{ topic.label }}'
+---
+
+{%- set topicAdrs = collections.adrs | withTopic(topic.label) %}
+
+<h1>Decisions about {{ topic.label }}</h1>
+<p class="page-description">{{ description }}</p>
+
+<div class="adr-filters">
+  <span class="adr-count"
+    >{{ topicAdrs | length }} decision{{ "s" if topicAdrs | length != 1 }}</span
+  >
+</div>
+
+<ol class="adr-list" reversed>
+  {%- for adr in topicAdrs %}
+    <li class="adr-item">
+      <div class="adr-header">
+        <span class="adr-status adr-status--{{ adr.data.status }}">
+          {% if adr.data.status == "accepted" %}{% icon "verified" %}{% else %}{% icon "cancel" %}{% endif %}
+          {{ adr.data.status }}
+        </span>
+        <time datetime="{{ adr.date | isoDate }}"
+          >{{ adr.date | timeSince }}</time
+        >
+      </div>
+      <a class="adr-title" href="{{ adr.url }}">{{ adr.data.title }}</a>
+      {%- if adr.data.context %}
+        <p class="adr-context">{{ adr.data.context }}</p>
+      {%- endif %}
+      <div class="adr-meta">
+        {%- if adr.data.practiceArea %}
+          <span class="tag">{{ adr.data.practiceArea }}</span>
+        {%- endif %}
+        {%- for t in adr.data.topics %}
+          <span class="tag">{{ t }}</span>
+        {%- endfor %}
+      </div>
+    </li>
+  {%- endfor %}
+</ol>

package/src/templates/partials/footer.njk

@@ -0,0 +1,12 @@
+<footer class="site-footer">
+  <ul class="social-links">
+    {%- for item in site.social %}
+      <li>
+        <a href="{{ item.url }}" aria-label="{{ item.label }}">
+          {% icon item.icon %}
+        </a>
+      </li>
+    {%- endfor %}
+  </ul>
+  <p>&copy; {{ null | year }} {{ site.legalName }} CC-BY 4.0.</p>
+</footer>