From 8174a284f25bab8f89b1c88cdb3c0388eb039cd6 Mon Sep 17 00:00:00 2001
From: Peter Powers <pmpowers@usgs.gov>
Date: Thu, 5 Jan 2023 19:54:54 -0700
Subject: [PATCH 1/5] typos; web service build edits

---
 docs/pages/About-the-NSHMP.md    |  2 +-
 docs/pages/Building-&-Running.md | 35 ++++++++++++++++++++++++++++----
 docs/pages/Developer-Basics.md   |  9 --------
 package-lock.json                |  1 -
 4 files changed, 32 insertions(+), 15 deletions(-)

diff --git a/docs/pages/About-the-NSHMP.md b/docs/pages/About-the-NSHMP.md
index 54d1297ad..042f137bb 100644
--- a/docs/pages/About-the-NSHMP.md
+++ b/docs/pages/About-the-NSHMP.md
@@ -18,7 +18,7 @@ considered in other industries such as real estate lending. A 9-member steering
 academic and industry experts provides technical oversight and recommendations to the NSHMP.
 
 An NSHM defines the set of likely earthquake sources and their rates in a particular region. Given
-parameters of the earhtquake source and a site of interest, ground motion models (GMMs) are used
+parameters of the earthquake source and a site of interest, ground motion models (GMMs) are used
 to estimate ground shaking from the set of earthquakes. The NSHMP routinely updates NSHMs for the
 U.S. and its territories to consider the best available science.
 
diff --git a/docs/pages/Building-&-Running.md b/docs/pages/Building-&-Running.md
index 8464fb14d..c349b5860 100644
--- a/docs/pages/Building-&-Running.md
+++ b/docs/pages/Building-&-Running.md
@@ -21,8 +21,8 @@ Building and running *nshmp-haz* requires prior installation of Git and Java. Pl
 
 ### Building
 
-Navigate to a location on your system where you want *nshmp-haz* code to reside, clone the
-repository, and compile:
+_nshmp-haz_ uses the [Gradle](https://gradle.org/) build tool. Navigate to a location on your
+system where you want *nshmp-haz* code to reside, clone the repository, and compile:
 
 ```bash
 cd /path/to/project/directory
@@ -36,7 +36,34 @@ This creates a single file, `build/libs/nshmp-haz.jar` that may be used for haza
 users using the native command prompt). This executes any tasks (e.g. `assemble`) after
 downloading all required dependencies, including Gradle itself.
 
-### Computing Hazard
+### Running
+
+_nshmp-haz_ applications may be run from the command line or as a local web service. Command line
+applications are recommended for long running hazard and disaggregation calculations, but most
+users will find a web service endpoint to be more flexible. Web services return
+[JSON](https://www.json.org/json-en.html) responses that can be parsed by most programming
+languages and data analaysis and visualization programs (e.g. Matlab).
+
+### Web Servies
+
+To run _nshmp-haz_ as a web service:
+
+```bash
+./gradlew run
+```
+
+Services (and documentation) are then avialable on <http://localhost:8080/>
+
+ALternatively, run:
+code, run:
+
+```bash
+./gradlew run -t
+```
+
+to have the services automatically recompile when the source code changes.
+
+### Command Line Hazard Calculation
 
 The `HazardCalc` program computes hazard curves at one or more sites for a variety of intensity
 measures. For example:
@@ -56,7 +83,7 @@ be supplied as a third argument. It can be used to override any calculation sett
 See the [examples](../../etc/examples) directory for more details (or
 [on GitLab](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/main/etc/examples))
 
-### Computing Disaggregations
+### Command Line Disaggregation Calculation
 
 Like `HazardCalc`, the `DisaggCalc` program performs disaggregations at one or more sites for a
 variety of intensity measures. The return period for the disaggregation is defined in the config,
diff --git a/docs/pages/Developer-Basics.md b/docs/pages/Developer-Basics.md
index 17da9de70..799479e25 100644
--- a/docs/pages/Developer-Basics.md
+++ b/docs/pages/Developer-Basics.md
@@ -50,15 +50,6 @@ cd /directory/for/code
 git clone https://code.usgs.gov/ghsc/nshmp/nshmp-haz.git
 ```
 
-## Eclipse Integration (Optional)
-
-Eclipse provides automatic compilation, syntax highlighting, and integration with Git, among
-other useful features. To build or modify *nshmp-haz* using [Eclipse](http://www.eclipse.org/),
-install the [Eclipse IDE for Java Developers](https://www.eclipse.org/downloads/packages/) or
-[Eclipse IDE for Enterprise Java and Web Developers](https://www.eclipse.org/downloads/packages/),
-if you plan on developing web services. Import the project into Eclipse: `File > Import >
-Gradle > Existing Gradle Project`
-
 ---
 
 ## Related Pages
diff --git a/package-lock.json b/package-lock.json
index dc72624ba..fd03b78e3 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -5,7 +5,6 @@
   "requires": true,
   "packages": {
     "": {
-      "name": "nshmp-haz",
       "version": "2.0.0",
       "devDependencies": {
         "markdownlint-cli": "^0.31.1",
-- 
GitLab


From 01e8b5fcfaeb17327bd152211ff7f4caf6ed8d90 Mon Sep 17 00:00:00 2001
From: Peter Powers <pmpowers@usgs.gov>
Date: Mon, 16 Jan 2023 19:34:22 -0700
Subject: [PATCH 2/5] updated build and run docs; separate docker page

---
 docs/README.md                          |   6 +-
 docs/pages/Building-&-Running.md        | 207 ++----------------
 docs/pages/Calculation-Configuration.md |   4 +-
 docs/pages/Developer-Basics.md          |   6 +-
 docs/pages/Logic-Trees-&-Uncertainty.md |   2 +-
 docs/pages/Site-Specification.md        |   4 +-
 docs/pages/Using-Docker.md              | 267 ++++++++++++++++++++++++
 etc/examples/README.md                  |   8 +-
 gradle/dependencies.gradle              |   1 -
 9 files changed, 304 insertions(+), 201 deletions(-)
 create mode 100644 docs/pages/Using-Docker.md

diff --git a/docs/README.md b/docs/README.md
index fcf5ab4e0..df638f0cc 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -3,7 +3,7 @@
 ***nshmp-haz*** is a U.S. Geological Survey ([USGS](https://www.usgs.gov)) developed software stack
 that supports probabilistic seismic hazard (PSHA) and related analyses. It is maintained by the
 National Seismic Hazard Model Project ([NSHMP](https://earthquake.usgs.gov/hazards/)) within the
-USGS's earthquake hazards program ([EHP](http://earthquake.usgs.gov)).
+USGS [Earthquake Hazards Program](http://earthquake.usgs.gov).
 
 *nshmp-haz* supports high performance seismic hazard calculations required to generate detailed
 maps over large areas and supports a variety of web services and applications related to
@@ -18,8 +18,8 @@ use *nshmp-haz* as well as underlying model implementation details.
   * [Developer Basics](./pages/Developer-Basics.md)
   * [Calculation Configuration](./pages/Calculation-Configuration.md)
   * [Site Specification](./pages/Site-Specification.md)
-  * [Examples](../../etc/examples)
-  * [Web Services](./pages/Web-Services.md)
+  * [Using Docker](./pages/Using-Docker.md)
+  * See also the [examples](../../etc/examples) directory
 * [Hazard Model](./pages/Hazard-Model.md)
   * [Model Structure](./pages/Model-Structure.md)
   * [Model Files](./pages/Model-Files.md)
diff --git a/docs/pages/Building-&-Running.md b/docs/pages/Building-&-Running.md
index c349b5860..121fa83b8 100644
--- a/docs/pages/Building-&-Running.md
+++ b/docs/pages/Building-&-Running.md
@@ -6,13 +6,8 @@
   * [Developer Basics](./Developer-Basics.md#developer-basics)
   * [Calculation Configuration](./Calculation-Configuration.md#calculation-configuration)
   * [Site Specification](./Site-Specification.md#site-specification)
-  * [Examples](../../etc/examples)
-  * [Web Services](./Web-Services.md)
-
-## Build & Run Options
-
-* [Build and run locally](#build-and-run-locally)
-* [Run with Docker](#run-with-docker)
+  * [Using Docker](./Using-Docker.md#using-docker)
+  * See also the [examples](../../etc/examples) directory
 
 ## Build and Run Locally
 
@@ -40,28 +35,29 @@ downloading all required dependencies, including Gradle itself.
 
 _nshmp-haz_ applications may be run from the command line or as a local web service. Command line
 applications are recommended for long running hazard and disaggregation calculations, but most
-users will find a web service endpoint to be more flexible. Web services return
+users will find the web service endpoints to be more flexible. Web services return
 [JSON](https://www.json.org/json-en.html) responses that can be parsed by most programming
 languages and data analaysis and visualization programs (e.g. Matlab).
 
 ### Web Servies
 
-To run _nshmp-haz_ as a web service:
+To run _nshmp-haz_ web services:
 
 ```bash
 ./gradlew run
 ```
 
-Services (and documentation) are then avialable on <http://localhost:8080/>
-
-ALternatively, run:
-code, run:
+By default, when the web services start up, they load the 2018 NSHM for the conterminous U.S.
+To use a different model run the web services using Java and specify model path:
 
 ```bash
-./gradlew run -t
+java -jar build/libs/nshmp-haz.jar --model=path/to/model
 ```
 
-to have the services automatically recompile when the source code changes.
+After startup, web services and documentation are now available at
+[http://localhost:8080/](http://localhost:8080/).
+
+See the [Matlab](../../etc/matlab) directory for examples of how to call the web services.
 
 ### Command Line Hazard Calculation
 
@@ -72,16 +68,16 @@ measures. For example:
 java -cp path/to/nshmp-haz.jar gov.usgs.earthquake.nshmp.HazardCalc model sites [config]
 ```
 
-At a minimum, the hazard source [model](./Hazard-Model.md) and the [site](./Site-Specification.md)(s)
-at which to perform calculations must be specified. The source model should specified a path to a
-directory. A single site may be specified with a string; multiple sites must be specified using
-either a comma-delimited (CSV) or [GeoJSON](http://geojson.org) file. The path to a custom
-[configuration](./Calculation-Configuration.md) file containing user-specific settings may optionally
-be supplied as a third argument. It can be used to override any calculation settings; if absent
-[default](./Calculation-Configuration.md) values are used.
+At a minimum, the hazard source [model](./Hazard-Model.md) and the 
+[site](./Site-Specification.md)(s) at which to perform calculations must be specified. The source
+model should specified a path to a directory. A single site may be specified with a string;
+multiple sites must be specified using either a comma-delimited (CSV) or
+[GeoJSON](http://geojson.org) file. The path to a custom 
+[configuration](./Calculation-Configuration.md) file containing user-specific settings may
+optionally be supplied as a third argument. It can be used to override any calculation settings;
+if absent [default](./Calculation-Configuration.md) values are used.
 
-See the [examples](../../etc/examples) directory for more details (or
-[on GitLab](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/main/etc/examples))
+See the [examples](../../etc/examples) directory for more details.
 
 ### Command Line Disaggregation Calculation
 
@@ -98,169 +94,6 @@ Disaggregations build on and output `HazardCalc` results along with other disagg
 files. Disaggregations also have some independent
 [configuration](./Calculation-Configuration.md#calculation-configuration-parameters) options.
 
-## Run with [Docker](https://docs.docker.com/install/)
-
-nshmp-haz is available as a public image from [Docker hub](https://hub.docker.com/r/usgs/nshmp-haz)
-with tags:
-
-* `latest`: Refers to the latest updates from the main or production branch
-* `development-latest`: Refers to forks of the repository.
-* `staging-latest`: Latest updates associated with the
-[main](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/main) branch
-* `production-latest`: Latest stable release associated with the
-[production](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/production) branch
-
-To ensure you have the latest *nshmp-haz* update associated with a specific tag,
-always first pull the image from Docker:
-
-```bash
-docker pull usgs/nshmp-haz:<tag>
-```
-
-> Replace `<tag>` with one of the above tags.
-
-Example:
-
-```bash
-docker pull usgs/nshmp-haz:production-latest
-```
-
-### Docker Memory on Mac
-
-By default, Docker Desktop for Mac is set to use 2 GB runtime memory. To run *nshmp-haz*, the
-memory available to Docker must be [increased](https://docs.docker.com/docker-for-mac/#advanced)
-to a minimum of 4 GB.
-
-### Run nshmp-haz in Docker
-
-The *nshmp-haz* application may be run as a Docker container which mitigates the need to install
-Git, Java, or other dependencies besides Docker. A public image is available
-from  [Docker hub](https://hub.docker.com/r/usgs/nshmp-haz)
-which can be run with:
-
-```bash
-# Pull docker image
-docker pull usgs/nshmp-haz:latest 
-
-# Run docker image
-docker run \
-    --env CLASS_NAME=<DisaggCalc | HazardCalc | RateCalc> \
-    --env IML=<NUMBER> \
-    --env RETURN_PERIOD=<NUMBER> \
-    --volume /absolute/path/to/sites/file:/app/sites.<geojson | csv> \
-    --volume /absolute/path/to/config/file:/app/config.json \
-    --volume /absolute/path/to/output:/app/output \
-    usgs/nshmp-haz
-```
-
-Where:
-
-* `CLASS_NAME` is the nshmp-haz class to run:
-  * [DisaggCalc](../../src/main/java/gov/usgs/earthquake/nshmp/DisaggCalc.java)
-  * [HazardCalc](../../src/main/java/gov/usgs/earthquake/nshmp/HazardCalc.java)
-  * [RateCalc](../../src/main/java/gov/usgs/earthquake/nshmp/RateCalc.java)
-* Other arguments (local files mapped to files within the Docker container with `:/app/...`):
-  * (required) The absolute path to a [USGS model (NSHM)](./USGS-Models.md)
-    * Example: `$(pwd)/nshm-hawaii:/app/model`
-  * (required) The absolute path to a GeoJSON or CSV [site(s)](./Site-Specification.md) file
-    * CSV example: `$(pwd)/my-csv-sites.csv:/app/sites.csv`
-    * GeoJSON example: `$(pwd)/my-geojson-sites.geojson:/app/sites.geojson`
-  * (required) The absolute path to an output directory
-    * Example: `$(pwd)/my-hazard-output:/app/output`
-  * (optional) The absolute path to a [configuration](./Calculation-Configuration.md) file
-    * Example: `$(pwd)/my-custom-config.json:/app/config.json`
-
-### Docker Examples
-
-#### [`HazardCalc`](../../src/main/java/gov/usgs/earthquake/nshmp/HazardCalc.java) Example
-
-The following example runs the `HazardCalc` program in nshmp-haz with the
-[nshm-hawaii](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git) model and the
-assumption a GeoJSON [site](./Site-Specification.md) file exists named `sites.geojson`.
-
-```bash
-# Download Hawaii NSHM
-git clone https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git
-
-# Pull image
-docker pull usgs/nshmp-haz:latest 
-
-# Run nshmp-haz HazardCalc
-docker run \
-    --env CLASS_NAME="HazardCalc" \
-    --volume "$(pwd)/nshm-hawaii:/app/model" \
-    --volume "$(pwd)/sites.geojson" \
-    --volume "$(pwd)/hawaii-hazard-output:/app/output" \
-    usgs/nshmp-haz
-```
-
-#### [`DisaggCalc`](../../src/main/java/gov/usgs/earthquake/nshmp/DisaggCalc.java) Example
-
-The following example runs the `DisaggCalc` program in nshmp-haz with the
-[nshm-hawaii](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git) model and the
-assumption a GeoJSON [site](./Site-Specification.md) file exists named `sites.geojson`.
-
-```bash
-# Download Hawaii NSHM
-git clone https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git
-
-# Pull image
-docker pull usgs/nshmp-haz:latest 
-
-# Run nshmp-haz DisaggCalc
-docker run \
-    --env CLASS_NAME="DisaggCalc" \
-    --env RETURN_PERIOD=475 \
-    --volume "$(pwd)/nshm-hawaii:/app/model" \
-    --volume "$(pwd)/sites.geojson" \
-    --volume "$(pwd)/hawaii-disagg-output:/app/output" \
-    usgs/nshmp-haz:latest
-```
-
-#### [`RateCalc`](../../src/main/java/gov/usgs/earthquake/nshmp/RateCalc.java) Example
-
-The following example runs the `RateCalc` program in nshmp-haz with the
-[nshm-hawaii](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git) model and the
-assumption a GeoJSON [site](./Site-Specification.md) file exists named `sites.geojson`.
-
-```bash
-# Download Hawaii NSHM
-git clone https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git
-
-# Pull image
-docker pull usgs/nshmp-haz:latest 
-
-# Run nshmp-haz RateCalc
-docker run \
-    --env CLASS_NAME="RateCalc" \
-    --volume "$(pwd)/nshm-hawaii:/app/model" \
-    --volume "$(pwd)/sites.geojson" \
-    --volume "$(pwd)/hawaii-rate-output:/app/output" \
-    usgs/nshmp-haz
-```
-
-### Run Customization
-
-When running *nshmp-haz* with Docker the maximum JVM memory size can
-be set with the environment flag (-e, -env):
-
-```bash
-docker run \
-    --env JAVA_MEMORY=<MEMORY> \
-    ...
-    usgs/nshmp-haz
-
-# Example
-docker run \
-    --env JAVA_MEMORY="12g" \
-    ...
-    usgs/nshmp-haz
-```
-
-Where:
-
-* `JAVA_MEMORY` is the maximum memory for the JVM (default: 8g)
-
 ---
 
 * [**Documentation Index**](../README.md)
diff --git a/docs/pages/Calculation-Configuration.md b/docs/pages/Calculation-Configuration.md
index 097e8d592..cb84d1b3c 100644
--- a/docs/pages/Calculation-Configuration.md
+++ b/docs/pages/Calculation-Configuration.md
@@ -109,8 +109,8 @@ T ≤ 10 s   | 0.000333, 0.000499, 0.000749, 0.00112, 0.00169, 0.00253, <br>0.00
   * [Developer Basics](./Developer-Basics.md#developer-basics)
   * [Calculation Configuration](./Calculation-Configuration.md#calculation-configuration)
   * [Site Specification](./Site-Specification.md#site-specification)
-  * [Examples](../../etc/examples) (or
-    [on GitLab](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/main/etc/examples))
+  * [Using Docker](./Using-Docker.md#using-docker)
+  * See also the [examples](../../etc/examples) directory
 * [__Documentation Index__](../README.md)
 
 ---
diff --git a/docs/pages/Developer-Basics.md b/docs/pages/Developer-Basics.md
index 799479e25..03640b54a 100644
--- a/docs/pages/Developer-Basics.md
+++ b/docs/pages/Developer-Basics.md
@@ -58,9 +58,9 @@ git clone https://code.usgs.gov/ghsc/nshmp/nshmp-haz.git
   * [Developer Basics](./Developer-Basics.md#developer-basics)
   * [Calculation Configuration](./Calculation-Configuration.md#calculation-configuration)
   * [Site Specification](./Site-Specification.md#site-specification)
-  * [Examples](../../etc/examples) (or
-    [on GitLab](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/main/etc/examples))
-* [**Documentation Index**](../README.md)
+  * [Using Docker](./Using-Docker.md#using-docker)
+  * See also the [examples](../../etc/examples) directory
+* [__Documentation Index__](../README.md)
 
 ---
 ![USGS logo](./images/usgs-icon.png) &nbsp;[U.S. Geological Survey](https://www.usgs.gov)
diff --git a/docs/pages/Logic-Trees-&-Uncertainty.md b/docs/pages/Logic-Trees-&-Uncertainty.md
index e1c4f1022..8a7201f36 100644
--- a/docs/pages/Logic-Trees-&-Uncertainty.md
+++ b/docs/pages/Logic-Trees-&-Uncertainty.md
@@ -3,7 +3,7 @@
 The following page details the logic trees of epistemic uncertainty considered in NSHMs supported
 by *nshmp-haz*. Logic trees are represented in a NSHM using files ending in `-tree.json`.
 
-[[*TOC*]]
+[[_TOC_]]
 
 ## Terminology
 
diff --git a/docs/pages/Site-Specification.md b/docs/pages/Site-Specification.md
index 544130a53..2f1af5014 100644
--- a/docs/pages/Site-Specification.md
+++ b/docs/pages/Site-Specification.md
@@ -104,8 +104,8 @@ outside the 'calculation' polygon are set to zero. For an example, see the
   * [Developer Basics](./Developer-Basics.md#developer-basics)
   * [Calculation Configuration](./Calculation-Configuration.md#calculation-configuration)
   * [Site Specification](./Site-Specification.md#site-specification)
-  * [Examples](../../etc/examples) (or
-    [on GitLab](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/main/etc/examples))
+  * [Using Docker](./Using-Docker.md#using-docker)
+  * See also the [examples](../../etc/examples) directory
 * [__Documentation Index__](../README.md)
 
 ---
diff --git a/docs/pages/Using-Docker.md b/docs/pages/Using-Docker.md
new file mode 100644
index 000000000..d943d7e05
--- /dev/null
+++ b/docs/pages/Using-Docker.md
@@ -0,0 +1,267 @@
+# Using [Docker](https://docs.docker.com/install/)
+
+*nshmp-haz* is available as a public image from
+[Docker hub](https://hub.docker.com/r/usgs/nshmp-haz) with tags:
+
+* `latest`: Refers to the latest updates from the main or production branch
+* `development-latest`: Refers to forks of the repository.
+* `staging-latest`: Latest updates associated with the
+[main](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/main) branch
+* `production-latest`: Latest stable release associated with the
+[production](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/production) branch
+
+To ensure you have the latest *nshmp-haz* update associated with a specific tag,
+always first pull the image from Docker:
+
+```bash
+docker pull usgs/nshmp-haz:<tag>
+```
+
+> Replace `<tag>` with one of the above tags.
+
+Example:
+
+```bash
+docker pull usgs/nshmp-haz:production-latest
+```
+
+## Docker Memory on Mac
+
+By default, Docker Desktop for Mac is set to use 2 GB runtime memory. To run *nshmp-haz*, the
+memory available to Docker must be [increased](https://docs.docker.com/docker-for-mac/#advanced)
+to a minimum of 4 GB.
+
+## Run *nshmp-haz* in Docker
+
+```bash
+# Pull docker image
+docker pull usgs/nshmp-haz:latest 
+
+# Run docker image
+docker run \
+    --env CLASS_NAME=<DisaggCalc | HazardCalc | RateCalc> \
+    --env IML=<NUMBER> \
+    --env RETURN_PERIOD=<NUMBER> \
+    --volume /absolute/path/to/sites/file:/app/sites.<geojson | csv> \
+    --volume /absolute/path/to/config/file:/app/config.json \
+    --volume /absolute/path/to/output:/app/output \
+    usgs/nshmp-haz
+```
+
+Where:
+
+* `CLASS_NAME` is the nshmp-haz class to run:
+  * [DisaggCalc](../../src/main/java/gov/usgs/earthquake/nshmp/DisaggCalc.java)
+  * [HazardCalc](../../src/main/java/gov/usgs/earthquake/nshmp/HazardCalc.java)
+  * [RateCalc](../../src/main/java/gov/usgs/earthquake/nshmp/RateCalc.java)
+* Other arguments (local files mapped to files within the Docker container with `:/app/...`):
+  * (required) The absolute path to a [USGS model (NSHM)](./USGS-Models.md)
+    * Example: `$(pwd)/nshm-hawaii:/app/model`
+  * (required) The absolute path to a GeoJSON or CSV [site(s)](./Site-Specification.md) file
+    * CSV example: `$(pwd)/my-csv-sites.csv:/app/sites.csv`
+    * GeoJSON example: `$(pwd)/my-geojson-sites.geojson:/app/sites.geojson`
+  * (required) The absolute path to an output directory
+    * Example: `$(pwd)/my-hazard-output:/app/output`
+  * (optional) The absolute path to a [configuration](./Calculation-Configuration.md) file
+    * Example: `$(pwd)/my-custom-config.json:/app/config.json`
+
+## Examples
+
+### [`HazardCalc`](../../src/main/java/gov/usgs/earthquake/nshmp/HazardCalc.java) Example
+
+The following example runs the `HazardCalc` program in nshmp-haz with the
+[nshm-hawaii](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git) model and the
+assumption a GeoJSON [site](./Site-Specification.md) file exists named `sites.geojson`.
+
+```bash
+# Download Hawaii NSHM
+git clone https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git
+
+# Pull image
+docker pull usgs/nshmp-haz:latest 
+
+# Run nshmp-haz HazardCalc
+docker run \
+    --env CLASS_NAME="HazardCalc" \
+    --volume "$(pwd)/nshm-hawaii:/app/model" \
+    --volume "$(pwd)/sites.geojson" \
+    --volume "$(pwd)/hawaii-hazard-output:/app/output" \
+    usgs/nshmp-haz
+```
+
+### [`DisaggCalc`](../../src/main/java/gov/usgs/earthquake/nshmp/DisaggCalc.java) Example
+
+The following example runs the `DisaggCalc` program in nshmp-haz with the
+[nshm-hawaii](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git) model and the
+assumption a GeoJSON [site](./Site-Specification.md) file exists named `sites.geojson`.
+
+```bash
+# Download Hawaii NSHM
+git clone https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git
+
+# Pull image
+docker pull usgs/nshmp-haz:latest 
+
+# Run nshmp-haz DisaggCalc
+docker run \
+    --env CLASS_NAME="DisaggCalc" \
+    --env RETURN_PERIOD=475 \
+    --volume "$(pwd)/nshm-hawaii:/app/model" \
+    --volume "$(pwd)/sites.geojson" \
+    --volume "$(pwd)/hawaii-disagg-output:/app/output" \
+    usgs/nshmp-haz:latest
+```
+
+### [`RateCalc`](../../src/main/java/gov/usgs/earthquake/nshmp/RateCalc.java) Example
+
+The following example runs the `RateCalc` program in nshmp-haz with the
+[nshm-hawaii](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git) model and the
+assumption a GeoJSON [site](./Site-Specification.md) file exists named `sites.geojson`.
+
+```bash
+# Download Hawaii NSHM
+git clone https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git
+
+# Pull image
+docker pull usgs/nshmp-haz:latest 
+
+# Run nshmp-haz RateCalc
+docker run \
+    --env CLASS_NAME="RateCalc" \
+    --volume "$(pwd)/nshm-hawaii:/app/model" \
+    --volume "$(pwd)/sites.geojson" \
+    --volume "$(pwd)/hawaii-rate-output:/app/output" \
+    usgs/nshmp-haz
+```
+
+## Run Customization
+
+When running *nshmp-haz* with Docker the maximum JVM memory size can
+be set with the environment flag (-e, -env):
+
+```bash
+docker run \
+    --env JAVA_MEMORY=<MEMORY> \
+    ...
+    usgs/nshmp-haz
+
+# Example
+docker run \
+    --env JAVA_MEMORY="12g" \
+    ...
+    usgs/nshmp-haz
+```
+
+Where:
+
+* `JAVA_MEMORY` is the maximum memory for the JVM (default: 8g)
+
+## Run *nshmp-haz* web services in Docker
+
+### Build and Run Docker Locally
+
+The Docker image may be built with the provided web service [Dockerfile](../../ws.Dockerfile).
+
+```bash
+cd /path/to/nshmp-haz
+
+# Build docker image
+docker build -f ws.Dockerfile -t nshmp-haz-ws .
+
+# Run Docker image
+docker run -p 8080:8080 -v "path/to/model:/model" nshmp-haz-ws
+```
+
+Web service runs on [http://localhost:8080/](http://localhost:8080/)
+
+The hazard model is read in via Docker volumes.
+
+#### Local Docker Example with NSHM
+
+```bash
+# Build docker image
+cd /path/to/nshmp-haz
+docker build -f ws.Dockerfile -t nshmp-haz-ws .
+
+# Download NSHM CONUS
+cd ..
+git clone https://code.usgs.gov/ghsc/nshmp/nshms/nshm-conus
+
+# Run web services
+docker run -p 8080:8080 -v "$(pwd):/model" nshmp-haz-ws
+```
+
+Open browser to [http://localhost:8080/](http://localhost:8080/).
+
+### Run from Container Registry
+
+A public Docker image is avaialable from [Docker hub](https://hub.docker.com/r/usgs/nshmp-haz-ws).
+
+There are 4 main tags:
+
+* `latest`: Refers to the latest updates from the main or production branch
+* `development-latest`: Refers to forks of the repository.
+* `staging-latest`: Refers to the
+[main](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/main) branch and is the latest updates
+* `production-latest`: Refers to the
+[production](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/production) branch and is stable
+
+```bash
+# Pull image
+docker pull usgs/nshmp-haz-ws:latest 
+
+# Run
+docker run -p 8080:8080 -v "/path/to/model:/model" usgs/nshmp-haz-ws
+```
+
+Web service runs on [http://localhost:8080/](http://localhost:8080/)
+
+The hazard model is read in via Docker volumes.
+
+#### Container Registry Example with NSHM
+
+```bash
+# Pull image
+docker pull usgs/nshmp-haz-ws:latest 
+
+# Download NSHM CONUS
+cd ..
+git clone https://code.usgs.gov/ghsc/nshmp/nshms/nshm-conus
+
+# Run web services
+docker run -p 8080:8080 -v "$(pwd):/model" usgs/nshmp-haz-ws
+```
+
+Open browser to [http://localhost:8080/](http://localhost:8080/).
+
+### Java Memory
+
+When running **nshmp-haz** web services with Docker
+the initial (Xms) and maximum (Xmx) JVM memory sizes can
+be set with the environment flag (-e, -env):
+
+```bash
+docker run -p <PORT>:8080 -e JAVA_OPTS="-Xms<INITIAL> -Xmx<MAX>" -d usgs/nshmp-haz-ws
+
+# Example
+docker run -p 8080:8080 -e JAVA_OPTS="-Xms1g -Xmx8g" -d usgs/nshmp-haz-ws
+```
+
+Where `<INITIAL>` and `<MAX >`should be set to the desired initial and maximum memory sizes,
+respectively.
+
+---
+
+## Related Pages
+
+* [Building & Running](./Building-&-Running.md#building-&-running)
+  * [Developer Basics](./Developer-Basics.md#developer-basics)
+  * [Calculation Configuration](./Calculation-Configuration.md#calculation-configuration)
+  * [Site Specification](./Site-Specification.md#site-specification)
+  * [Using Docker](./Using-Docker.md#using-docker)
+  * See also the [examples](../../etc/examples) directory
+* [__Documentation Index__](../README.md)
+
+---
+![USGS logo](./images/usgs-icon.png) &nbsp;[U.S. Geological Survey](https://www.usgs.gov)
+National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/etc/examples/README.md b/etc/examples/README.md
index 75b377a93..96cb1e006 100644
--- a/etc/examples/README.md
+++ b/etc/examples/README.md
@@ -1,6 +1,10 @@
 # Examples
 
-These examples are designed to be executed locally while following the READMEs on GitLab.
+These examples are designed to be executed locally while following the READMEs on GitLab and
+assumes the reader has successfully downloaded and built the code as described in the
+[documentation](../../docs/README.md). Because each example builds on prior concepts, we recommend
+stepping through all the examples in order.
+
 All examples avoid a lengthy call to Java and the `HazardCalc` program by using the following
 system alias:
 
@@ -8,7 +12,7 @@ system alias:
 alias hazard='java -cp /path/to/nshmp-haz/build/libs/nshmp-haz.jar gov.usgs.earthquake.nshmp.HazardCalc'
 ```
 
-Because each example builds on prior concepts, it is best step through all the examples, however quickly.
+
 
 <!-- markdownlint-disable MD001 -->
 #### Start: [Example 1 – A simple hazard calculation](1-hazard-curve/README.md)
diff --git a/gradle/dependencies.gradle b/gradle/dependencies.gradle
index c28d21571..11c2ead62 100644
--- a/gradle/dependencies.gradle
+++ b/gradle/dependencies.gradle
@@ -1,4 +1,3 @@
-
 dependencies {
 
   // NSHMP
-- 
GitLab


From 4753f61aa7e6cea26c722d60f814ae9caca33ef9 Mon Sep 17 00:00:00 2001
From: Peter Powers <pmpowers@usgs.gov>
Date: Mon, 16 Jan 2023 20:18:54 -0700
Subject: [PATCH 3/5] lint fixes

---
 docs/pages/Building-&-Running.md              | 31 +++++++------
 docs/pages/Calculation-Configuration.md       | 14 +++---
 docs/pages/Code-Versions.md                   | 14 +++---
 docs/pages/Developer-Basics.md                |  2 +-
 docs/pages/Functional-PSHA.md                 | 28 ++++++------
 docs/pages/Ground-Motion-Models.md            | 30 ++++++-------
 docs/pages/Logic-Trees-&-Uncertainty.md       |  2 +-
 .../Magnitude-Frequency-Distributions.md      |  2 +-
 docs/pages/Model-Editions.md                  |  4 +-
 docs/pages/Model-Files.md                     | 10 ++---
 docs/pages/Model-Structure.md                 |  2 +-
 docs/pages/Site-Specification.md              |  4 +-
 docs/pages/Source-Types.md                    | 44 +++++++++----------
 docs/pages/Using-Docker.md                    |  2 +-
 etc/examples/README.md                        |  2 -
 15 files changed, 95 insertions(+), 96 deletions(-)

diff --git a/docs/pages/Building-&-Running.md b/docs/pages/Building-&-Running.md
index 121fa83b8..77c51d06c 100644
--- a/docs/pages/Building-&-Running.md
+++ b/docs/pages/Building-&-Running.md
@@ -1,13 +1,6 @@
 # Building & Running
 
-## Related Pages
-
-* [Building & Running](./Building-&-Running.md#building-&-running)
-  * [Developer Basics](./Developer-Basics.md#developer-basics)
-  * [Calculation Configuration](./Calculation-Configuration.md#calculation-configuration)
-  * [Site Specification](./Site-Specification.md#site-specification)
-  * [Using Docker](./Using-Docker.md#using-docker)
-  * See also the [examples](../../etc/examples) directory
+[TOC]
 
 ## Build and Run Locally
 
@@ -16,7 +9,7 @@ Building and running *nshmp-haz* requires prior installation of Git and Java. Pl
 
 ### Building
 
-_nshmp-haz_ uses the [Gradle](https://gradle.org/) build tool. Navigate to a location on your
+*nshmp-haz* uses the [Gradle](https://gradle.org/) build tool. Navigate to a location on your
 system where you want *nshmp-haz* code to reside, clone the repository, and compile:
 
 ```bash
@@ -33,7 +26,7 @@ downloading all required dependencies, including Gradle itself.
 
 ### Running
 
-_nshmp-haz_ applications may be run from the command line or as a local web service. Command line
+*nshmp-haz* applications may be run from the command line or as a local web service. Command line
 applications are recommended for long running hazard and disaggregation calculations, but most
 users will find the web service endpoints to be more flexible. Web services return
 [JSON](https://www.json.org/json-en.html) responses that can be parsed by most programming
@@ -41,7 +34,7 @@ languages and data analaysis and visualization programs (e.g. Matlab).
 
 ### Web Servies
 
-To run _nshmp-haz_ web services:
+To run *nshmp-haz* web services:
 
 ```bash
 ./gradlew run
@@ -57,7 +50,9 @@ java -jar build/libs/nshmp-haz.jar --model=path/to/model
 After startup, web services and documentation are now available at
 [http://localhost:8080/](http://localhost:8080/).
 
-See the [Matlab](../../etc/matlab) directory for examples of how to call the web services.
+See the [Matlab](../../etc/matlab) directory for examples of how to call the web services. To
+run the ground motion model (GMM) web services, please use the
+[*nshmp-haz-ws*](https://code.usgs.gov/ghsc/nshmp/nshmp-ws) repository.
 
 ### Command Line Hazard Calculation
 
@@ -68,11 +63,11 @@ measures. For example:
 java -cp path/to/nshmp-haz.jar gov.usgs.earthquake.nshmp.HazardCalc model sites [config]
 ```
 
-At a minimum, the hazard source [model](./Hazard-Model.md) and the 
+At a minimum, the hazard source [model](./Hazard-Model.md) and the
 [site](./Site-Specification.md)(s) at which to perform calculations must be specified. The source
 model should specified a path to a directory. A single site may be specified with a string;
 multiple sites must be specified using either a comma-delimited (CSV) or
-[GeoJSON](http://geojson.org) file. The path to a custom 
+[GeoJSON](http://geojson.org) file. The path to a custom
 [configuration](./Calculation-Configuration.md) file containing user-specific settings may
 optionally be supplied as a third argument. It can be used to override any calculation settings;
 if absent [default](./Calculation-Configuration.md) values are used.
@@ -96,6 +91,14 @@ files. Disaggregations also have some independent
 
 ---
 
+## Related Pages
+
+* [Building & Running](./Building-&-Running.md#building-&-running)
+  * [Developer Basics](./Developer-Basics.md#developer-basics)
+  * [Calculation Configuration](./Calculation-Configuration.md#calculation-configuration)
+  * [Site Specification](./Site-Specification.md#site-specification)
+  * [Using Docker](./Using-Docker.md#using-docker)
+  * See also the [examples](../../etc/examples) directory
 * [**Documentation Index**](../README.md)
 
 ---
diff --git a/docs/pages/Calculation-Configuration.md b/docs/pages/Calculation-Configuration.md
index cb84d1b3c..0ba6e1faa 100644
--- a/docs/pages/Calculation-Configuration.md
+++ b/docs/pages/Calculation-Configuration.md
@@ -13,7 +13,7 @@ may be overridden. See [building and running](./Building-&-Running.md) and the
 
 Parameter | Type | Default | Notes |
 --------- | ---- | ------- | ----- |
-__`hazard`__
+**`hazard`**
 &nbsp;&nbsp;&nbsp;`.exceedanceModel`       |`String`   | `"TRUNCATION_3SIGMA_UPPER"`| [`ExceedanceModel`][url-exceedance]
 &nbsp;&nbsp;&nbsp;`.truncationLevel`       |`Double`   | `3.0`                      | [1](#notes)
 &nbsp;&nbsp;&nbsp;`.imts`                  |`String[]` | `["PGV","PGA","SA0P01","SA0P02",`<br>`"SA0P03","SA0P05","SA0P075",`<br>`"SA0P1","SA0P15","SA0P2","SA0P25",`<br>`"SA0P3","SA0P4","SA0P5","SA0P75",`<br>`"SA1P0","SA1P5","SA2P0","SA3P0",`<br>`"SA4P0","SA5P0","SA7P5","SA10P0"]` | [`Imt`][url-imt]
@@ -23,25 +23,25 @@ __`hazard`__
 &nbsp;&nbsp;&nbsp;`.useSiteData`           |`Boolean`  | `true`                     | Enable site data (e.g. basin depths)
 &nbsp;&nbsp;&nbsp;`.customImls`            |`Map<String, Double[]>`  | `{}` (empty object)     | [2](#notes)
 &nbsp;&nbsp;&nbsp;`.valueFormat`           |`String`   | `"ANNUAL_RATE"`            | [`ValueFormat`][url-valueformat]
-__`gmm`__
+**`gmm`**
 &nbsp;&nbsp;&nbsp;`.dampingRatio`          |`Double`   | `0.05` (5%)                | Limited to range [0.005..0.3] 0.5% to 30%
 &nbsp;&nbsp;&nbsp;`.sigmaScale`            |`Double`   | `1.0` (100%, no scaling)   | Limited to range [0.5..1.0] 50% to 100%
 &nbsp;&nbsp;&nbsp;`.vertical`              |`Boolean`  | `false`                    | Compute vertical ground motions
-__`disagg`__
+**`disagg`**
 &nbsp;&nbsp;&nbsp;`.returnPeriod`          |`Double`   | `2475`                     |
 &nbsp;&nbsp;&nbsp;`.bins`                  |`Object`   |                            | [4](#notes)
 &nbsp;&nbsp;&nbsp;`.contributorLimit`      |`Double`   | `0.1`                      | [5](#notes)
-__`rate`__
+**`rate`**
 &nbsp;&nbsp;&nbsp;`.bins`                  |`Object`   |                            | [6](#notes)
 &nbsp;&nbsp;&nbsp;`.distance`              |`Double`   | `20` km
 &nbsp;&nbsp;&nbsp;`.distributionFormat`    |`String`   | `"INCREMENTAL"`            | [`DistributionFormat`][url-distribution]
 &nbsp;&nbsp;&nbsp;`.timespan`              |`Double`   | `30` years
 &nbsp;&nbsp;&nbsp;`.valueFormat`           |`String`   | `"ANNUAL_RATE"`            | [`ValueFormat`][url-valueformat]
-__`output`__                               |
+**`output`**                               |
 &nbsp;&nbsp;&nbsp;`.directory`             |`String`   | `hazout`
 &nbsp;&nbsp;&nbsp;`.dataTypes`             |`String[]` | `["TOTAL","MAP"]`          | [`DataType`][url-datatype]
 &nbsp;&nbsp;&nbsp;`.returnPeriods`         |`Double[]` | `[475,975,2475,10000]`     | [`ReturnPeriods`][url-returnperiods]
-__`performance`__
+**`performance`**
 &nbsp;&nbsp;&nbsp;`.optimizeGrids`         |`Boolean`  | `true`                     | [7](#notes)
 &nbsp;&nbsp;&nbsp;`.smoothGrids`           |`Boolean`  | `true`                     | [8](#notes)
 &nbsp;&nbsp;&nbsp;`.systemPartition`       |`Integer`  | `1000`                     | [9](#notes)
@@ -111,7 +111,7 @@ T ≤ 10 s   | 0.000333, 0.000499, 0.000749, 0.00112, 0.00169, 0.00253, <br>0.00
   * [Site Specification](./Site-Specification.md#site-specification)
   * [Using Docker](./Using-Docker.md#using-docker)
   * See also the [examples](../../etc/examples) directory
-* [__Documentation Index__](../README.md)
+* [**Documentation Index**](../README.md)
 
 ---
 ![USGS logo](./images/usgs-icon.png) &nbsp;[U.S. Geological Survey](https://www.usgs.gov)
diff --git a/docs/pages/Code-Versions.md b/docs/pages/Code-Versions.md
index 801a9b66f..973190a4b 100644
--- a/docs/pages/Code-Versions.md
+++ b/docs/pages/Code-Versions.md
@@ -1,35 +1,35 @@
 # Code Versions
 
 The static datasets of USGS NSHMs prior to 2014 were computed using Fortran (see
-[_nshmp-haz-fortran_](https://github.com/usgs/nshmp-haz-fortran])). The static datasets for the
+[*nshmp-haz-fortran*](https://github.com/usgs/nshmp-haz-fortran])). The static datasets for the
 2014 Conterminous U.S. NSHM were computed using the Fortran codes and
 [OpenSHA](https://opensha.org/) (for the California portion of the model). The dynamic versions
 of the 2008 and 2014 Conterminous U.S. models were then implemented in the 1st version of
-[_nshmp-haz_](https://github.com/usgs/nshmp-haz) (on GitHub). This updated Java codebase uses XML
+[*nshmp-haz*](https://github.com/usgs/nshmp-haz) (on GitHub). This updated Java codebase uses XML
 source models and supports the web services behind the dynamic calculations of the [Unified Hazard
 Hazard Tool](https://earthquake.usgs.gov/hazards/interactive/) (UHT).
 
-The 2nd version of _nshmp-haz_ (this repository) supercedes prior codebases. The development of this
+The 2nd version of *nshmp-haz* (this repository) supercedes prior codebases. The development of this
 version involved a significant refactoring of both the computational code and source model format.
 The source models are now defined using JSON, GeoJSON, and CSV files to better reflect the
 underlying logic trees and support uncertainty analysis.
 
-## Transitioning from _nshmp-haz_ v1 to v2
+## Transitioning from *nshmp-haz* v1 to v2
 
 NSHMs are very detailed and migrating from one format to another is not trivial and prone to error.
 Moreover, approximations (e.g. using 3.1415 for Pi rather than the the value built into most
 languages) can yield different results. When multiple such small changes exist, deciphering what
 is giving rise to differences in results can be challenging.
 
-To document the transition from _nshmp-haz_ v1 to v2, we here attach comparison maps at four return
+To document the transition from *nshmp-haz* v1 to v2, we here attach comparison maps at four return
 periods (475, 975, 2475, and 10,000 year) for the 2018 Conterminous U.S. model. Maps are included
 for PGA and 3 spectral periods ( 0.2 s, 1 s, and 5 s). There are no differences in the Central &
 Eastern U.S. and differences in the WUS are <<1%. The difference in hazard in the vicinity of
-Salt Lake City arises from the cluster models in _nshmp-haz_ v1 not being able to consider the
+Salt Lake City arises from the cluster models in *nshmp-haz* v1 not being able to consider the
 additional epistemic uncertainty added to the the NGA-West2 ground motion models.
 
 We continue to investigate the cause of other differences but they are small enough that we are
-comfortable moving forward deploying _nshmp-haz_ v2 codes and models to our public web services and
+comfortable moving forward deploying *nshmp-haz* v2 codes and models to our public web services and
 applications. This repository includes end-to-end tests for supported NSHMs that may be run
 on demand.
 
diff --git a/docs/pages/Developer-Basics.md b/docs/pages/Developer-Basics.md
index 03640b54a..346ace647 100644
--- a/docs/pages/Developer-Basics.md
+++ b/docs/pages/Developer-Basics.md
@@ -60,7 +60,7 @@ git clone https://code.usgs.gov/ghsc/nshmp/nshmp-haz.git
   * [Site Specification](./Site-Specification.md#site-specification)
   * [Using Docker](./Using-Docker.md#using-docker)
   * See also the [examples](../../etc/examples) directory
-* [__Documentation Index__](../README.md)
+* [**Documentation Index**](../README.md)
 
 ---
 ![USGS logo](./images/usgs-icon.png) &nbsp;[U.S. Geological Survey](https://www.usgs.gov)
diff --git a/docs/pages/Functional-PSHA.md b/docs/pages/Functional-PSHA.md
index 0b936d6c1..b797d8f6a 100644
--- a/docs/pages/Functional-PSHA.md
+++ b/docs/pages/Functional-PSHA.md
@@ -29,17 +29,17 @@ in magnitude, *M*, and distance, *R*). This formulation relies on models of grou
 give the probability that an intensity measure level of interest will be exceeded conditioned on
 the occurrence of a particular earthquake. Such models are commonly referred to as:
 
-* __Intensity measure relationships__
-* __Attenuation relationships__
-* __Ground motion prediction equations (GMPEs)__
-* __Ground motion models (GMMs)__
+* **Intensity measure relationships**
+* **Attenuation relationships**
+* **Ground motion prediction equations (GMPEs)**
+* **Ground motion models (GMMs)**
 
 The parameterization of modern models (e.g. NGA-West2; Bozorgnia et al., 2014) extends to much
 more than magnitude and distance, including, but not limited to:
 
-* __Multiple distance metrics__ (e.g. rJB, rRup, rX, rY)
-* __Fault geometry__ (e.g. dip, width, rupture depth, hypocentral depth)
-* __Site characteristics__ (e.g. basin depth terms, site type or Vs30 value)
+* **Multiple distance metrics** (e.g. rJB, rRup, rX, rY)
+* **Fault geometry** (e.g. dip, width, rupture depth, hypocentral depth)
+* **Site characteristics** (e.g. basin depth terms, site type or Vs30 value)
 
 ## Simple, yes, but used for so much more…
 
@@ -119,10 +119,10 @@ foreach IMT {
 Break the traditional PSHA formulation down into discrete steps and preserve the data associated
 with each step:
 
-* __[1]__ Source & Site parameterization
-* __[2]__ Ground motion calculation (mean and standard deviation only)
-* __[3]__ Exceedance curve calculation (per source)
-* __[4]__ Recombine
+* **[1]** Source & Site parameterization
+* **[2]** Ground motion calculation (mean and standard deviation only)
+* **[3]** Exceedance curve calculation (per source)
+* **[4]** Recombine
 
 Whereas the traditional pipeline looks something like this:
 
@@ -132,9 +132,9 @@ The functional pipeline can be processed stepwise:
 
 ![image](images/psha-functional.png "PSHA functional pipeline")
 
-__Need a disaggregation?__ Revisit and parse the results of steps 1 and 2
+**Need a disaggregation?** Revisit and parse the results of steps 1 and 2
 
-__Need a response spectra?__ Spawn more calculations, one for each IMT, at step 2.
+**Need a response spectra?** Spawn more calculations, one for each IMT, at step 2.
 
 ## Benefits
 
@@ -161,7 +161,7 @@ __Need a response spectra?__ Spawn more calculations, one for each IMT, at step
 
 ---
 
-[__Documentation Index__](../README.md)
+[**Documentation Index**](../README.md)
 
 ---
 ![USGS logo](./images/usgs-icon.png) &nbsp;[U.S. Geological Survey](https://www.usgs.gov)
diff --git a/docs/pages/Ground-Motion-Models.md b/docs/pages/Ground-Motion-Models.md
index 4419608b2..cb69268a8 100644
--- a/docs/pages/Ground-Motion-Models.md
+++ b/docs/pages/Ground-Motion-Models.md
@@ -5,7 +5,7 @@ the occurrence of various earthquakes. The following tables list the GMMs suppor
 is not uncommon for a GMM to have multiple concrete implementations. For instance, most subduction
 GMMs, as published, support both interface and intraslab events.
 
-[[_TOC_]]
+[TOC]
 
 ## GMM Configuration
 
@@ -44,7 +44,7 @@ The following sample `gmm-config.json` file applies the NGA-West 2 epistemic unc
 
 ## GMM Uncertainty Models
 
-_nshmp-haz_ supports additional epistemic uncertainty models derived from the PEER NGA-West 1
+*nshmp-haz* supports additional epistemic uncertainty models derived from the PEER NGA-West 1
 and PEER NGA-West 2 projects. These models both have factors for distance (`Rrup`) bins
 Rrup < 10 km, 10 km <= Rrup, < 30 km, and 30 km <= Rrup, and for magnitude bins M < 6.0, 6.0 <=
 M < 7.0, and 7.0 <= M. These models can be applied within the `gmm-config.json` file as shown in
@@ -52,14 +52,14 @@ the [GMM Uncertainty](#gmm-uncertainty) section above.
 
 ## GMMs By Tectonic Setting
 
-GMMs available in _nshmp-haz_ are tabulated by tectonic setting below. See the javadocs for the
+GMMs available in *nshmp-haz* are tabulated by tectonic setting below. See the javadocs for the
 [GMM Package](https://earthquake.usgs.gov/nshmp/docs/nshmp-lib/gov/usgs/earthquake/nshmp/gmm/package-summary.html)
 for implementation details of each GMM and comprehensive lists of GMM IDs.
 
 ### Active Crust GMMs
 
 Reference | ID | Component | Notes
-:---------|:--:|:---------:|:------:
+:---------|:---|:----------|:------:
 **NGA-West 2**
 [Abrahamson et al., 2014](http://dx.doi.org/10.1193/070913EQS198M) | ASK_14<br>ASK_14_BASIN | RotD50 |
 [Boore et al., 2014](http://dx.doi.org/10.1193/070113EQS184M) | BSSA_14<br>BSSA_14_BASIN | RotD50 |
@@ -93,7 +93,7 @@ NGA-East<br>[Goulet et al., 2017](https://peer.berkeley.edu/sites/default/files/
 [Shahjouei and Pezeshk, 2016](http://dx.doi.org/10.1785/0120140367) | NGA_EAST_SEED_SP16 | RotD50 | 3
 **Other**
 [Atkinson, 2008](http://dx.doi.org/10.1785/0120070199)<br>[Atkinson & Boore, 2011](http://dx.doi.org/10.1785/0120100270) | ATKINSON_08_PRIME | horizontal | 4
-[Atkinson & Boore, 2006](http://dx.doi.org/10.1785/0120050245) | _AB\_06\_\*<br>140BAR\|200BAR<br>none\|\_AB\|\_J_ | horizontal | 4
+[Atkinson & Boore, 2006](http://dx.doi.org/10.1785/0120050245) | AB_06_*<br>140BAR \| 200BAR<br>none \| \_AB \| \_J | horizontal | 4
 [Atkinson & Boore, 2006](http://dx.doi.org/10.1785/0120050245)<br>[Atkinson & Boore, 2011](http://dx.doi.org/10.1785/0120100270) | AB_06_PRIME | horizontal | 4
 [Campbell, 2003](http://dx.doi.org/10.1785/0120020002) | CAMPBELL_03<br>CAMPBELL_03_AB<br>CAMPBELL_03_J | Geometric mean | 4
 [Frankel et al., 1996](https://pubs.usgs.gov/of/1996/532/) | FRANKEL_96<br>FRANKEL_96_AB<br>FRANKEL_96_J | not specified | 4
@@ -112,30 +112,28 @@ for individual NGA-East component model IDs
 
 ### Subduction GMMs
 
-_Note: See the [GMM javadocs](https://earthquake.usgs.gov/nshmp/docs/nshmp-lib/gov/usgs/earthquake/nshmp/gmm/Gmm.html)
-for a comprehensive list of GMM IDs._
+*Note: See the [GMM javadocs](https://earthquake.usgs.gov/nshmp/docs/nshmp-lib/gov/usgs/earthquake/nshmp/gmm/Gmm.html)
+for a comprehensive list of GMM IDs.*
 
 Reference | ID | Component | Notes
 :---------|:---|:----------|:------:
 **NGA-Subduction**
-[Abrahamson & Gülerce, 2020](https://peer.berkeley.edu/sites/default/files/2020_25.pdf) | _AG\_20\_\*<br>GLOBAL\|CASCADIA\|ALASKA<br>INTERFACE\|SLAB<br>no basin\|\_BASIN_ | RotD50
-[Kuehn et al., 2020](https://peer.berkeley.edu/sites/default/files/2020_04_kuehn_final.pdf) | _KBCG\_20\_\*<br>GLOBAL\|CASCADIA\|ALASKA<br>INTERFACE\|SLAB<br>no basin\|\_BASIN_ | RotD50
-[Parker et al., 2020](https://peer.berkeley.edu/sites/default/files/2020_03_parker_final.pdf) | _PSHAB\_20\_\*<br>GLOBAL\|CASCADIA\|ALASKA<br>INTERFACE\|SLAB<br>no basin\|\_BASIN_ | RotD50
+[Abrahamson & Gülerce, 2020](https://peer.berkeley.edu/sites/default/files/2020_25.pdf) | AG_20_*<br>GLOBAL \| CASCADIA \| ALASKA<br>INTERFACE \| SLAB<br> (none) \| \_BASIN | RotD50
+[Kuehn et al., 2020](https://peer.berkeley.edu/sites/default/files/2020_04_kuehn_final.pdf) | KBCG_20_*<br>GLOBAL \| CASCADIA \| ALASKA<br>INTERFACE \| SLAB<br>(none) \| \_BASIN | RotD50
+[Parker et al., 2020](https://peer.berkeley.edu/sites/default/files/2020_03_parker_final.pdf) | PSHAB_20_*<br>GLOBAL \| CASCADIA \| ALASKA<br>INTERFACE \| SLAB<br>(none) \|\_BASIN | RotD50
 **Other**
-[Atkinson & Boore, 2003](http://dx.doi.org/10.1785/0120020156) | _AB\_03\*<br>GLOBAL\|CASCADIA<br>INTERFACE\|SLAB<br>none\|\_LOW_SAT_| horizontal |
+[Atkinson & Boore, 2003](http://dx.doi.org/10.1785/0120020156) | AB_03_*<br>GLOBAL \| CASCADIA<br>INTERFACE \| SLAB<br> (none) \| \_LOW_SAT| horizontal |
 [Atkinson & Macias, 2009](http://dx.doi.org/10.1785/0120080147) | AM_09_INTERFACE<br>AM_09_INTERFACE_BASIN | Geometric mean | 1
-BC Hydro<br>[Abrahamson et al., 2016](http://dx.doi.org/10.1193/051712EQS188MR) | _BCHYDRO\_12\_\*<br>INTERFACE\|SLAB<br>none\|\_BASIN<br>none\|\_BACKARC_ | Geometric mean |
-BC Hydro NGA<br>[Abrahamson et al., 2018](https://peer.berkeley.edu/sites/default/files/2018_02_abrahamson_9.10.18.pdf)² | _BCHYDRO\_18\_NGA\_\*<br>INTERFACE\|SLAB<br>none\|\_NO_EPI_ | Geometric mean | 3
+BC Hydro<br>[Abrahamson et al., 2016](http://dx.doi.org/10.1193/051712EQS188MR) | BCHYDRO_12_*<br>INTERFACE \| SLAB<br> (none) \| \_BASIN<br>(none) \| \_BACKARC | Geometric mean |
+BC Hydro NGA<br>[Abrahamson et al., 2018](https://peer.berkeley.edu/sites/default/files/2018_02_abrahamson_9.10.18.pdf)² | BCHYDRO_18_NGA_*<br>INTERFACE \| SLAB<br> (none) \| \_NO_EPI | Geometric mean | 3
 [McVerry et al., 2000](http://doi.org/10.5459/BNZSEE.39.1.1-58) | MCVERRY_00_INTERFACE<br>MCVERRY_00_SLAB<br>MCVERRY_00_VOLCANIC | Max-horizontal,<br>also supports geometric mean | 4
 [Youngs et al., 1997](http://dx.doi.org/10.1785/gssrl.68.1.58) | YOUNGS_97_INTERFACE<br>YOUNGS_97_SLAB | Geometric mean |
-[Zhao et al., 2006](http://dx.doi.org/10.1785/0120050122) | _ZHAO\_06\_\*<br>INTERFACE\|SLAB<br>none\|\_BASIN_ | Geometric mean |
-[Zhao et al., 2016](http://dx.doi.org/10.1785/0120150034)<br>[Zhao et al., 2016](http://dx.doi.org/10.1785/0120150056) | ZHAO_16_INTERFACE<br>ZHAO_16_SLAB<br>_ZHAO_16_UPPER_MANTLE_ | Geometric mean<br>(random orientation) | 5
+[Zhao et al., 2006](http://dx.doi.org/10.1785/0120050122) | ZHAO_06_*<br>INTERFACE \| SLAB<br> (none) \| \_BASIN | Geometric mean |
 
 ¹ Interface only  
 ² Likely to be superseded by the final EQ Spectra paper  
 ³ Calibrated for Cascadia use only  
 ⁴ New Zealand model, does not correspond directly with US site class model  
-⁵ Subduction Slab and Interface  
 
 ### Regional and Specialized GMMs
 
diff --git a/docs/pages/Logic-Trees-&-Uncertainty.md b/docs/pages/Logic-Trees-&-Uncertainty.md
index 8a7201f36..e1c4f1022 100644
--- a/docs/pages/Logic-Trees-&-Uncertainty.md
+++ b/docs/pages/Logic-Trees-&-Uncertainty.md
@@ -3,7 +3,7 @@
 The following page details the logic trees of epistemic uncertainty considered in NSHMs supported
 by *nshmp-haz*. Logic trees are represented in a NSHM using files ending in `-tree.json`.
 
-[[_TOC_]]
+[[*TOC*]]
 
 ## Terminology
 
diff --git a/docs/pages/Magnitude-Frequency-Distributions.md b/docs/pages/Magnitude-Frequency-Distributions.md
index 365758f13..743e05351 100644
--- a/docs/pages/Magnitude-Frequency-Distributions.md
+++ b/docs/pages/Magnitude-Frequency-Distributions.md
@@ -5,7 +5,7 @@ capable of generating, otherwise known as a magnitude-frequency distribution (MF
 types of MFDs supported in a hazard model are described below. Unless otherwise noted, all the
 members listed in the JSON examples below are required.
 
-[[_TOC_]]
+[TOC]
 
 ## Single
 
diff --git a/docs/pages/Model-Editions.md b/docs/pages/Model-Editions.md
index 206a5de56..fb9923317 100644
--- a/docs/pages/Model-Editions.md
+++ b/docs/pages/Model-Editions.md
@@ -46,7 +46,7 @@ Hawaii            | 1998 | 1.1.0 | | TBD | |
 Hawaii            | 1998 | 1.0.0 |:small_blue_diamond:| | ASCE7-10 |
 Puerto Rico & <br/> U.S. Virgin Islands | 2003 | v1.0.0 | | | |
 
-<sup>†</sup> __Note on the 2014 conterminous U.S. NSHM:__ Initial publication of the
+<sup>†</sup> **Note on the 2014 conterminous U.S. NSHM:** Initial publication of the
 [2014 model](https://www.usgs.gov/natural-hazards/earthquake-hazards/science/2014-united-states-lower-48-seismic-hazard-long-term)
 included data to support updates to the U.S. Building Code, specifically hazard curves for peak
 ground acceleration (PGA), and 0.2 and 1.0 second spectral accelerations, all at a BC boundary site
@@ -99,7 +99,7 @@ one of the dynamic editions is likely better.
   * [Model Editions](./Model-Editions.md#model-editions)
   * [Logic Trees & Uncertainty](./Logic-Trees-&-Uncertainty.md#logic-trees-&-uncertainty)
   * [Code Versions](./Code-Versions.md#code-versions)
-* [__Documentation Index__](../README.md)
+* [**Documentation Index**](../README.md)
 
 ---
 ![USGS logo](./images/usgs-icon.png) &nbsp;[U.S. Geological Survey](https://www.usgs.gov)
diff --git a/docs/pages/Model-Files.md b/docs/pages/Model-Files.md
index 347935dd0..36cc69f82 100644
--- a/docs/pages/Model-Files.md
+++ b/docs/pages/Model-Files.md
@@ -4,7 +4,7 @@ A variety of logic tree, configuration, and data files that are common to all mo
 types are described below and on related pages for specific model components, for example, ground
 motion models (GMMs) or magnitude-frequency distributions (MFDs).
 
-[[_TOC_]]
+[TOC]
 
 ## Model and Calculation Configuration
 
@@ -81,7 +81,7 @@ or its children will be processed; any standalone sources will be ignored. For e
 **source-group.json:** A specialized form of logic tree that describes model branches that are
 additive and therefore does not include weights. Examples from the NSHM for the conterminous U.S.
 NSHM include the Cascadia segmented and partial-rupture models, and the New Madrid 1500-yr cluster
-branches. The branch objects in a source group _may_ include an optional `scale` member that can
+branches. The branch objects in a source group *may* include an optional `scale` member that can
 be used to impose a probability of occurrence or other scaling requred by a NSHM. If absent, the
 `scale` value is one.
 
@@ -99,7 +99,7 @@ be used to impose a probability of occurrence or other scaling requred by a NSHM
 ```
 
 **tree-info.json:** Top level source trees and groups must be accompanied by a file that contains
-a unique integer ID for the logic tree. This file _may_ also include a `name` field that, if
+a unique integer ID for the logic tree. This file *may* also include a `name` field that, if
 present, will be used instead of the enclosing directory name, but it is not required.
 
  ```json
@@ -124,7 +124,7 @@ For example:
 ```
 
 See the [ground motion models](./Ground-Motion-Models.md) page for details on GMMs supported in
-_nshmp-haz_ and the related `gmm-config.json` files that governs GMM behavior.
+*nshmp-haz* and the related `gmm-config.json` files that governs GMM behavior.
 
 ### MFD Logic Trees
 
@@ -151,7 +151,7 @@ source-tree branches.
 How MFDs are intialized (or realized) depends on the presence and contents of `mfd-config.json` and
 `rate-tree.json` files. See the
 [magnitude frequency distributions](./Magnitude-Frequency-Distributions.md) page for details on
-these files and the types of MFDs supported in _nshmp-haz_.
+these files and the types of MFDs supported in *nshmp-haz*.
 
 ## Rupture Sets
 
diff --git a/docs/pages/Model-Structure.md b/docs/pages/Model-Structure.md
index 7af9614f6..20e324791 100644
--- a/docs/pages/Model-Structure.md
+++ b/docs/pages/Model-Structure.md
@@ -6,7 +6,7 @@ self describing and represent logic trees and other relationships between source
 (JSON), source geometry (GeoJSON features), and earthquake rate data (CSV). JSON is well-suited
 for representing model data and relationships and is supported in most programming languages.
 
-[[_TOC_]]
+[TOC]
 
 ## Directory Structure
 
diff --git a/docs/pages/Site-Specification.md b/docs/pages/Site-Specification.md
index 2f1af5014..3b7990ed0 100644
--- a/docs/pages/Site-Specification.md
+++ b/docs/pages/Site-Specification.md
@@ -4,7 +4,7 @@ The sites at which to perform hazard and related calculations may be defined in
 ways. Examples of the file formats described below are available in the resource directory:
 [`etc/nshm`](../../etc/nshm/README.md).
 
-__Note on Coordinates:__ *nshmp-haz* supports longitude and latitude values in the closed
+**Note on Coordinates:** *nshmp-haz* supports longitude and latitude values in the closed
 ranges `[-360° ‥ 360°]` and `[-90° ‥ 90°]`. However, mixing site and/or source
 coordinates across the antimeridian (the -180° to 180° transition) will yield unexpected results.
 For Pacific models and calculations, always use positive or negative longitudes exclusively.
@@ -106,7 +106,7 @@ outside the 'calculation' polygon are set to zero. For an example, see the
   * [Site Specification](./Site-Specification.md#site-specification)
   * [Using Docker](./Using-Docker.md#using-docker)
   * See also the [examples](../../etc/examples) directory
-* [__Documentation Index__](../README.md)
+* [**Documentation Index**](../README.md)
 
 ---
 ![USGS logo](./images/usgs-icon.png) &nbsp;[U.S. Geological Survey](https://www.usgs.gov)
diff --git a/docs/pages/Source-Types.md b/docs/pages/Source-Types.md
index 76d90b847..ddaa27b71 100644
--- a/docs/pages/Source-Types.md
+++ b/docs/pages/Source-Types.md
@@ -10,17 +10,17 @@ represent models of smoothed seismicity in both crustal and subduction intraslab
 may also be used for fault zones where there is a history of large earthquakes but the fault
 geometry itself is unknown or very poorly defined.
 
-[[_TOC_]]
+[TOC]
 
-Source models for use with _nshmp-haz_ are defined using [JSON](https://www.json.org) and
-[GeoJSON](https://geojson.org). _nshmp-haz_ makes determinations about how to represent a source
+Source models for use with *nshmp-haz* are defined using [JSON](https://www.json.org) and
+[GeoJSON](https://geojson.org). *nshmp-haz* makes determinations about how to represent a source
 based on a GeoJSON geometry type in conjunction with supporting JSON configuration files. Example
 source configuration files, `*-config.json`, are provided with each source type description.
 Configuration files must be fully specified with `null` JSON member values used to specify 'do
 nothing' where appropriate. Any configuration member value in ALL_CAPS indicates the value is one
 of a fixed number of options commonly referred to as an enum.
 
-__Note on Coordinates:__ _nshmp-haz_ supports longitude and latitude values in the closed ranges
+**Note on Coordinates:** *nshmp-haz* supports longitude and latitude values in the closed ranges
 `[-360°‥360°]` and `[-90°‥90°]`. Note, however, that mixing site and/or source coordinates across
 the antimeridian (the -180° to 180° transition) will yield unexpected results. For Pacific models
 and calculations, always use positive or negative longitudes exclusively.
@@ -43,7 +43,7 @@ Grid sources are represented in a model using a logic tree with a `rupture-sets.
 ruptures on each branch.  Because gridded seismicity models may be governed by regionally
 varying MFD properties (e.g. `mMax`), rupture sets for grids are defined in a JSON array.
 
-__rupture-sets.json__: Defines an array of one or more rupture sets. Multiple rupture sets are
+**rupture-sets.json**: Defines an array of one or more rupture sets. Multiple rupture sets are
 used to model regional differences in MFD properties such as maximum magnitude. The `feature`
 member points to the ID of a geojson feature (in the `grid-sources/features` directory) that
 defines the bounds of the gridded seismicity source. A grid rupture set `mfd-tree` is never
@@ -62,7 +62,7 @@ defined inline and always points to a tree in a
 ]
 ```
 
-__grid-config.json__: A `grid-depth-map` defines a mapping of magnitude ranges to logic trees of
+**grid-config.json**: A `grid-depth-map` defines a mapping of magnitude ranges to logic trees of
 depth distributions. The map can use arbitrary names as keys, but the magnitude ranges defined by
 each member must be non-overlapping. The magnitude ranges are interpreted as closed (inclusive) –
 open (exclusive), e.g. [mMin..mMax). `maxDepth` constrains the maximum depth of any pseudo fault
@@ -107,7 +107,7 @@ to upper-right). While most gridded rate files contain columns of longitude, lat
 some may contain depth values (intraslab sources), maximum magnitude caps, or other values. Scaled
 spatial PDFs are the preferred approach to modeling regional rate variations, however it is also
 possible to define explicit MFDs at each grid node. To do so, the `spatial-pdf` member
-of a __rupture-sets.json__ is replaced with `grid-mfds`. See
+of a **rupture-sets.json** is replaced with `grid-mfds`. See
 `2018 CONUS NSHM > active-crust > grid-sources` for examples of both approaches.
 
 ## Zone Sources
@@ -149,7 +149,7 @@ directly.
 }
 ```
 
-__zone-config.json:__ Zone source model configuration is identical to a grid source configuration.
+**zone-config.json:** Zone source model configuration is identical to a grid source configuration.
 
 ```json
 {
@@ -188,7 +188,7 @@ they occur in multiple locations on the fault surface with appropriately scaled
 associated with finite fault models may be explicitly defined or derived from slip rates.
 Fault rupture rates may be modeled using explicitly defined MFDs or logic trees of slip rate.
 
-__fault-source.geojson__: Defines the geometry and properties of a single source. In the example
+**fault-source.geojson**: Defines the geometry and properties of a single source. In the example
 below the presence of a `rate-map` property indicates MFDs should be constructed from the supplied
 slip rates and using the weights defined in a `rate-tree.json`.
 
@@ -235,7 +235,7 @@ slip rates and using the weights defined in a `rate-tree.json`.
 }
 ```
 
-__fault-config.json__: Controls the point spacing on a gridded surface used to realize the fault
+**fault-config.json**: Controls the point spacing on a gridded surface used to realize the fault
 geometry as well as define the models to use for magnitude scaling and rupture floating. Dip
 variations and an associated slip-rate scaling model are also supported for normal faults.
 
@@ -249,9 +249,9 @@ variations and an associated slip-rate scaling model are also supported for norm
 }
 ```
 
-__rupture-set.json__: When a fault source is represented with a logic tree a
-`rupture-set.json` defines the ruptures for each branch. A rupture set _may_ also define custom
-properties and _may_ also contain a `sections` member that defines the fault sections for the
+**rupture-set.json**: When a fault source is represented with a logic tree a
+`rupture-set.json` defines the ruptures for each branch. A rupture set *may* also define custom
+properties and *may* also contain a `sections` member that defines the fault sections for the
 rupture set (see note on fault section stitching, [below](#fault-section-stitching)).
 
 ```json
@@ -272,10 +272,10 @@ rupture set (see note on fault section stitching, [below](#fault-section-stitchi
 When multiple sections are defined for a rupture, the ruptures must be defined in an order that
 preserves the U.S. structural geology right-hand-rule. When stitched together, repeated locations
 at the enpoints of adjacent sections, if present, are removed. The properties of the first section
-govern the properties of the stitched fault, however, a rupture-set _may_ include a properties
+govern the properties of the stitched fault, however, a rupture-set *may* include a properties
 member, the contents of which will override the properties of the first stitched section. Although
 it would be better to have geometric properties of stitched sections be calculated dynamically,
-the current approach preserves support for past models. A rupture-set _may_ also include a
+the current approach preserves support for past models. A rupture-set *may* also include a
 `coordinates` member that can be used to represent a smoothed trace geometry where stitched
 sections do not share common endpoints.
 
@@ -287,9 +287,9 @@ as the joint probability of exceeding ground motions from each independent event
 a cluster may only have an mfd-tree composed of `Mfd.Type.SINGLE` MFDs and the mfd-trees must
 match across all sources in a cluster (i.e. each mfd-tree has the same IDs and weights).
 
-__cluster-set.json__ A specialized type of rupture set, this file defines the array of fault
+**cluster-set.json** A specialized type of rupture set, this file defines the array of fault
 rupture sets that make up a 'cluster'. As with fault sources, the nested rupture sets in a cluster
-set _may_ define `properties` and `sections` members.
+set *may* define `properties` and `sections` members.
 
 ```json
 {
@@ -320,13 +320,13 @@ This specialized fault source type supports inversion based rupture rate estimat
 on a fault network such as that used for UCERF3 in the 2014 and 2018 NSHMs for the conterminous
 U.S. Fault system source sets require three files: `rupture_set.json`, `sections.geojson`, and
 `ruptures.csv` that are placed together within folders defining branches of a fault system
-logic tree. Note that system sources _may_ have complementary gridded seismicity source models
+logic tree. Note that system sources *may* have complementary gridded seismicity source models
 with matching logic trees.
 
-__rupture-set.json__: Provides identifying information for the ruptures defined in the adjacant
+**rupture-set.json**: Provides identifying information for the ruptures defined in the adjacant
 sections and ruptures files.
 
-__sections.geojson__: defines a feature collection of the fault sections in a fault network.
+**sections.geojson**: defines a feature collection of the fault sections in a fault network.
 Because fault sections are derived by dividing larger faults into subsections, section features
 contain several properties that differ from standalone fault section source models (e.g.
 `dip-direction`).
@@ -362,7 +362,7 @@ contain several properties that differ from standalone fault section source mode
 }
 ```
 
-__ruptures.csv__: Defines the properties of every rupture. The last column in a rupture file
+**ruptures.csv**: Defines the properties of every rupture. The last column in a rupture file
 defines the ordered array of participating fault section IDs using the shorthand
 `1127:1131-2411:2412`. Colons denote continous ranges of sections and hyphens denote breaks.
 
@@ -389,7 +389,7 @@ using an `slab-config.json` file.
   * [Magnitude Frequency Distributions (MFDs)](./Magnitude-Frequency-Distributions.md#magnitude-frequency-distributions)
   * [Rupture Scaling Relations](./Rupture-Scaling-Relations.md#rupture-scaling-relations)
   * [Ground Motion Models (GMMs)](./Ground-Motion-Models.md#ground-motion-models)
-* [__Documentation Index__](../README.md)
+* [**Documentation Index**](../README.md)
 
 ---
 ![USGS logo](./images/usgs-icon.png) &nbsp;[U.S. Geological Survey](https://www.usgs.gov)
diff --git a/docs/pages/Using-Docker.md b/docs/pages/Using-Docker.md
index d943d7e05..501d12566 100644
--- a/docs/pages/Using-Docker.md
+++ b/docs/pages/Using-Docker.md
@@ -260,7 +260,7 @@ respectively.
   * [Site Specification](./Site-Specification.md#site-specification)
   * [Using Docker](./Using-Docker.md#using-docker)
   * See also the [examples](../../etc/examples) directory
-* [__Documentation Index__](../README.md)
+* [**Documentation Index**](../README.md)
 
 ---
 ![USGS logo](./images/usgs-icon.png) &nbsp;[U.S. Geological Survey](https://www.usgs.gov)
diff --git a/etc/examples/README.md b/etc/examples/README.md
index 96cb1e006..21de19b15 100644
--- a/etc/examples/README.md
+++ b/etc/examples/README.md
@@ -12,8 +12,6 @@ system alias:
 alias hazard='java -cp /path/to/nshmp-haz/build/libs/nshmp-haz.jar gov.usgs.earthquake.nshmp.HazardCalc'
 ```
 
-
-
 <!-- markdownlint-disable MD001 -->
 #### Start: [Example 1 – A simple hazard calculation](1-hazard-curve/README.md)
 
-- 
GitLab


From 6a07b4bb217b64b2996393b28c511380129c7811 Mon Sep 17 00:00:00 2001
From: Peter Powers <pmpowers@usgs.gov>
Date: Thu, 19 Jan 2023 14:29:25 -0700
Subject: [PATCH 4/5] stream lambda refactor

---
 src/main/java/gov/usgs/earthquake/nshmp/DisaggCalc.java | 2 +-
 src/main/java/gov/usgs/earthquake/nshmp/HazardMaps.java | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/main/java/gov/usgs/earthquake/nshmp/DisaggCalc.java b/src/main/java/gov/usgs/earthquake/nshmp/DisaggCalc.java
index 0c726e199..6275df2b5 100644
--- a/src/main/java/gov/usgs/earthquake/nshmp/DisaggCalc.java
+++ b/src/main/java/gov/usgs/earthquake/nshmp/DisaggCalc.java
@@ -260,7 +260,7 @@ public class DisaggCalc {
         .splitToList(line)
         .stream()
         .skip(colsToSkip)
-        .mapToDouble(Double::valueOf)
+        .mapToDouble(Double::parseDouble)
         .toArray();
 
     EnumMap<Imt, Double> imtImlMap = new EnumMap<>(Imt.class);
diff --git a/src/main/java/gov/usgs/earthquake/nshmp/HazardMaps.java b/src/main/java/gov/usgs/earthquake/nshmp/HazardMaps.java
index bb5733e2f..a93b41304 100644
--- a/src/main/java/gov/usgs/earthquake/nshmp/HazardMaps.java
+++ b/src/main/java/gov/usgs/earthquake/nshmp/HazardMaps.java
@@ -107,7 +107,7 @@ public class HazardMaps {
 
     double[] imls = header.subList(headerCount, header.size())
         .stream()
-        .mapToDouble(Double::valueOf)
+        .mapToDouble(Double::parseDouble)
         .toArray();
 
     StringBuilder mapHeader = new StringBuilder(siteStr);
@@ -176,7 +176,7 @@ public class HazardMaps {
       double[] rates = elements
           .stream()
           .skip(headerCount)
-          .mapToDouble(Double::valueOf)
+          .mapToDouble(Double::parseDouble)
           .toArray();
 
       for (double returnPeriod : returnPeriods) {
-- 
GitLab


From 7be6a472cf0f1f4981f3253e63ae10dc21411e43 Mon Sep 17 00:00:00 2001
From: Peter Powers <pmpowers@usgs.gov>
Date: Thu, 19 Jan 2023 14:30:48 -0700
Subject: [PATCH 5/5] build run edits

---
 docs/pages/Building-&-Running.md | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/docs/pages/Building-&-Running.md b/docs/pages/Building-&-Running.md
index 77c51d06c..421b8cdb2 100644
--- a/docs/pages/Building-&-Running.md
+++ b/docs/pages/Building-&-Running.md
@@ -38,17 +38,18 @@ To run *nshmp-haz* web services:
 
 ```bash
 ./gradlew run
+# or './gradlew run -t' to recompile and relaunch when code changes
 ```
 
 By default, when the web services start up, they load the 2018 NSHM for the conterminous U.S.
 To use a different model run the web services using Java and specify model path:
 
 ```bash
+./gradlew assemble
 java -jar build/libs/nshmp-haz.jar --model=path/to/model
 ```
 
-After startup, web services and documentation are now available at
-[http://localhost:8080/](http://localhost:8080/).
+After startup, web services and documentation are available at <http://localhost:8080/>.
 
 See the [Matlab](../../etc/matlab) directory for examples of how to call the web services. To
 run the ground motion model (GMM) web services, please use the
@@ -89,6 +90,32 @@ Disaggregations build on and output `HazardCalc` results along with other disagg
 files. Disaggregations also have some independent
 [configuration](./Calculation-Configuration.md#calculation-configuration-parameters) options.
 
+## Customizing Code
+
+Whereas *nshmp-haz* contains code to run command line applications and web services, model
+loading and hazard calculations are handled in the dependent library
+[*nshmp-lib*](https://code.usgs.gov/ghsc/nshmp/nshmp-lib). To use a local, modified version of
+*nshmp-lib*, set an environment variable `NSHMP_LIB_LOCAL=true` and *nshmp-haz*
+will look for *nshmp-lib* in a directory adjacent to *nshmp-haz*. If *nshmp-lib* is located
+somewhere else, modify the path specified in
+[`gradle/dependencies.gradle`](../../gradle/dependencies.gradle). When using a local version
+of *nshmp-lib*, first build the *nshmp-lib* project using `./gradlew fatJar` so that
+required dependencies are included.
+
+Summary of steps to check out and start running code for local development:
+
+```bash
+# --> Set a NSHMP_LIB_LOCAL=true environment variable on your system
+cd yourProjectDirectory
+git clone https://code.usgs.gov/ghsc/nshmp/nshmp-lib.git
+cd nshmp-lib
+./gradlew fatJar
+cd ..
+git clone https://code.usgs.gov/ghsc/nshmp/nshmp-ws.git
+cd nshmp-ws
+./gradlew run
+```
+
 ---
 
 ## Related Pages
-- 
GitLab