Add 'docs/' from commit '70362ff051543c08b48e2f8065119b2460b99c1a'

git-subtree-dir: docs
git-subtree-mainline: 5b35ea3
git-subtree-split: 70362ff

docs/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby]
+
+gem 'html-proofer'

docs/Gemfile.lock

@@ -0,0 +1,36 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    ethon (0.12.0)
+      ffi (>= 1.3.0)
+    ffi (1.11.1)
+    html-proofer (3.13.0)
+      addressable (~> 2.3)
+      mercenary (~> 0.3)
+      nokogiri (~> 1.10)
+      parallel (~> 1.3)
+      rainbow (~> 3.0)
+      typhoeus (~> 1.3)
+      yell (~> 2.0)
+    mercenary (0.3.6)
+    mini_portile2 (2.4.0)
+    nokogiri (1.10.4)
+      mini_portile2 (~> 2.4.0)
+    parallel (1.18.0)
+    public_suffix (4.0.1)
+    rainbow (3.0.0)
+    typhoeus (1.3.1)
+      ethon (>= 0.9.0)
+    yell (2.2.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  html-proofer
+  tzinfo-data
+
+BUNDLED WITH
+   2.0.2

docs/assets/scss/hugo-uswds-custom.scss

@@ -0,0 +1,4 @@
+.nist-footer {
+  font-family: inherit;
+  z-index: auto !important;
+}

docs/config.yaml

@@ -0,0 +1,57 @@
+# Default page title
+title: "Hugo USWDS"
+# The base URL of the site
+baseURL: https://pages.nist.gov/hugo-uswds-docs/
+# The default language provided by the site
+defaultContentLanguage: en
+languages:
+  en:
+    lang: en
+    languageName: English
+    weight: 1
+# Indicates that metadata provided in page headers is provided
+# in YAML
+MetaDataFormat: "yaml"
+# Configures this theme
+theme: "uswds"
+# If provided, the site will use Google Analytics
+googleAnalytics: UA-42404149-54
+# Creates absolute URLs for all links in the site
+canonifyurls: true
+# Establishes page file metadata based on Git commits info
+# for the associated file
+enableGitInfo: true
+# Configures the syntax Highlighting used by this theme
+pygmentsCodeFences: true
+pygmentsCodefencesGuessSyntax: true
+pygmentsUseClasses: true
+# The following custom parameters are used by the page
+# templates and components.
+params:
+  # Configures the content used in the Basic and Extended
+  # Header components.
+  header:
+    # An optional short name for the site for use on the basic
+    # Header. If not provided, the project_name will be used
+    # instead.
+    project_shortname: "USWDS Hugo Theme"
+    project_name: "United States Web Design System Hugo Theme"
+  # Used to provide the "Improve this Page" link on the bottom
+  # of each page. This setting is optional. If not provided,
+  # the "Improve this Page" link will not be provided
+  contentRepoPath: https://github.com/usnistgov/hugo-uswds-docs/tree/master/website/content
+  # Used to configure the search bar to use search.gov
+  searchAffiliate: oscal
+# There are two main navigation menus that can be configured
+# here. "primary" menu entries appear in the main navigation
+# provided by the Basic and Extended Headers. "secondary" menu
+# entries appear in the Extended Header on the homepage.
+# Navigation can also be configured on any corresponding pages.
+menu:
+  secondary:
+  - name: Website Github
+    url: https://github.com/usnistgov/hugo-uswds-docs
+    weight: 90
+  - name: Theme Github
+    url: https://github.com/usnistgov/hugo-uswds
+    weight: 90

docs/content/_index.md

@@ -0,0 +1,5 @@
+---
+title: "Hugo USWDS Theme Documentation"
+---
+
+This site provides [documentation](documentation/) and [examples](examples/) for using the [United States Web Design System](https://designsystem.digital.gov/) (USWDS) Theme for [Hugo](https://gohugo.io/).

docs/content/documentation/_index.md

@@ -0,0 +1,9 @@
+---
+title: "Documentation"
+menu:
+  primary:
+    name: Documentation
+    weight: 30
+---
+
+TBD

docs/content/documentation/components/_index.md

@@ -0,0 +1,129 @@
+---
+title: "USWDS Components"
+weight: 10
+sidenav:
+  toc:
+    collapsedepth: 3
+---
+
+## Supported Components
+
+The following USWDS components are supported by this theme.
+
+### Alert
+
+{{% usa-tag %}}Component Definition{{% /usa-tag %}} [Alert](https://designsystem.digital.gov/components/alert/)
+
+Alerts are supported by the [usa-alert](../hugo/shortcodes/#usa-alert-shortcode) shortcode.
+
+### Layout Grid
+
+{{% usa-tag %}}Component Definition{{% /usa-tag %}} [Grid](https://designsystem.digital.gov/utilities/layout-grid/)
+
+This theme uses Grid layouts as part of the default [page templates](../hugo/templates/).
+
+The following Hugo shortcodes can be used to customize the grid layout used on a given page.
+
+- [usa-grid-container](../hugo/shortcodes/#usa-grid-container-shortcode): Can be used to center the content on the screen, with a maximum width of desktop (1024px).
+- [usa-grid-row](../hugo/shortcodes/#usa-grid-row-shortcode): Used with the `usa-grid-column` shortcode to support more fine-grained layouts.
+- [usa-grid-column](../hugo/shortcodes/#usa-grid-column-shortcode): Used to layout the spacing of individual columns with a `usa-grid-row` shortcode.
+
+### Header
+
+{{% usa-tag %}}Component Definition{{% /usa-tag %}} [Header](https://designsystem.digital.gov/components/header/)
+
+The USWDS [Basic](../hugo/templates/#the-header-basic-html-template) and [Extended](../hugo/templates/#the-header-extended-html-template) headers are provided in this theme. The "mega menu" variants are not currently supported.
+
+#### Basic Header
+
+{{% usa-tag %}}Component Definition{{% /usa-tag %}} [Basic Header](https://designsystem.digital.gov/components/header/#basic)
+
+The Basic Header uses primary navigation menus defined in the [site-wide](../hugo/configuration-parameters/#primary-and-secondary-navigation) and [page-specific](../hugo/configuration-parameters/#primary-and-secondary-navigation-1) configurations.
+
+The Basic Header is used in the [List](../hugo/templates/#list-template) and [Page](../hugo/templates/#page-template) templates to provide top-level navigation for all pages of the site, other than the homepage.
+
+#### Extended Header
+
+{{% usa-tag %}}Component Definition{{% /usa-tag %}} [Extended Header](https://designsystem.digital.gov/components/header/#extended)
+
+The Extended Header uses primary and secondary navigation menus defined in the [site-wide](../hugo/configuration-parameters/#primary-and-secondary-navigation) and [page-specific](../hugo/configuration-parameters/#primary-and-secondary-navigation-1) configurations.
+
+The Extended Header is used in the [homepage](../hugo/templates/#homepage-template) template to provide top-level navigation for the site's main homepage.
+
+### Icons
+
+{{% usa-tag %}}Component Definition{{% /usa-tag %}} [Icons](https://designsystem.digital.gov/components/icons/)
+
+A [subset](https://github.com/usnistgov/hugo-uswds/tree/master/static/img) of [Font Awesome](https://fontawesome.com/) icons are included in USWDS and can be accessed as static images using `/img/{icon-filename}`. If you need additional icons, use [Font Awesome](https://fontawesome.com/) in your project.
+
+### Search
+
+{{% usa-tag %}}Component Definition{{% /usa-tag %}} [Search](https://designsystem.digital.gov/components/search/)
+
+The search component is supported in the [Basic](#basic-header) and [Extended](#extended-header) Headers provided by the default [templates](../hugo/templates/). The default search used by these headers is provided by the `layouts/partials/header-search.html` [template](https://github.com/usnistgov/hugo-uswds/blob/master/layouts/partials/components/header-search.html). This template can by [overriden](../hugo/templates/#the-header-search-html-template) to provide a custom search.
+
+### Side Navigation
+
+{{% usa-tag %}}Component Definition{{% /usa-tag %}}  [Side Navigation](https://designsystem.digital.gov/components/sidenav/)
+
+The generation of side navigation can be customized using [site](../hugo/configuration-parameters/#site-wide-configuration) and [page](../hugo/configuration-parameters/#page-specific-configuration) parameters.
+
+The [list](../hugo/templates/#list-template) and [page](../hugo/templates/#page-template) templates support auto generation of side navigation.
+
+A few enhancements have also been made over the side navigation provided by USWDS. This theme uses [Tocbot](https://tscanlin.github.io/tocbot/) to automatically generate a table of contents for each page in the side navigation. The entries in the table of contents are based on the headings within the page. The behavior of the table of contents can be customized by the [page parameters](../hugo/configuration-parameters/#page-specific-configuration): `sidenav.toc.enabled`, `sidenav.toc.headingselectors`, `sidenav.toc.includeHtml`, and `sidenav.toc.collapseDepth`.
+
+### Table
+
+{{% usa-tag %}}Component Definition{{% /usa-tag %}}  [Table](https://designsystem.digital.gov/components/table/)
+
+A partial implementation of the USWDS Bordered Table component is provided when using tables in Markdown.
+
+Borderless Tables are not currently supported.
+
+### Tag
+
+{{% usa-tag %}}Component Definition{{% /usa-tag %}} [Tag](https://designsystem.digital.gov/components/tag/)
+
+The USWDS Tag component is supported by the [usa-tag](../hugo/shortcodes/#usa-tag-shortcode) shortcode.
+
+### Typography
+
+{{% usa-tag %}}Component Definition{{% /usa-tag %}} [Typography](https://designsystem.digital.gov/components/typography/)
+
+Some aspects of the USWDS Typography are currently supported, as follows.
+
+#### Prose Formatting
+
+Some features of USWDS [prose](https://designsystem.digital.gov/components/typography/#prose) is supported by this theme.
+
+The `usa-intro` shortcode can be used for intro text.
+
+Inline HTML can be included in markdown to make use of `p` and `span` tags with typography classes.
+
+#### USWDS Theme Settings
+
+This theme uses the following USWDS theme settings to provide default styles for Markdown text.
+
+```scss
+$theme-global-paragraph-styles: true;
+$theme-global-link-styles:      true;
+$theme-global-content-styles:   true;
+```
+
+The setting `$theme-global-paragraph-styles` provides default styling for Markdown paragraphs.
+
+The setting `$theme-global-link-styles` provides default styling for Markdown links.
+
+The setting `$theme-global-content-styles` provides default styling for paragraph text, links, headings, lists, and tables.
+
+## Unsupported Components
+
+The following USWDS components are not currently supported by this theme:
+
+- [Accordion](https://designsystem.digital.gov/components/accordion/)
+- [Button](https://designsystem.digital.gov/components/button/)
+- [Footer](https://designsystem.digital.gov/components/footer/)
+- [Form Controls](https://designsystem.digital.gov/components/form-controls/)
+- [Form Templates](https://designsystem.digital.gov/components/form-templates/)
+
+It is possible to use these USWDS components as inline HTML inside Markdown pages.

docs/content/documentation/hugo/_index.md

@@ -0,0 +1,7 @@
+---
+title: "Using the USWDS Theme"
+sidenav:
+  title: Theme Use
+---
+
+TBD

docs/content/documentation/hugo/configuration-parameters.md

@@ -0,0 +1,122 @@
+---
+title: "Hugo Configuration"
+weight: 10
+---
+
+## Site-Wide Configuration
+
+Hugo provides a variety of [configuration options](https://gohugo.io/getting-started/configuration/). For simplicity, this documentation and associated examples assume a YAML-based, single file configuration is used for a site using this theme. In this case all Hugo site-wide configurations are made in the `config.yaml` located at the root of the website dirctory. Other options are available for configuring Hugo using alternate config file formats and directory structures, which are not covered on this page.
+
+The following subsections describe the configurations that are relevant to this theme.
+
+### Primary and Secondary Navigation
+
+This theme uses two different menus: primary and secondary.
+
+The primary and secondary menus are used by the Extended Header [template](../templates/#the-header-extended-html-template), while only the primary menu is used by the Basic Header [template](../templates/#the-header-basic-html-template).
+
+Hugo supports [configuring navigation](https://gohugo.io/content-management/menus/) in both the site configuration and in the [front matter](#primary-and-secondary-navigation-1) of an indvidual page. Typically, menu items that do not pertain to page resources are configured in the site configuration file, while menu entries for a page resource is configured in that page. The latter allows the menu entry to follow the page.
+
+The following is an example of defining a portion of a menu in the site configuration.
+
+```yaml
+menu:
+  primary:
+  - name: "NIST website"
+    url: "https://www.nist.gov/"
+    weight: 10
+  secondary:
+  - name: "Website Github"
+    url: "https://github.com/usnistgov/hugo-uswds-docs"
+    weight: 90
+  - name: "Theme Github"
+    url: "https://github.com/usnistgov/hugo-uswds"
+    weight: 90
+```
+
+Each menu takes a list of menu entries consisting of `name` and `url` properties.
+
+The *optional* `weight` property establishes the order in which the menu entry will be displayed within the navigation. All entries without a weight will be displayed after those with a weight.
+
+### Side Navigation
+
+The following site configurations can be used to customize the side navigation behavior in the `config.yaml` file:
+
+- `sidenav.includeTopLevel`: If `true`, a sidenav entry will be created at the top of the nav for the corresponding top-level section. If `false`, the entry for the top-level section will be suppressed.
+
+{{<highlight yaml>}}
+params:
+  sidenav:
+    includeTopLevel: true
+{{</highlight >}}
+
+### Other Parameters
+
+The following additional site-wide configurations can be used in the `config.yaml` file:
+
+- `contentrepopath` (**optional**): If provided, a link will be provided relative to this path that allows a viewer to propose a change to the page.
+
+- `suppresstopiclists` (**optional**, **default:** false)
+
+- `custom_css` (**optional**):
+
+- `custom_js` (**optional**):
+
+## Page-Specific Configuration
+
+### Primary and Secondary Navigation
+
+### Side Navigation
+
+The following page-specific configurations can be used to customize how information for a given page appears in the side navigation:
+
+- `sidenav.title`(**optional**): By default, the label used for a page in the side navigation is the Page's title. This page parameter can be used to provide an alternate title for use in the side navigation. This can be used to provide a shorter title when desired.
+
+{{<highlight yaml>}}
+sidenav:
+  title: "Sidenav Page Title"
+{{</highlight >}}
+
+- `sidenav.toc.enabled`(**optional**, **default:** true): If `true` or not specified, a table of contents will be generated in the side navigation based on the page headings. If `false` the table of contents is suppressed.
+
+{{<highlight yaml>}}
+sidenav:
+  toc:
+    enabled: true
+{{</highlight >}}
+
+- `sidenav.toc.headingselectors`(**optional**, **default:** h2, h3, h4): This parameter can be set to a comma seperated list of CSS selectors that indicate which page headers should be included in the table of contents.
+
+{{<highlight yaml>}}
+sidenav:
+  toc:
+    headingselectors: "h2,h3.sub1"
+{{</highlight >}}
+
+- `sidenav.toc.includehtml`(**optional**, **default:** false): If `true`, the HTML defined in each heading will be copied into the link used in each table of content entry. If `false` or not specified, any HTML tags will be stripped out of each content entry.
+
+{{<highlight yaml>}}
+sidenav:
+  toc:
+    includeHtml: true
+{{</highlight >}}
+
+- `sidenav.toc.collapsedepth`(**optional**, **default:** 0): A number ranging from `0` to `6` indicating how many heading levels should not be collapsed. All heading levels below this level, will be collapsed unless the browser is scrolling through these headings. The value `0`, indicates that all headings below the first available level will be collapsed.
+
+{{<highlight yaml>}}
+sidenav:
+  toc:
+    collapseDepth: 2
+{{</highlight >}}
+
+### Other Parameters
+
+The following additional site-wide configurations can be used in the front matter of each page:
+
+- `usabanner` (**optional**, **default:** false): If `true`, the USWDS "official government website" [banner](https://designsystem.digital.gov/components/header/) will be displayed at the top of the page.
+
+- `suppresstopiclist` (**optional**, **default:** false):
+
+- `custom_css` (**optional**):
+
+- `custom_js` (**optional**):