Skip to main content

Documentation Page

A documentation page template provides a consistent layout for presenting detailed informational content with hierarchical navigation and in-page table of contents.


Overview

The documentation page template is designed for structured content pages that require clear navigation and organization. It combines side navigation for document hierarchy with in-page navigation for quick access to sections within the current page.

This template is ideal for help documentation, user guides, policy pages, technical documentation, and any content that benefits from a hierarchical structure with easy navigation.

Note: This page itself is an example of the documentation page template in action. The side navigation on the left provides hierarchical navigation through the component library, while the "On this page" navigation on the right provides quick links to sections within this page.


Key Elements

Side Navigation

The side navigation component (.usa-sidenav) provides hierarchical navigation for document sections. It allows users to understand the overall structure of the documentation and quickly navigate to different sections or related pages.

<div class="usa-sidenav-container grid-col-2 display-none desktop:display-block">
  <nav aria-label="Secondary navigation">
    <ul class="usa-sidenav">
      <li class="usa-sidenav__item">
        <a href="#"><strong>Section Title</strong></a>
        <ul class="usa-sidenav__sublist">
          <li class="usa-sidenav__item">
            <a href="#">Subsection</a>
          </li>
          <li class="usa-sidenav__item">
            <a href="#" class="usa-current">Current page</a>
          </li>
        </ul>
      </li>
    </ul>
  </nav>
</div>

In-page Navigation

The in-page navigation component (.usa-in-page-nav) automatically generates a table of contents based on heading elements within the page. This "On this page" section helps users quickly scan content and jump to specific sections.

<aside
  class="usa-in-page-nav"
  data-heading-elements="h2 h3"
  data-title-text="On this page"
  data-title-heading-level="h4"
  data-scroll-offset="48"
  data-root-margin="48px 0px -70% 0px"
  data-threshold="1"
></aside>

Content Area

The main content area uses the .usa-prose class to apply consistent typography and spacing. Content should follow a clear heading hierarchy (H1 for page title, H2 for main sections, H3 for subsections) to ensure proper navigation generation and accessibility.

<main class="usa-prose grid-col-fill grid-container margin-x-4">
  <h1 class="usa-page-title">Page Title</h1>
  <p class="usa-intro">Introductory paragraph...</p>

  <h2>Main Section</h2>
  <p>Section content...</p>

  <h3>Subsection</h3>
  <p>Subsection content...</p>
</main>

Related Links

Documentation pages often include related links to help users discover additional resources. These can be presented as inline links within content, summary boxes, or dedicated sections at the end of the page.

<section class="usa-prose">
  <h3>Related resources</h3>
  <ul>
    <li><a href="#">Related page one</a></li>
    <li><a href="#">Related page two</a></li>
    <li><a href="#" class="usa-link--external">External resource</a></li>
  </ul>
</section>


Guidance

When to use the documentation page template

For help documentation and user guides that explain how to use a system or service.
For technical documentation, API references, or developer guides.
For policy pages, terms of service, or legal documentation.
For frequently asked questions (FAQs) organized by topic.
For any structured content that benefits from hierarchical navigation.

Best practices

Use a clear heading hierarchy.
Structure content with H1 for the page title, H2 for main sections, and H3 for subsections. This hierarchy drives both the in-page navigation and accessibility.
Write scannable content.
Use short paragraphs, bullet points, and clear headings to help users quickly find the information they need.
Link to related content.
Help users discover related documentation by including relevant links within your content and in dedicated "Related resources" sections.
Keep the side navigation manageable.
Limit the depth of your navigation hierarchy to avoid overwhelming users. Consider grouping related pages or using expandable sections.
Use consistent page structure.
Maintain a consistent layout across documentation pages so users know what to expect and where to find information.

Accessibility considerations

Use proper heading levels.
Ensure headings follow a logical hierarchy without skipping levels. Screen reader users rely on heading structure to navigate content.
Include skip links.
The template includes a "Skip to main content" link that allows keyboard users to bypass repetitive navigation and jump directly to the main content area.
Use landmark regions.
The template uses semantic HTML elements like <main>, <nav>, <aside>, and <footer> to define page regions that assistive technologies can identify.
Label navigation regions.
Use aria-label attributes to distinguish between multiple navigation regions (e.g., "Primary navigation" vs. "Secondary navigation").
Ensure visible focus indicators.
All interactive elements should have visible focus states so keyboard users can track their location on the page.

USWDS Documentation

For more guidance, view the USWDS Documentation Page Template Documentation.



Looking for U.S. government information and services?
Visit USA.gov