@lullabot/eleventy-decision-records

An Eleventy (v3 or v4) theme plugin for documenting architectural decision records (ADRs).

Install it into an Eleventy project and you get the listing pages, per-topic and per-contributor pages, search, and an Atom feed — without copying any of it into your repository.

Getting Started

npm install @lullabot/eleventy-decision-records

Eleventy is a peer dependency (3.x, or the 4.x prereleases), so install it too if you have not already:

npm install --save-dev @11ty/eleventy

Register the plugin in your Eleventy config:

import decisionRecords from '@lullabot/eleventy-decision-records';

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(decisionRecords, {
    site: {
      organization: 'Your Organization',
      url: 'https://decisions.example.com/',
    },
  });

  return {
    markdownTemplateEngine: 'njk',
    htmlTemplateEngine: 'njk',
    dir: {
      input: 'docs',
    },
  };
}

Both template engines must be set to njk — the theme's pages and layouts are Nunjucks, including the markdown ones. Your project also needs "type": "module" in its package.json.

Site metadata, navigation, and practice areas are configured through the plugin options only. The theme registers them as global data, which Eleventy merges over any _data/site.json, _data/navigation.json, or _data/practiceAreas.json in your project.

Then write decision records as markdown files in docs/decisions/, and build as usual:

npx eleventy --serve

The theme supplies a homepage and an about page until you add your own. Anything it provides can be replaced by putting a file of the same name in your project — see Customizing.

Documentation

• Customizing for your organization — plugin options, overriding templates, styles, and icons
• Writing ADRs — naming convention and frontmatter fields
• Development — commands, testing, CI/deployment
• Architecture — how the plugin is put together

License

See LICENSE for details.

The Gabarito font files in src/assets/fonts/ are licensed separately under the SIL Open Font License 1.1. See src/assets/fonts/OFL.txt.