Port Handbook from Jekyll to 11ty, and from USWDS 2 to USWDS 3 (#3267)

* 11ty

* add menu button in narrow view; fix footer links; fix link color

* published images include original filename instead of JUST a hash/id

* update dependencies; update heading links

* validation fixes

* add post-build step to statically generate page side navs and internal link markup

* fix the header, thanks to @hbillings!

* fix an issue with alignment and a missing border

* remove unused file; fix header link (hopefully)

* move tests of built content back to circleci

* add dependabot

* add Slack links; tweak README; add more info to CONTRIBUTING

* change nav section overflow; update asset script to also rebuild the site so images get put back

Author: mgwalker

.circleci/config.yml

@@ -0,0 +1,69 @@
+version: 2.1
+jobs:
+  build:
+    docker:
+      - image: node:16
+    steps:
+      - checkout
+      - run:
+          name: install dependencies
+          command: npm install
+      - run:
+          name: build
+          command: npm run build
+      - persist_to_workspace:
+          root: .
+          paths:
+            - node_modules
+            - _site
+
+  validate html:
+    docker:
+      - image: node:16
+    steps:
+      - checkout
+      - attach_workspace:
+          at: .
+      - run:
+          name: validate HTML
+          command: npm run test:html-validation
+
+  validate internal links:
+    docker:
+      - image: node:16
+    steps:
+      - checkout
+      - attach_workspace:
+          at: .
+      - run:
+          name: validate internal links
+          command: npm run test:internal-links
+
+  validate links use helper:
+    docker:
+      - image: node:16
+    steps:
+      - checkout
+      - attach_workspace:
+          at: .
+      - run:
+          name: validate internal links use the {% page %} helper
+          command: npm run test:prefixed-links
+
+workflows:
+  version: 2
+  test the built static content:
+    jobs:
+      - build
+      - validate html:
+          name: validate HTML
+          requires:
+            - build
+      - validate internal links:
+          name: validate internal links
+          requires:
+            - build
+      - validate links use helper:
+          name: validate internal links use the {% page %} helper
+          requires:
+            - build

.eleventy.js

@@ -0,0 +1,181 @@
+const { DateTime } = require("luxon");
+const fs = require("fs");
+const { EleventyRenderPlugin } = require("@11ty/eleventy");
+const path = require("path");
+const pluginRss = require("@11ty/eleventy-plugin-rss");
+const pluginNavigation = require("@11ty/eleventy-navigation");
+const markdownIt = require("markdown-it");
+const markdownItAnchor = require("markdown-it-anchor");
+const yaml = require("js-yaml");
+const svgSprite = require("eleventy-plugin-svg-sprite");
+const {
+  imageShortcode,
+  imageWithClassShortcode,
+  slackChannelLinkShortcode,
+  uswdsIconShortcode,
+} = require("./config/shortcodes");
+const { headingLinks } = require("./config/headingLinks");
+const postbuild = require("./config/postbuild");
+
+module.exports = function (config) {
+  // Set pathPrefix for site
+  let pathPrefix = "/";
+
+  config.addPassthroughCopy({ "js/publish/*.js": "assets/js" });
+
+  // Copy Netlify config straight through
+  config.addPassthroughCopy({
+    "config/netlify.yml": "admin/config.yml",
+  });
+
+  // Copy USWDS init JS so we can load it in HEAD to prevent banner flashing
+  config.addPassthroughCopy({
+    "./node_modules/@uswds/uswds/dist/js/uswds-init.js":
+      "assets/js/uswds-init.js",
+  });
+
+  // Copy the favicon
+  config.addPassthroughCopy({
+    "favicon.ico": "favicon.ico",
+  });
+
+  // Add plugins
+  config.addPlugin(EleventyRenderPlugin);
+  config.addPlugin(pluginRss);
+  config.addPlugin(pluginNavigation);
+
+  //// SVG Sprite Plugin for USWDS USWDS icons
+  config.addPlugin(svgSprite, {
+    path: "./node_modules/@uswds/uswds/dist/img/uswds-icons",
+    svgSpriteShortcode: "uswds_icons_sprite",
+    svgShortcode: "uswds_icons",
+  });
+
+  //// SVG Sprite Plugin for USWDS USA icons
+  config.addPlugin(svgSprite, {
+    path: "./node_modules/@uswds/uswds/dist/img/usa-icons",
+    svgSpriteShortcode: "usa_icons_sprite",
+    svgShortcode: "usa_icons",
+  });
+
+  // Allow yaml to be used in the _data dir
+  config.addDataExtension("yaml", (contents) => yaml.load(contents));
+  config.addDataExtension("yml", (contents) => yaml.load(contents));
+
+  config.addFilter("readableDate", (dateObj) => {
+    return DateTime.fromJSDate(dateObj, { zone: "utc" }).toFormat(
+      "dd LLL yyyy"
+    );
+  });
+
+  // https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-date-string
+  config.addFilter("htmlDateString", (dateObj) => {
+    return DateTime.fromJSDate(dateObj, { zone: "utc" }).toFormat("yyyy-LL-dd");
+  });
+
+  // Get the first `n` elements of a collection.
+  config.addFilter("head", (array, n) => {
+    if (!Array.isArray(array) || array.length === 0) {
+      return [];
+    }
+    if (n < 0) {
+      return array.slice(n);
+    }
+
+    return array.slice(0, n);
+  });
+
+  // Return the smallest number argument
+  config.addFilter("min", (...numbers) => {
+    return Math.min.apply(null, numbers);
+  });
+
+  function filterTagList(tags) {
+    return (tags || []).filter(
+      (tag) => ["all", "nav", "post", "posts"].indexOf(tag) === -1
+    );
+  }
+
+  config.addFilter("filterTagList", filterTagList);
+
+  // Create an array of all tags
+  config.addCollection("tagList", function (collection) {
+    let tagSet = new Set();
+    collection.getAll().forEach((item) => {
+      (item.data.tags || []).forEach((tag) => tagSet.add(tag));
+    });
+
+    return filterTagList([...tagSet]);
+  });
+
+  // Customize Markdown library and settings:
+  let markdownLibrary = markdownIt({
+    html: true,
+  }).use(markdownItAnchor, {
+    permalink: headingLinks, // use our custom heading links
+    slugify: config.getFilter("slugify"),
+  });
+  config.setLibrary("md", markdownLibrary);
+
+  // Override Browsersync defaults (used only with --serve)
+  config.setBrowserSyncConfig({
+    callbacks: {
+      ready: function (_, browserSync) {
+        const content_404 = fs.readFileSync("_site/404/index.html");
+
+        browserSync.addMiddleware("*", (req, res) => {
+          // Provides the 404 content without redirect.
+          res.writeHead(404, { "Content-Type": "text/html; charset=UTF-8" });
+          res.write(content_404);
+          res.end();
+        });
+      },
+    },
+    ui: false,
+    ghostMode: false,
+  });
+
+  // If BASEURL env variable exists, update pathPrefix to the BASEURL
+  if (process.env.BASEURL) {
+    pathPrefix = process.env.BASEURL;
+  }
+
+  // Set image shortcodes
+  config.addLiquidShortcode("image", imageShortcode);
+  config.addLiquidShortcode("image_with_class", imageWithClassShortcode);
+  config.addLiquidShortcode("slack_channel", slackChannelLinkShortcode);
+  config.addLiquidShortcode("uswds_icon", uswdsIconShortcode);
+
+  config.addLiquidShortcode("page", (link) => path.join(pathPrefix, link));
+
+  config.on("eleventy.after", async () => {
+    await postbuild();
+  });
+
+  return {
+    // Control which files Eleventy will process
+    // e.g.: *.md, *.njk, *.html, *.liquid
+    templateFormats: ["md", "html", "njk"],
+
+    // Pre-process *.md files with: (default: `liquid`)
+    // Other template engines are available
+    // See https://www.11ty.dev/docs/languages/ for other engines.
+    markdownTemplateEngine: "liquid",
+
+    // Pre-process *.html files with: (default: `liquid`)
+    // Other template engines are available
+    // See https://www.11ty.dev/docs/languages/ for other engines.
+    htmlTemplateEngine: "liquid",
+
+    // Optional (default is shown)
+    pathPrefix: pathPrefix,
+    // -----------------------------------------------------------------
+
+    dir: {
+      input: "pages",
+      includes: "../_includes",
+      data: "../_data",
+      output: "_site",
+    },
+  };
+};

.eleventyignore

@@ -0,0 +1,6 @@
+CONTRIBUTING.md
+LICENSE.md
+README.md
+.github
+config
+___old

.github/ISSUE_TEMPLATE/page-update.md

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

.github/dependabot.yml

@@ -0,0 +1,9 @@
+## Changes proposed in this pull request:
+
+-
+-
+-
+
+## security considerations
+
+[Note the any security considerations here, or make note of why there are none]

.github/pull_request_template.md

@@ -0,0 +1,51 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "20 22 * * 2"
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ["javascript"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v2
+        with:
+          languages: ${{ matrix.language }}
+
+      # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+      # If this step fails, then you should remove it and run the build manually (see below)
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v2
+
+      # ℹ️ Command-line programs to run using the OS shell.
+      # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+
+      # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+      #    and modify them (or add more) to build your code if your project
+      #    uses a compiled language
+
+      #- run: |
+      #   make bootstrap
+      #   make release
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v2

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,40 @@
+name: pull request
+
+on: [pull_request]
+
+jobs:
+  format:
+    name: format code
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          # Use the branch commit instead of the PR merge commit
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - uses: actions/[email protected]
+        with:
+          node-version: 16
+
+      - name: format markdown
+        run: npx prettier .
+
+      - name: commit changes, if necessary
+        id: commit
+        uses: EndBug/add-and-commit@v7
+        with:
+          default_author: github_actions
+          message: format files
+
+      - name: leave a comment, if necessary
+        uses: actions/[email protected]
+        if: steps.commit.outputs.committed == 'true'
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            github.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `I have formatted the code. Please @${context.actor} pull the last commit before pushing any more changes.`
+            });