Merge pull request #13 from usnistgov/7-oscal-reference-landing-page

usnistgov · Aug 17, 2023 · 19eadb9 · 19eadb9
2 parents 7446f58 + 140c9ad
commit 19eadb9
Show file tree

Hide file tree

Showing 10 changed files with 43 additions and 11 deletions.
diff --git a/site/archetypes/guide.md b/site/archetypes/guide.md
@@ -0,0 +1,28 @@
+# How do I use this documentation?
+
+Each specification consists of an outline, an index, and a reference, for both JSON and XML formats.
+
+## Outline Pages
+
+An outline is a navigatable, tree-based representation of OSCAL's models. For example, below is the collapsed OSCAL System Security Plan outline in JSON and XML, respectively. The name links to the corresponding entry in the XML or JSON formats.
+
+By clicking on the black triangle in front of an entry, it expands to show child entries.
+
+![](/img/outline-ssp-json.png)
+![](/img/outline-ssp-xml.png)
+
+In an outline, the cardinality, the minimum and maximum number of instances required, follows the entry as a number in square brackets. The data type follows the cardinality (see the cardinality <code>[1]</code> in the image below).
+
+## Reference Pages
+
+In an outline, each entry links to its corresponding reference providing a definition for an entry and its constraints.
+
+![](/img/reference-ssp-json.png)
+
+## Index Pages
+
+An index for each OSCAL model lists all entries in alphabetical order.
+
+Each entry in the index lists a specific location in the applicable model, in both JSON and XML formats.
+
+![](/img/index-ssp-props-json.png)
diff --git a/site/content/_index.md b/site/content/_index.md
diff --git a/site/content/models/_index.md b/site/content/models/_index.md
@@ -1,9 +1,9 @@
 ---
-title: Model Reference
+title: Model Documentation
 layout: reference-index
 menu:
   primary:
-    name: Model Reference
+    name: Model Documentation
     weight: 35
 toc:
   enabled: true

diff --git a/site/layouts/_default/index.html b/site/layouts/_default/index.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en-us">
+
+<head>
+    <title>Redirect</title>
+    <link rel="canonical" href="models/">
+    <meta name="robots" content="noindex">
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=models/">
+</head>
+
+</html>
diff --git a/site/layouts/_default/reference-index.html b/site/layouts/_default/reference-index.html
@@ -49,6 +49,7 @@
             {{ end }}
           {{ end }}
           </ul>
+          {{ readFile "archetypes/guide.md" | markdownify }}
           {{ end }}
         </article>
       </div>

diff --git a/site/static/img/index-ssp-props-json.png b/site/static/img/index-ssp-props-json.png
diff --git a/site/static/img/outline-ssp-json-expand.png b/site/static/img/outline-ssp-json-expand.png
diff --git a/site/static/img/outline-ssp-json.png b/site/static/img/outline-ssp-json.png
diff --git a/site/static/img/outline-ssp-xml.png b/site/static/img/outline-ssp-xml.png
diff --git a/site/static/img/reference-ssp-json.png b/site/static/img/reference-ssp-json.png