ScanGov components

Shared Eleventy templates and includes used across ScanGov sites.

Usage

Copy templates to each site's content/ directory. Copy _includes/ files to each site's _includes/ directory.

Syncing to the sites

Always do a full sync. When a shared file changes here (public/css/scangov.css, an _includes/ file), copy the whole file to every site: scangov-com, scangov, docs, standards, data, and my.scangov.com. Never add a few lines to an older copy in a site. Rebuild scripts/bundle.css where it is tracked (scangov-com, standards). Then run node scripts/check-sync.js; it must report no drift except the entries listed in its knownDrift. If a site is behind, bring it fully up to date in the same pull request.

All templates require layout: false in front matter to prevent directory-level layout defaults from wrapping non-HTML output.

Templates

robots.njk

Outputs /robots.txt. Allows all crawlers and references the sitemap.

Requires in site.json:

• url — site base URL

security.njk + security-root.njk

Outputs /.well-known/security.txt (canonical) and /security.txt (convenience copy). Standard security disclosure file per securitytxt.org. Both files serve identical content; the Canonical field in both points to /.well-known/security.txt. Two files are required because GitHub Pages is static and cannot redirect between paths.

Requires in site.json:

• url — site base URL
• org-url — organization URL (used for Contact and Policy fields)
• securityExpires — ISO 8601 expiry date (e.g. 2027-01-01T00:00:00.000Z)

sitemap.njk

Outputs /sitemap.xml. Includes all Eleventy collection pages except those with sitemap: false in front matter. Emits <lastmod> as ISO 8601 from modified when available, falling back to date, and omits the element entirely when neither is set (search engines ignore empty or non-ISO values). Pages generated by pagination have no date unless the template sets one, so give those templates a modified value via eleventyComputed.

Requires in site.json:

• url — site base URL

Pagination and addAllPagesToCollections: sitemap.xml (and anything else that loops collections.all — search, a site index, RSS) only sees pages that are actually in collections.all. Eleventy's pagination feature only adds the first generated page to collections.all by default — any per-item pagination block (one page per person, domain, topic, dataset, etc., with its own permalink: referencing the pagination alias) must set addAllPagesToCollections: true, or every page after the first silently disappears from the sitemap with no build error. Reference example: orgs/index.html or profile/overview.html in the scangov repo. If pages are meant to stay out of collections on purpose, say so explicitly instead of just omitting the flag — addAllPagesToCollections: false (opts a per-item pagination page out specifically) or eleventyExcludeFromCollections: true (excludes a template from every collection outright, e.g. redirects.njk) — so a missing flag always reads as "forgotten," never "ambiguous." Each of the 5 deployed Eleventy sites also runs scripts/check-sitemap-completeness.js in CI to catch a forgotten flag automatically.

Includes

File	Description
analytics.html	Google Analytics script (requires site.gaId)
favicon.html	Favicon link tags
footer.html	Site footer
header.html	Site <head> with meta, OG, schema
jumbotron.html	Page hero/banner
jumbotron-default.html	Default page hero
nav.html	Site navigation
related.html	Related content links
search.html	Search UI
sidenav.html	Sidebar navigation
style.html	CSS link tags
js.html	JS script tags
toc.html	Table of contents
toc-mobile.html	Mobile table of contents
actions.html	Action buttons
audio.html	Audio player
action-buttons.html	Page or document actions: Edit, Copy link, Copy, Download, Print, Reset. Icon-only, btn-sm. Needs public/js/action-buttons.js. See Action buttons below.
cta.html	Fixed bottom band with Plans, Demo, Copy link and Copy buttons (included from footer.html)
connect.html	Social/connect links
details.html	Expandable details
feedback.html	Feedback form
filter-pill.html	Filter pill UI
image.html	Responsive image
post-badges.html	Post metadata badges
post-links.html	Post navigation links
scangov.html	ScanGov branding
schema-docs.html	JSON-LD schema for docs pages
tool-form.html	Single-field tool form (label, large input, large button). Set toolFormId, toolFieldLabel, toolPlaceholder, toolButtonLabel before including. Wrap in the tool page shell: container > row > col-md-2 / col-md-8 / col-md-2
404.html	404 error page

Buttons

Two styles, one size rule, defined once in public/css/scangov.css:

Style	Classes	Use for
Primary	btn btn-primary	The one main action on a view (form submit, Save, Get started)
Secondary	btn btn-outline-primary	Everything else (go to a page, Cancel, Close, Edit, Remove, Copy, Download)

• Default size. btn-sm only for: an icon-only page action toolbar, a table row or cell, a row action inside a card or list, and an "Add" button inside a form. Never for a form submit, Generate, a call to action (Plans, Demo), or a modal confirm. One size per group. No btn-lg.
• Buttons side by side sit in d-flex gap-2. scangov.css adds a gap for a missed case, but do not rely on it.
• btn-sm has its own, much smaller shadow (--bs-shadow-sm: a 1px offset, not 4px). Cards, inputs and regular buttons keep the shared shadow.
• <a> goes somewhere, <button> does something. Both take the same classes.
• Icons are leading and decorative, and always match the label color; the button's gap spaces them.
• Tabs, view switchers, pagination, accordions and the close X are not buttons.
• node scripts/check-sync.js also fails on any other btn-* class in a site repo.

The full rules are in the buttons skill in ScanGov/skills, and every state is shown in public/templates/buttons.html.

Action buttons

One set of page actions on every site, in one order: Edit, Copy link, Copy, Download, Print, Share, Rescan, Reset. They are icon-only, btn-sm, with aria-label and title. Reset keeps its text because it clears what the person entered.

Function	Icon	Label
Edit	fa-pen	Edit
Copy link	fa-link	Copy link
Copy	fa-copy	Copy (a menu: Text, Markdown)
Download	fa-download	Download (a menu: HTML, JSON, Markdown, Text, Word)
Print	fa-print	Print
Share	fa-share-from-square	Share
Rescan	fa-arrows-rotate	Rescan
Reset	fa-rotate-left	Reset
Back	fa-arrow-left	Back
Customize	fa-sliders	Customize (text, in an accordion)
Sample	fa-spray-can-sparkles	Sample (text)

• Icon-only fits a toolbar of repeated actions with familiar icons. Keep the text when the action stands alone, is consequential (Reset, Delete, Remove), uses an unfamiliar icon, or is the primary action in a form.
• Copy and Download are one button each, with a menu. A format that does not apply is left out: formats that need a document are left out when the page has none, a menu with one format is a single button, and a menu with none is removed. A site adds its own formats (CSV, PDF) with window.sgActions.register(name, definition).
• Messages: an instant action (copy, download) shows a check in the button for 2 seconds and a live region announces it ("Link copied", "Markdown copied", "Downloaded {file}"). A failure shows a toast with text. A long action (rescan, generate) is disabled with a spinner while it runs, then a toast says what happened. Use window.sgActions.succeed, fail, setState and announce from JS-built buttons.
• Include _includes/action-buttons.html and public/js/action-buttons.js. The page needs <span id="action-status" ...>, which the include adds. Print hides action buttons and the call-to-action band.
• Every state is shown in public/templates/action-buttons.html.

Scorecard

The public scorecard (my.scangov.com /public/:orgkey/:siteslug/report) and the scangov.org report pages share one card markup. _includes/grade-card.html shows each variant; public/css/scangov.css holds .card-grade and .card-grade-sm.

• One card for Overall, then one per indicator, in alphabetical order. No indicator is pinned last.
• Card parts: header (label and info icon), body (the grade in div.display-1), optional footer.
• Color comes from the score (text-bg-success, -warning, -danger); the grade is always shown as a letter, so color is never the only signal.
• Footers are left-aligned.
• The theme follows the system setting (prefers-color-scheme). Do not add a theme toggle.
• Info icons and links inside a status card (text-bg-success, -warning, -danger) take the card's text color in both themes: white on red, dark on green and yellow. scangov.css handles it; do not set a color on the icon.
• Icon colors: black in light mode. Check scangov.css for a color rule when you add an icon, and sync the CSS to all sites.
• One icon per function, everywhere: Sample is fa-spray-can-sparkles; Customize (a collapsed group of optional settings) is fa-sliders.