In OSCAL docs production, we want to produce a nested table of contents through Hugo targeting particular elements in the HTML.

This can be done, as documented, in the YAML header (as in an example of xml-schema.md):

sidenav:
  title: XML Format Reference
  toc:
    headingselectors: "h2.toc1, span.toc2"

But the ToC produced in this case is not nested. The toc2 targets are listed next to the toc1 targets, not "inside" them.

It appears to work if the value is given as h2.toc1, h3.toc2, and the page has h3 instead of span.

However we don't want the entire line to be listed in the ToC (as a "header"), only the segment inside the line. span seems appropriate here to use for extraction of content into the ToC.

Any workarounds here? The problem with using the h3 is that in USWDS, h3 (any h*) implies all kinds of formatting logic for its siblings, and here the siblings are in line ... leading to side effects in the display requiring a lot of CSS to override. It would be nice it we could simply list the contents of the span.

I have been using this theme like for Metaschema and OSCAL work, particularly in relation to usnistgov/metaschema#260, and I am encountering an issue as of commit aj-stein-nist/metaschema@3345161 were locally running the code with hugo leads to browser errors caught in the debugger.

I have the Mermaid diagram below. This renders correctly in mermaid.live, but not even in GitHub's inline issue editor or in the current version of this repo's hugo-uswds theme.

erDiagram
  "metaschema definition" }|..|{ "instance" : "must specify model of"
  "metaschema tool" }|..|{ "metaschema definition" : "must parse"
  "metaschema tool" }|..|{ "instance" : "can parse"
  "metaschema tool" }|..|{ "schema" : "can generate"
  "schema" }|..|{ "instance" : "must validate"

I get the following error from the Mermaid library locally when running hugo and the same in this GitHub issue.

Unable to render rich display

Parse error on line 2:
erDiagram "metaschema definiti...
-----------^
Expecting 'EOF', 'SPACE', 'NEWLINE', 'title', 'acc_title', 'acc_descr', 'acc_descr_multiline_value', 'ALPHANUM', 'open_directive', got 'WORD'

Interestingly, when I add a space between the first and second lines, it does work, but only when using an updated version of the Mermaid library (version 9.3.0, the latest stable, updating its tag and SRI from the Cloudflare CDN used for the 8.x version currently). So with 9.3.0 this works:

erDiagram

  "metaschema definition" }|..|{ "instance" : "must specify model of"
  "metaschema tool" }|..|{ "metaschema definition" : "must parse"
  "metaschema tool" }|..|{ "instance" : "can parse"
  "metaschema tool" }|..|{ "schema" : "can generate"
  "schema" }|..|{ "instance" : "must validate"

(NOTE: this will work with the hugo theme in local testing, GH will still show an error in this WSYWIG editor.)

I want to file a bug to workaround this issue and also sensibly update Mermaid to support new diagram types and fix bugs in existing functionality such as entity relationship diagrams, as I am reporting here.

Image provided below as example. There is a lot of space left on the right side of the page, but the navigation section appears to have a strict width enforced. This particular widget appears to be hidden/culled on smaller screen representations making the reasoning for such a strict width unclear.

Can the width be adjustable or more flexible based on content?

As a reader of a website, in order for faster, more approachable reading of long-form content, I would like code blocks to be foldable, to collapse and expand as needed as part of long-form text.

Hat tip to @brianruf, who asked for this feature in the context of Metaschema in usnistgov/metaschema#277, but we need to implement the change in the hugo theme and templates here first.

Currently the USWDS javascript dependencies are vendored without any metadata about what version of USWDS the project relies upon.

I'd like to propose either:

1. Continue vendoring (committing assets to the main branch) the UWDS dependencies, but define the versions in a package.json and include a script to copy the relevant assets out of the node_modules/ folder

   • This approach is easier to use, and allows consumers using the submodule method to still point at the master branch.
   • Actions will probably be required to prevent the vendored dependency from getting out of sync with the package.json

2. Make the process of building the website for consumption as a theme explicit. Commits to the main branch do not contain USWDS code, and users of the submodule point at a "built" branch.

   • This approach is "cleaner" as it does not include separate JS code in the main branches, which may lead to better scaling if more dependencies are added.
   • Actions will be required to "build" the module, committing to a separate branch.
   • For local development, a makefile (or insert your own helper here) will be required to copy the dependencies before building the docs site.

Both of these approaches would allow for us to easily upgrade version of USWDS as well as any future dependencies we may want to include in the future.

This would also allow for integration with dependabot.

Per discussion from @david-waltermire-nist, we need to research how to use {{ define ... }} blocks for our layouts and override (maybe extend) to follow the updated guidance from NIST's web admins about the proper use of the USG Digital Analytics Platform and the proper, current UA code for GA in the context of DAP.

As a developer using the hugo-uswds theme as a module for an internal website at nist (on ipages.nist.gov, not pages.nist.gov, not accessible on public, routable Internet), I cannot use the search component with search.gov as the website is not indexable, so I would like the ability to deploy a Hugo website with this module and configure a non-default value to disable it so it's not visible.

As discovered with @david-waltermire-nist when troubleshooting usnistgov/metaschema-xslt#19 for usnistgov/metaschema#200, we determined that {{ .Permalink }} targets for href are always absolute even when we need them to be relative. Example of issue in this GitHub Actions run while working on usnistgov/metaschema-xslt#19.