Fixing broken and stale links in model documentation. Resolves usnist…

…gov#968.

build/ci-cd/config/metaschema-docs

@@ -1,9 +1,9 @@
-# path to metaschema source|archetype|HUGO_MODEL_ID|HUGO_MODEL_NAME|HUGO_SCHEMA_ID
-src/metaschema/oscal_complete_metaschema.xml|complete-reference|complete||complete
-src/metaschema/oscal_catalog_metaschema.xml|model-reference|catalog|Catalog|catalog
-src/metaschema/oscal_profile_metaschema.xml|model-reference|profile|Profile|profile
-src/metaschema/oscal_ssp_metaschema.xml|model-reference|system-security-plan|System Security Plan|ssp
-src/metaschema/oscal_component_metaschema.xml|model-reference|component-definition|Component Definition|component-definition
-src/metaschema/oscal_assessment-plan_metaschema.xml|model-reference|assessment-plan|Assessment Plan|assessment-plan
-src/metaschema/oscal_assessment-results_metaschema.xml|model-reference|assessment-results|Assessment Results|assessment-results
-src/metaschema/oscal_poam_metaschema.xml|model-reference|plan-of-action-and-milestones|Plan of Action and Milestones|poam
+# path to metaschema source|archetype|HUGO_MODEL_ID|HUGO_MODEL_NAME|HUGO_LAYER_ID|HUGO_SCHEMA_ID
+src/metaschema/oscal_complete_metaschema.xml|complete-reference|complete|||complete
+src/metaschema/oscal_catalog_metaschema.xml|model-reference|catalog|Catalog|control|catalog
+src/metaschema/oscal_profile_metaschema.xml|model-reference|profile|Profile|control|profile
+src/metaschema/oscal_ssp_metaschema.xml|model-reference|system-security-plan|System Security Plan|implementation|ssp
+src/metaschema/oscal_component_metaschema.xml|model-reference|component-definition|Component Definition|implementation|component-definition
+src/metaschema/oscal_assessment-plan_metaschema.xml|model-reference|assessment-plan|Assessment Plan|assessment|assessment-plan
+src/metaschema/oscal_assessment-results_metaschema.xml|model-reference|assessment-results|Assessment Results|assessment|assessment-results
+src/metaschema/oscal_poam_metaschema.xml|model-reference|plan-of-action-and-milestones|Plan of Action and Milestones|assessment|poam

build/ci-cd/generate-model-documentation.sh

@@ -184,7 +184,7 @@ if [ ! -d "${doc_path}" ] || [ "$DISABLE_ARCHETYPE_CREATION" = "false" ]; then
 fi
 
 exitcode=0
-while IFS="|" read metaschema_path archetype model_id model_name schema_id || [[ -n "$metaschema_path" ]]; do
+while IFS="|" read metaschema_path archetype model_id model_name layer_id schema_id || [[ -n "$metaschema_path" ]]; do
   [[ "$metaschema_path" =~ ^[[:space:]]*# ]] && continue
   # remove leading space
   metaschema_path="${metaschema_path##+([[:space:]])}"
@@ -194,9 +194,14 @@ while IFS="|" read metaschema_path archetype model_id model_name schema_id || [[
   archetype="${archetype##+([[:space:]])}"
   model_id="${model_id##+([[:space:]])}"
   model_name="${model_name##+([[:space:]])}"
+  layer_id="${layer_id##+([[:space:]])}"
   schema_id="${schema_id##+([[:space:]])}"
 
   metaschema="$OSCAL_DIR"/"$metaschema_path"
+
+  # echo "metaschema: ${metaschema}"
+  [ ! -f "$metaschema" ] && continue;
+
   metaschema_relative=$(realpath --relative-to="$WORKING_DIR" "$metaschema")
 
   filename=$(basename -- "$metaschema")
@@ -213,14 +218,15 @@ while IFS="|" read metaschema_path archetype model_id model_name schema_id || [[
   #echo "model_id='${model_id}'"
   #echo "model_name='${model_name}'"
   #echo "schema_id='${schema_id}'"
+  #echo "layer_id='${layer_id}'"
   #echo "model_path='${model_path}'"
 
   # generate reference documentation
   if [ "$DISABLE_ARCHETYPE_CREATION" = "false" ] || [ ! -d "${model_path}" ]; then
     # build the version folder
     #if [ -d "${model_path}" ] && rm -rf "${doc_path}"
 
-    result=$(cd ${DOCS_DIR};HUGO_REF_TYPE="${TYPE}" HUGO_REF_BRANCH="${BRANCH}" HUGO_REF_VERSION="${VERSION}" HUGO_REF_REVISION="${REVISION}" HUGO_MODEL_NAME="${model_name}" HUGO_MODEL_ID="${model_id}" HUGO_SCHEMA_ID="${schema_id}" hugo new --kind ${archetype} "${model_path}" 2>&1)
+    result=$(cd ${DOCS_DIR};HUGO_REF_TYPE="${TYPE}" HUGO_REF_BRANCH="${BRANCH}" HUGO_REF_VERSION="${VERSION}" HUGO_REF_REVISION="${REVISION}" HUGO_MODEL_NAME="${model_name}" HUGO_MODEL_ID="${model_id}" HUGO_SCHEMA_ID="${schema_id}" HUGO_MODEL_CONCEPTS_URL="/concepts/layer/${layer_id}/${schema_id}/" hugo new --kind ${archetype} "${model_path}" 2>&1)
     cmd_exitcode=$?
     if [ $cmd_exitcode -ne 0 ]; then
       echo -e "${P_ERROR}Generating '${P_END}${model_id}${P_OK}' model page failed for revision '${P_END}${REVISION}${P_ERROR}' on branch '${P_END}${BRANCH}${P_ERROR}'.${P_END}"
@@ -266,6 +272,6 @@ while IFS="|" read metaschema_path archetype model_id model_name schema_id || [[
 
   echo -e "${P_OK}Generated docs for '${P_END}${metaschema_relative}${P_OK}' in '${P_END}${model_path}${P_OK}'.${P_END}"
 
-done <"$OSCAL_DIR/build/ci-cd/config/metaschema-docs"
+done <"${WORKING_DIR}/build/ci-cd/config/metaschema-docs"
 
 exit $exitcode

docs/archetypes/complete-reference/_index.md

@@ -15,7 +15,7 @@ sidenav:
 
 This reference combines the information items used in all the OSCAL models into a single, comprehensive view. The following reference documentation is available.
 
-- **[Conceptual Overview]({{ getenv "HUGO_MODEL_CONCEPTS_URL" }}):** Provides a high-level overview of the intended purpose and role of each model in the [OSCAL architecture](/concepts/layer/). Describes each model's purpose, target audience, and key concepts.
+- **[Conceptual Overview](/concepts/layer/):** Provides a high-level overview of the intended purpose and role of each model in the [OSCAL architecture](/concepts/layer/). Describes each model's purpose, target audience, and key concepts.
 - **Outline ([JSON/YAML](json-outline/), [XML](xml-outline/)):** Provides a brief listing of the information items for all OSCAL models organized hierarchically. Useful for understanding the structure and basic syntax of all the OSCAL models in a given format.
 - **Reference ([JSON/YAML](json-reference/), [XML](xml-reference/)):** Provides a detailed description of the structure and syntax for the information items for all OSCAL models organized hierarchically. Useful for understanding how to use information items within all the OSCAL models in the given format.
 - **Index ([JSON/YAML](json-index/), [XML](xml-index/)):** Provides a listing of the information items for all OSCAL models organized by where they are used.

docs/archetypes/model-reference/json-definitions.md

@@ -10,6 +10,6 @@ toc:
   headingselectors: "h1.toc1, h2.toc2, h3.toc3, h4.toc4, h5.toc5, h6.toc6"
 ---
 
-The following is a reference for the JSON object definitions derived from this model's [metaschema](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}//src/metaschema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_metaschema.xml).
+The following is a reference for the JSON object definitions derived from the [metaschema](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}//src/metaschema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_metaschema.xml) for this [model]({{ getenv "HUGO_MODEL_CONCEPTS_URL" }}).
 
 <!-- DO NOT REMOVE. Generated text below -->

docs/archetypes/model-reference/json-index.md

@@ -10,6 +10,6 @@ toc:
   headingselectors: "h1.toc1"
 ---
 
-The following is an index of each JSON property used in the [JSON format](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/json/schema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.json) for this model. Each entry in the index lists all uses of the given property in the format, which is linked to the corresponding entry in the [JSON Format Reference](../json-reference/). Each entry also lists the formal name for the definition which is linked to the corresponding JSON definition in the [JSON Format Metaschema Reference](../json-definitions/).
+The following is an index of each JSON property used in the [JSON format](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/json/schema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.json) for this [model]({{ getenv "HUGO_MODEL_CONCEPTS_URL" }}). Each entry in the index lists all uses of the given property in the format, which is linked to the corresponding entry in the [JSON Format Reference](../json-reference/). Each entry also lists the formal name for the definition which is linked to the corresponding JSON definition in the [JSON Format Metaschema Reference](../json-definitions/).
 
 <!-- DO NOT REMOVE. Generated text below -->

docs/archetypes/model-reference/json-outline.md

@@ -44,6 +44,6 @@ aliases:
 {{- end }}
 ---
 
-The following outline is a representation of the [JSON format](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/json/schema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.json) for this model. For each property, the name links to the corresponding entry in the [JSON Format Reference](../json-reference/). The cardinality and data type are also provided for each property where appropriate.
+The following outline is a representation of the [JSON format](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/json/schema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.json) for this [model]({{ getenv "HUGO_MODEL_CONCEPTS_URL" }}). For each property, the name links to the corresponding entry in the [JSON Format Reference](../json-reference/). The cardinality and data type are also provided for each property where appropriate.
 
 <!-- DO NOT REMOVE. Generated text below -->

docs/archetypes/model-reference/json-reference.md

@@ -45,6 +45,6 @@ aliases:
 {{- end }}
 ---
 
-The following is the JSON format reference for this model, which is organized hierarchically. Each entry represents the corresponding JSON property in the model's JSON format, and provides details about the semantics and use of the property. The [JSON Format Outline](../json-outline/) provides a streamlined, hierarchical representation of this model's JSON format which can be used along with this reference to better understand the JSON representation of this model.
+The following is the JSON format reference for this [model]({{ getenv "HUGO_MODEL_CONCEPTS_URL" }}), which is organized hierarchically. Each entry represents the corresponding JSON property in the model's JSON format, and provides details about the semantics and use of the property. The [JSON Format Outline](../json-outline/) provides a streamlined, hierarchical representation of this model's JSON format which can be used along with this reference to better understand the JSON representation of this model.
 
 <!-- DO NOT REMOVE. Generated text below -->

docs/archetypes/model-reference/xml-definitions.md

@@ -10,6 +10,6 @@ toc:
   headingselectors: "h1.toc1, h2.toc2, h3.toc3, h4.toc4, h5.toc5, h6.toc6"
 ---
 
-The following is a reference for the XML element and attribute types derived from this model's [metaschema](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}//src/metaschema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_metaschema.xml).
+The following is a reference for the XML element and attribute types derived from the [metaschema](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}//src/metaschema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_metaschema.xml) for this [model]({{ getenv "HUGO_MODEL_CONCEPTS_URL" }}).
 
 <!-- DO NOT REMOVE. Generated text below -->

docs/archetypes/model-reference/xml-index.md

@@ -10,6 +10,6 @@ toc:
   headingselectors: "h1.toc1"
 ---
 
-The following is an index of each XML element and attribute used in the [XML format](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/xml/schema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.xsd) for this model. Each entry in the index lists all uses of the given element or attribute in the format, which is linked to the corresponding entry in the [XML Format Reference](../xml-reference/). Each entry also lists the formal name for the given element or attribute which is linked to the corresponding XML type in the [XML Format Metaschema Reference](../xml-definitions/).
+The following is an index of each XML element and attribute used in the [XML format](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/xml/schema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.xsd) for this [model]({{ getenv "HUGO_MODEL_CONCEPTS_URL" }}). Each entry in the index lists all uses of the given element or attribute in the format, which is linked to the corresponding entry in the [XML Format Reference](../xml-reference/). Each entry also lists the formal name for the given element or attribute which is linked to the corresponding XML type in the [XML Format Metaschema Reference](../xml-definitions/).
 
 <!-- DO NOT REMOVE. Generated text below -->

docs/archetypes/model-reference/xml-outline.md

@@ -44,6 +44,6 @@ aliases:
 {{- end }}
 ---
 
-The following outline is a representation of the [XML format](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/xml/schema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.xsd) for this model. For each element or attribute, the name links to the corresponding entry in the [XML Format Reference](../xml-reference/). The cardinality and data type are also provided for each element or attribute where appropriate.
+The following outline is a representation of the [XML format](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/xml/schema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.xsd) for this [model]({{ getenv "HUGO_MODEL_CONCEPTS_URL" }}). For each element or attribute, the name links to the corresponding entry in the [XML Format Reference](../xml-reference/). The cardinality and data type are also provided for each element or attribute where appropriate.
 
 <!-- DO NOT REMOVE. Generated text below -->

docs/archetypes/model-reference/xml-reference.md

@@ -45,6 +45,6 @@ aliases:
 {{- end }}
 ---
 
-The following is the XML format reference for this model, which is organized hierarchically. Each entry represents the corresponding XML element or attribute in the model's XML format, and provides details about the semantics and use of the element or attribute. The [XML Format Outline](../xml-outline/) provides a streamlined, hierarchical representation of this model's XML format which can be used along with this reference to better understand the XML representation of this model.
+The following is the XML format reference for this [model]({{ getenv "HUGO_MODEL_CONCEPTS_URL" }}), which is organized hierarchically. Each entry represents the corresponding XML element or attribute in the model's XML format, and provides details about the semantics and use of the element or attribute. The [XML Format Outline](../xml-outline/) provides a streamlined, hierarchical representation of this model's XML format which can be used along with this reference to better understand the XML representation of this model.
 
 <!-- DO NOT REMOVE. Generated text below -->