Isildur's Bane – a Jekyll meta-template for 18F/TTS guides

This template is deprecated

Isildur's Bane began as an experiment to see if a higher-level guide template abstraction could help minimize non-content-related maintenance work by guide owners. See Goals and Concept of operations for more details.

Two discoveries were made:

• GitHub Actions do not support auto-update of protected branches. While not all TTS guides use protected branches, that's likely an oversight rather than a best practice to be promoted in the context of our org. Working around it would require a Pull Request-approach to updates in downstream guides, which would (mostly) defeat the purpose of this template.
• "Product/market fit": Guide maintainers did not seem to find hands-off automated updates valuable enough to sacrifice styling/structure autonomy in their individual guides.

Consequently, this template will no longer be maintained and will be extracted out from the TTS Engineering Guide.

Goals

This is a template for 18F and TTS guides, built with the following goals and assumptions:

• Guides need minimal stylistic customization beyond the stock usdws-jekyll template.
• Guide maintainers want to focus on content, not servicing dependabot and Snyk PRs.
• Guides at 18F and TTS should have a similar layout/branding/functionality and be compliant with GSA policies.
• Guides can be well-served by a common set of Jekyll plug-ins, components, CircleCI test scripts, etc.

Some guides at 18F/TTS might be exceptions; e.g., the TTS handbook (large volume of content) and 18F Methods Guide (content demands different visual layout).

Once this template is incorporated into a guide GitHub repo, guide maintainers can ignore all the supporting files and solely focus on:

• README.md
• The _guide folder, which has:
  • simplified _config.yml
  • _data folder, with simplified data files
  • _pages folder for Markdown content

Security and dependency updates will automatically be applied to their guide repository.

Relevant discussions

• state of TTS documentation sites - 2020-03-28
• GSA guidelines thread in #practice-leads
• 18F/uswds-jekyll proposal: make more opinionated

Technical details

To achieve these goals, this repository uses:

• usdws-jekyll
• Styling from 18F/ux-guide and 18F/federalist-jekyll-uswds-18f-port
• Code from 18F/before-you-ship and 18F/handbook
• a GitHub Action that downstream guides will (automatically) call to merge updates from this upstream repository
• a guide-specific directory to put configuration and content and simplify the "API" a guide maintainer needs to navigate:
  • _guide/_config.yml, augments the Jekyll/uswds-jekyll _config.yml
  • _guide/_data for only the YAML files and keys that can be altered downstream
  • _guide/_pages
• a separate _data/orgs subdirectory and site configuration key to have optional 18F, Solutions, CoE, or PIF branding. TTS-only branding is enabled by default.
• a Jekyll generator to override values set from YAML files in _data and in _config.yml
  • Note: Federalist does not support multiple Jekyll config files (e.g., --config _config.yml,_guide/_config.yml), requiring custom code
• Git attributes to help ensure this upstream repository does not affect downstream content in _pages, etc.
• Template repository setting in GitHub

Concept of operations

1. Use this repository as a template to create a new repository. Alternatively, merge its content into an existing repository.
2. Edit _guide/_config.yml, _guide/_data/navigation.yml, _guide/_data/header.yml, _guide/_data/anchor.yml, README.md, and content under _guide/_pages. Don't edit anything else if you want to guarantee consistency across guides and automatic updates for security and compliance.
3. Set up Federalist, CircleCI, Snyk, etc.
4. Register sitemap in search.gov.
5. Any security updates, configuration changes, style changes done by the template maintainer get automatically merged into the downstream guide (i.e., once a day).
6. Downstream guides are automatically redeployed with up-to-date dependencies.
7. It is anticipated that eventually there will be non-backwards compatible changes to Jekyll. At that point, some manual intervention might be required.

Development

Once you have instantiated a downstream guide repository and cloned it locally, use Docker to view your site:

1. docker-compose up --build

2. Open http://localhost:4000