Customization

Docs4NIST uses two sets of templates that determine the appearance of the hosted documentation.

Assimilation templates

The first set of templates is used by assimilate_theme() to modify the Sphinx configuration.

These templates can be customized by forking this repository.

conf.py

This template file overlays the html_theme you chose for your documentation with the ntd2d theme, described next.

ntd2d/

This template directory provides a Sphinx theme that modifies your chosen documentation theme.

ntd2d/layout.html

This template file inserts standard NIST headers and footers and a dropdown menu that allows selecting different versions of your documentation.

Some Sphinx themes may display the NIST footer at the top of the page. This occurs when the theme’s CSS conflicts with the dynamically injected NIST header and footer elements.

To fix this, create a custom layout.html template in your _templates/ directory:

{% extends "!layout.html" %}
{%- block extrahead %}
  {{ super() }}
  <!-- Fix NIST footer positioning -->
  <style>
    /* Target the wrapper divs created by NIST JavaScript */
    #nistheadergoeshere {
      position: relative !important;
      display: block !important;
      z-index: 10;
      width: 100%;
    }
    #nistfootergoeshere {
      position: relative !important;
      display: block !important;
      clear: both !important;
      margin-top: 2rem !important;
      width: 100%;
    }
    /* Also target the actual footer/header elements inside */
    #nistfootergoeshere footer,
    #nistheadergoeshere header {
      position: relative !important;
      display: block !important;
    }
    /* Ensure theme content doesn't overlap */
    .wy-grid-for-nav {
      position: relative;
      z-index: 1;
    }
    .wy-nav-content-wrap {
      min-height: calc(100vh - 200px);
    }
    .rst-footer-buttons {
      margin-bottom: 2rem;
    }
  </style>
{%- endblock %}

Add templates_path = ['_templates'] to your conf.py if not already present. The .wy-* selectors target sphinx_rtd_theme; other themes may require different CSS adjustments.

ntd2d/static/ntd2d.css_t

This template file controls the appearance of the dropdown menu.

Pages templates

The second set of templates is used by update_pages() to create the pages on the hosting site that enable switching between different documentation variants.

You can customize any of these templates by copying them to a _templates/ directory at the root of your nist-pages branch and editing them to suit.

These templates use Python string format syntax (Sphinx and pages.nist.gov already fight over Jekyll templating, so we’re not getting fancy, here).

downloads.html

A section inserted into menu.html if a documentation variant has any downloadable output, e.g., PDF or ePUB.

Available substitution keywords are:

• downloads: A pre-formatted string with each downloadable output formatted by download_item.html.

download_item.html

Formats a link to a single downloadable output.

Available substitution keywords are:

• href: URL of the downloadable output.

• kind: Type of downloadable output, e.g., PDF or ePUB.

index.html

The default page for your documentation displayed at https://pages.nist.gov/{repository}.

Available substitution keywords are:

• owner: The GitHub user or organization for your repository.

• repository: The name of your repository.

• variants: The result of filling the variants.html template.

menu.html

The dropdown menu that allows selecting different branches and tags of your documentation.

Available substitution keywords are:

• downloads: The result of filling the downloads.html template.

• tree_url: The GitHub URL corresponding to the active tag or branch.

• variant: The name of the active tag or branch.

• variants: The result of filling the variants.html template.

ntd2d_active.css

Style sheet that controls the appearance of the active tag or branch in the dropdown menu.

Available substitution keywords are:

• variant: The name of the active tag or branch.

variants.html

Lists tags and branches that are configured to serve documentation with this Action.

Available substitution keywords are:

• branches: A pre-formatted string with each git branch formatted by variant_item.html.

• latest: A pre-formatted string with the HEAD of the default GitHub branch formatted by variant_item.html.

• stable: A pre-formatted string with the stable_version that has the highest version identifier, as formatted by variant_item.html.

• stable_versions: A pre-formatted string with the tags or branches that satisfy the PEP 440 version specification and aren’t pre-releases, each formatted by variant_item.html.

• versions: A pre-formatted string with the tags or branches that satisfy the PEP 440 version specification, each formatted by variant_item.html.

variant_item.html

Formats a link to a single tag or branch.

Available substitution keywords are:

• href: URL of the downloadable output.

• kind: Type of downloadable output, e.g., PDF or ePUB.