Though the theme is based on the Federalist-Jekyll starter kit, there are a number of adjustment and customizations throughout the site.

• Each guide is a top level nav item
• Each chapter within a guide is it's own page within the _pages folder
• The first chapter is the landing page for the guide

For any chapter beyond the introduction, you should add an H1 with class usa-sr-only You can do this in the markdown file using the following syntax. This keeps a full html heading hierarchy on the page.

# Guide name
{:.usa-sr-only}

• Each chapter has an illustration that follows the chapter title (i.e. the h2)
• Images should be placed in the _assets/images folder and should be an SVG
• The illustration is added using jekyll-assets and is wrapped in a div with class "chapter__img-container":

<div markdown="1" class="chapter__img-container">
{% asset agile-best-practices.svg class="chapter__img" alt="" %}
</div>

• Each guide contains a sidenav which lists out all of the chapters for that Guide
• The sidenav always lists out all of the chapters, but the subnav within the sidenav is dependent on the chapter. For example

  · Chapter 1
  · Chapter 2
     ° Section 1
     ° Section 2
     ° Section 3
     ° Footnotes
  · Chapter 3

• The sidenav is created using the navigation.yml file under the data folder, and is labeled with the chapter title
• Set sidenav: front matter to the sidenav corresponding to the guide
• The subnav: front matter is unique to each chapter and lists out the subheadings (H3s) within that section
• Generating the subnav needs to be done by hand at the moment ( :/ ), but can be sped up by running the following script on a local version of the in-progress guide:

let h3s = document.querySelectorAll('h3');
let subNav = "";
for (let i = 0; i < h3s.length; i++) {
  let text = h3s[i].innerText;
  let regex = /[!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~]/g;
  let cleanText = text.replace(regex,"");
  let textElements = cleanText.split(" ");
  let href = textElements.join("-").toLowerCase();
  let textPrefix = "- text: ";
  let hrefPrefix = "  href: ";
  let subNavLink = textPrefix + cleanText + "\n" + hrefPrefix + "'#" + href + "'" + "\n";
  subNav +=  subNavLink;
  }
console.log(subNav);

Which will spit out the formatted text in the console for copy pasting — is this the best way to do it? Probably not, but works for now.

• Ideally, subnav links should be one line of text. If the link default link text (i.e. the subheading in the text) is too long, suggest or ask the team for a shorter version of the title.

• The markdown converter might generate footers automatically — will need to check based on the converter
• In the State Guide footers are marked in text with the footnote marker [^reference], and have a corresponding note in the footnotes section. The note is tied with the marker using the following notation [^reference]:.
• For consistency, the key used in the footnote marker (i.e. reference) is the last word in the sentence where the footnote marker is placed.