Eleventy Custom Markdown Parser

README.md

Using Eleventy for USWDS projects

This eleventy config does several things to make it easier to work with USWDS:

• Exposes a filter asMarkdown that can be used in hard-coded (non-markdown) HTML files. This uses the same markdown parser that Markdown uses, to prevent issues with having multiple instances or libraries.
• External links get formatted as usa-link--external, and open in a new tab
• Lists are formatted with usa-list
• The typographer setting is enabled, giving us features like smart quotes.

eleventy.config.js

export default function (eleventyConfig) {
  
  // ...
  // other eleventyConfig configuration might be here
  // ...

  let mdLib;

  eleventyConfig.amendLibrary("md", (lib) => {
    mdLib = lib;

    mdLib.set({ html: true, typographer: true });

    mdLib.renderer.rules.bullet_list_open = () => `<ul class="usa-list">`;

    mdLib.renderer.rules.link_open = (tokens, idx, options, env, self) => {
      const token = tokens[idx];
      const href = token.attrGet("href");

      if (isExternalLink(href)) {
        token.attrSet("target", "_blank");
        token.attrSet("rel", "noreferrer");
        token.attrSet("class", "usa-link usa-link--external");
      } else {
        token.attrSet("class", "usa-link");
      }
      return self.renderToken(tokens, idx, options);
    };
  });

  eleventyConfig.addFilter("asMarkdown", (content, renderInline = false) => {
    if (!mdLib) {
      throw new Error("mdLib is undefined");
    }
    return renderInline ? mdLib.renderInline(content) : mdLib.render(content);
  });
  
}

utils-isExternalLink.js

const URL_HOSTNAME = "example.com";

export const isExternalLink = (href) => {
  // files located at `/files/` open in a new tab
  if (href?.includes("/files/")) {
    return true;
  }

  try {
    const url = new URL(href);
    const matchesDomain = url.hostname === URL_HOSTNAME;
    const matchesSubDomain = url.hostname.endsWith(`.${URL_HOSTNAME}`);
    const isHttpOrHttps = url.protocol === "http:" || url.protocol === "https:";

    if (!isHttpOrHttps) {
      return false;
    }
    return !matchesDomain && !matchesSubDomain;
  } catch {
    return false;
  }
};