Introduce "Visualizations" page as an intermediate destination

Makefile

@@ -159,8 +159,6 @@ $(DOCDIR):
 #
 # Then, use `refgraph` (part of `refscan`) to generate a pair of graphs (i.e. network diagrams),
 # one that depicts inter-collection relationships and one that depicts inter-class relationships.
-# We generate them (i.e. their HTML files) at paths referenced in the `nav` section of `mkdocs.yml`.
-# As a result, a pair of navigation links in the sidebar of the document website will lead to them.
 #
 gendoc: $(DOCDIR)
 	# added copying of images and renaming of TEMP.md
@@ -171,8 +169,9 @@ gendoc: $(DOCDIR)
 	$(RUN) cp $(SRC)/scripts/*.js $(DOCDIR)/javascripts/
 	# Use `refgraph` (part of `refscan`) to generate interactive diagrams within the compiled documentation file tree.
 	# One diagram depicts the relationships between collections and the other depicts the relationships between classes.
-	$(RUN) refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph $(DOCDIR)/collection-graph.html
-	$(RUN) refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph $(DOCDIR)/class-graph.html
+	mkdir -p $(DOCDIR)/visualizations
+	$(RUN) refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph $(DOCDIR)/visualizations/collection-graph.html
+	$(RUN) refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph $(DOCDIR)/visualizations/class-graph.html
 
 testdoc: gendoc serve
 

mkdocs.yml

@@ -31,8 +31,7 @@ nav:
   - NMDC Schema Contributors How-to from Schema Hackathon 2023-12-10: https://docs.google.com/presentation/d/1ZH41QAoESUwAkdHyUxlrmSKS5M-bT0TOulBgX4rBx2A/edit#slide=id.g26390794265_0_693
   - NMDC Schema Validation: schema-validation.md
   - Schema element deprecation guide: schema_element_deprecation_guide.md
-  - Inter-class relationships (diagram): class-graph.html
-  - Inter-collection relationships (diagram): collection-graph.html
+  - Visualizations: visualizations.md
 
 
 site_url: https://microbiomedata.github.io/nmdc-schema

src/docs/visualizations.md

@@ -0,0 +1,25 @@
+# Visualizations
+
+## Inter-collection relationship diagram
+
+<!-- Note: `visualizations/collection-graph.html` does not exist in the source code repository.
+           It gets generated as part of the documentation build process. -->
+This [**inter-collection relationship diagram**](visualizations/collection-graph.html)
+shows the database **collections** described by the schema, and the **relationships** between those collections.
+
+Each circle represents a collection.
+Each arrow represents all of the fields that documents in one collection—the one at that arrow's tail—can
+use to refer to documents in another collection—the one at that arrow's head.
+If you click on a circle, the names of the fields will appear on the arrows connected to that circle.
+
+## Inter-class relationship diagram
+
+<!-- Note: `visualizations/class-graph.html` does not exist in the source code repository.
+           It gets generated as part of the documentation build process. -->
+This [**inter-class relationship diagram**](visualizations/class-graph.html)
+shows the **classes** defined within the schema, and the **relationships** between those classes.
+
+Each circle represents a class.
+Each arrow represents all of the slots that instances of that class—the one at that arrow's tail—can
+use to refer to instances of another class—the one at that arrow's head.
+If you click on a circle, the names of the slots will appear on the arrows connected to that circle.