diff --git a/docs/Makefile b/docs/Makefile
index 0edad84..e222f47 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -22,7 +22,7 @@
 	gitbook init
 	gitbook install
 
-test: linkcheck
+test: linkcheck lint
 
 linkcheck: build
 	linkchecker --check-extern -a _book/
@@ -38,7 +38,6 @@
 	ln -s ../../../orchestration/profiles/rcord/docs profiles/rcord
 	ln -s ../../../orchestration/profiles/ecord/docs profiles/ecord
 	ln -s ../../../orchestration/profiles/mcord/docs profiles/mcord
-	ln -s ../../../orchestration/profiles/opencloud/docs profiles/opencloud
 
 lint:
 	@echo "markdownlint(mdl) version: `mdl --version`"
@@ -47,7 +46,7 @@
 	@echo "---"
 	@cat mdlstyle.rb
 	@echo "---"
-	mdl -s mdlstyle.rb `find . ! -path "./_book/*" ! -path "./node_modules/*" ! -path "./cord-tester/modules/*" -name "*.md"`
+	mdl -s mdlstyle.rb `find -L . ! -path "./partials/*" ! -path "./_book/*" ! -path "./node_modules/*" ! -path "./cord-tester/modules/*" -name "*.md"`
 
 xos:
 	ln -s ../../orchestration/xos/docs xos
diff --git a/docs/cord_in_china.md b/docs/cord_in_china.md
index 7ae302e..5f73fb6 100644
--- a/docs/cord_in_china.md
+++ b/docs/cord_in_china.md
@@ -206,5 +206,5 @@
 to see emails from the rest of the community, send a blank email to
 
 `NAME_OF_THE_ML+subscribe@opencord.org`, for example
-[cord-dev+subscribe@opencord.org](cord-dev+subscribe@opencord.org).
+[cord-dev+subscribe@opencord.org](mailto:cord-dev+subscribe@opencord.org).
 
diff --git a/docs/getting_the_code.md b/docs/getting_the_code.md
index 70c68cd..e391f40 100644
--- a/docs/getting_the_code.md
+++ b/docs/getting_the_code.md
@@ -28,12 +28,7 @@
 The `cord` repositories are usually checked out to `~/cord` in most of our
 examples and deployments:
 
-```shell
-mkdir ~/cord && \
-cd ~/cord && \
-repo init -u https://gerrit.opencord.org/manifest -b {{ book.branch }} && \
-repo sync
-```
+{% include "/partials/repo-download.md" %}
 
 > NOTE: `-b` specifies the branch name. Development work goes on in `master,
 > and there are also specific stable branches such as `cord-4.0` that can be
diff --git a/docs/install.md b/docs/install.md
index 00844f6..6f11468 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -46,10 +46,7 @@
 `cord-bootstrap.sh` script to install these tools and check out the CORD source
 tree to `~/cord`.
 
-```shell
-curl -o ~/cord-bootstrap.sh https://raw.githubusercontent.com/opencord/cord/{{ book.branch }}/scripts/cord-bootstrap.sh
-chmod +x cord-bootstrap.sh
-```
+{% include "/partials/cord-bootstrap.md" %}
 
 > NOTE: Change the `master` path component in the URL to your desired version
 > branch (ex: `cord-5.0`) if required.
diff --git a/docs/install_physical.md b/docs/install_physical.md
index 590463d..a724a24 100644
--- a/docs/install_physical.md
+++ b/docs/install_physical.md
@@ -95,9 +95,9 @@
 * 3x Physical Servers: one to be used as head node, two to be used as compute
   nodes.
 
-    * Suggested Model: OCP Inspired&trade; QuantaGrid D51B-1U server. Each server is
-      configured with 2x Intel E5-2630 v4 10C 2.2GHz 85W, 64GB of RAM 2133MHz
-      DDR4, 2x 500GB HDD, and a 40 Gig adapter.
+    * Suggested Model: OCP Inspired&trade; QuantaGrid D51B-1U server. Each
+      server is configured with 2x Intel E5-2630 v4 10C 2.2GHz 85W, 64GB of RAM
+      2133MHz DDR4, 2x 500GB HDD, and a 40 Gig adapter.
 
     * Strongly Suggested NIC:
         * Intel Ethernet Converged Network Adapters XL710 10/40 GbE PCIe 3.0, x8
@@ -261,7 +261,7 @@
 
 #### Give "sudoer" permissions (no password)
 
-```
+```bash
 sudo adduser YOUR_USER_NAME sudo && \
 echo 'YOUR_USER_NAME ALL=(ALL) NOPASSWD:ALL' | sudo tee --append /etc/sudoers.d/90-cloud-init-users
 ```
diff --git a/docs/install_virtual.md b/docs/install_virtual.md
index 9ad4110..69e6994 100644
--- a/docs/install_virtual.md
+++ b/docs/install_virtual.md
@@ -374,9 +374,9 @@
 ### test-exampleservice
 
 This test builds on `test-vsg` by loading the *exampleservice* described in the
-[Developing for Cord:ExampleService](xos/example_service.md).  The purpose of
-the *exampleservice* is to demonstrate how new subscriber-facing services can
-be easily deployed to a CORD POD. This test performs the following steps:
+[ExampleService](xos/tutorials/example_service.md).  The purpose of the
+*exampleservice* is to demonstrate how new subscriber-facing services can be
+easily deployed to a CORD POD. This test performs the following steps:
 
 * On-boards *exampleservice* into the CORD POD
 * Creates an *exampleservice* tenant, which causes a VM to be created and
diff --git a/docs/kubernetes.md b/docs/kubernetes.md
index 4d88322..a6daa93 100644
--- a/docs/kubernetes.md
+++ b/docs/kubernetes.md
@@ -1,11 +1,25 @@
 # Using CORD on Kubernetes (Exeperimental)
 
-
 ## Podconfigs & Scenarios
 
-There are kubernetes specific scenarios, `controlkube` and `preppedkube`.
+There are currently two kubernetes specific scenarios, `controlkube` and `preppedkube`.
 
-## Commands
+### controlkube
+
+This is the "small" installation, and brings up 3 nodes with 2GB of ram each.
+It's designed for laptop or testing use.
+
+### preppedkube
+
+This is the "small" installation, and brings up 3 nodes with 16GB of ram each.
+It's designed for testing and use on physical hardware.
+
+## Building a Kubernetes enabled CORD pod
+
+Currently, virtual deployment with Vagrant is only supported on linux, with
+libvirt as a backend.
+
+## `make` targets
 
 Remove all kubespray related targets: `make clean-kubespray`
 
diff --git a/docs/mdlstyle.rb b/docs/mdlstyle.rb
index ce1c0a6..f738818 100644
--- a/docs/mdlstyle.rb
+++ b/docs/mdlstyle.rb
@@ -1,12 +1,15 @@
 # use all rules
 all
 
-# Intent lists with 4 spaces
+# Indent lists with 4 spaces
 rule 'MD007', :indent => 4
 
 # Don't enforce line length limitations within code blocks and tables
 rule 'MD013', :code_blocks => false, :tables => false
 
-# numbered lists should have the correct order
+# Numbered lists should have the correct order
 rule 'MD029', :style => "ordered"
 
+# Allow  ! and ? as trailing punctuation in headers
+rule 'MD026', :punctuation => '.,;:'
+
diff --git a/docs/operate/power_up.md b/docs/operate/power_up.md
index 7afd590..58b1b05 100644
--- a/docs/operate/power_up.md
+++ b/docs/operate/power_up.md
@@ -16,22 +16,24 @@
 ## Check the Head Node Services
 
 1. Verify that `mgmtbr` and `fabric` interfaces are up and have IP addresses
+
 2. Verify that MAAS UI is running and accessible:
+
     * **Physical POD:** `http://<head-node>/MAAS`
     * **CiaB:** `http://<ciab-server>:8080/MAAS`
 
-> **Troubleshooting: MAAS UI not available on CiaB.** If you are running a CiaB
-> and there is no webserver on port 8080, it might be necessary to refresh port
-> forwarding to the prod VM.  Run `ps ax|grep 8080` and look for an SSH command
-> (will look something like this):
+    > **Troubleshooting: MAAS UI not available on CiaB.** If you are running a CiaB
+    > and there is no webserver on port 8080, it might be necessary to refresh port
+    > forwarding to the prod VM.  Run `ps ax|grep 8080` and look for an SSH command
+    > (will look something like this):
 
-```shell
-31353 pts/5    S      0:00 ssh -o User=vagrant -o Port=22 -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -o PasswordAuthentication=no -o ForwardX11=no -o IdentityFile="/users/acb/cord/build/scenarios/cord/.vagrant/machines/head1/libvirt/private_key" -L *:8080:192.168.121.14:80 -N 192.168.121.14
-```
+    ```shell
+    31353 pts/5    S      0:00 ssh -o User=vagrant -o Port=22 -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -o PasswordAuthentication=no -o ForwardX11=no -o IdentityFile="/users/acb/cord/build/scenarios/cord/.vagrant/machines/head1/libvirt/private_key" -L *:8080:192.168.121.14:80 -N 192.168.121.14
+    ```
 
-> A workaround is to kill this process, and then copy and paste the command
-> above into another window on the CiaB server to set up a new SSH port
-> forwarding connection.
+    > A workaround is to kill this process, and then copy and paste the command
+    > above into another window on the CiaB server to set up a new SSH port
+    > forwarding connection.
 
 3. Verify that the following Docker containers are running: mavenrepo, switchq,
    automation, provisioner, generator, harvester, storage, allocator, registry
@@ -42,14 +44,15 @@
 5. Run: `source /opt/cord_profile/admin-openrc.sh`
 
 6. Verify that the following OpenStack commands work:
+
     * `$ keystone user-list`
     * `$ nova list --all-tenants`
     * `$ neutron net-list`
 
-> **Troubleshooting: OpenStack commands give SSL error.** Sometimes Keystone
-> starts up in a strange state and OpenStack commands will fail with various
-> SSL errors.  To fix this, it is often sufficient to run: `ssh ubuntu@keystone
-> sudo service apache2 restart`
+    > **Troubleshooting: OpenStack commands give SSL error.** Sometimes Keystone
+    > starts up in a strange state and OpenStack commands will fail with various
+    > SSL errors.  To fix this, it is often sufficient to run: `ssh ubuntu@keystone
+    > sudo service apache2 restart`
 
 ## Power on Leaf and Spine Switches
 
@@ -78,7 +81,7 @@
 2. Run: `source /opt/cord_profile/admin-openrc.sh`
 3. Verify that nova service-list shows the compute node as “up”.
 
-> It may take a few minutes until the node's status is updated in Nova.
+    > It may take a few minutes until the node's status is updated in Nova.
 
 4. Verify that you can log into the compute nodes from the head node as the
    ubuntu user
diff --git a/docs/partials/cord-bootstrap.md b/docs/partials/cord-bootstrap.md
new file mode 100644
index 0000000..f0a95e2
--- /dev/null
+++ b/docs/partials/cord-bootstrap.md
@@ -0,0 +1,2 @@
+<pre><code class="lang-sh">curl -o ~/cord-bootstrap.sh https://raw.githubusercontent.com/opencord/cord/{{ book.branch }}/scripts/cord-bootstrap.sh
+chmod +x cord-bootstrap.sh</code></pre>
diff --git a/docs/partials/repo-download.md b/docs/partials/repo-download.md
new file mode 100644
index 0000000..3b5c124
--- /dev/null
+++ b/docs/partials/repo-download.md
@@ -0,0 +1,4 @@
+<pre><code class="lang-sh">mkdir ~/cord && \
+cd ~/cord && \
+repo init -u https://gerrit.opencord.org/manifest -b {{ book.branch }} && \
+repo sync</code></pre>
diff --git a/docs/quickstarts.md b/docs/quickstarts.md
index bc3bdae..3122dcb 100644
--- a/docs/quickstarts.md
+++ b/docs/quickstarts.md
@@ -11,11 +11,7 @@
 Virtual pod, you can use the
 [cord-bootstrap.sh](install.html#cord-bootstrapsh-script) script:
 
-```shell
-curl -o ~/cord-bootstrap.sh https://raw.githubusercontent.com/opencord/cord/master/scripts/cord-bootstrap.sh
-chmod +x cord-bootstrap.sh
-./cord-bootstrap.sh -v
-```
+{% include "/partials/cord-bootstrap.md" %}
 
 > NOTE: Change the `master` path component in the URL to your desired version
 > branch (ex: `cord-5.0`) if required.
@@ -29,6 +25,7 @@
 system, run the following commands:
 
 ```shell
+./cord-bootstrap.sh -v
 cd ~/cord/build && \
 make PODCONFIG=rcord-virtual.yml config && \
 make -j4 build |& tee ~/build.out && \