diff --git a/docs/.gitignore b/docs/.gitignore
index 8a900e9..d1adcde 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,9 +1,2 @@
 _book/
 venv-xosdocs
-xos-gui
-xos-tosca
-exampleservice
-kubernetes
-onos
-openstack
-simpleexampleservice
\ No newline at end of file
diff --git a/docs/Makefile b/docs/Makefile
index 0cd84bd..86248c0 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -10,7 +10,7 @@
 # use bash for pushd/popd, and to fail if commands within  a pipe fail
 SHELL = bash -o pipefail
 
-GENERATED_DOCS = 
+GENERATED_DOCS =
 
 LINT_STYLE ?= mdl_relaxed.rb
 
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 9580352..84860ec 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -19,10 +19,10 @@
     * [Tutorial](tutorials/basic_synchronizer.md)
     * [XOS Shell (xossh)](dev/xossh.md)
 * [Platform Services](platform.md)
-    * [Kubernetes](./external_content/kubernetes.md)
-    * [OpenStack](./external_content/openstack.md)
-    * [ONOS](./external_content/onos.md)
+    * [Kubernetes](kubernetes/kubernetes-service.md)
+    * [OpenStack](openstack/openstack-service.md)
+    * [ONOS](onos/README.md)
 * [Example Services](examples.md)
-    * [Simple Example Service](./external_content/simpleexampleservice.md)
-    * [Example Service](./external_content/exampleservice.md)
+    * [Simple Example Service](simpleexampleservice/simple-example-service.md)
+    * [Example Service](exampleservice/example-service.md)
 
diff --git a/docs/examples.md b/docs/examples.md
index 1d23cc7..a8893e7 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -1,7 +1,8 @@
 # Example Services
 
-This section describes two example services that have been on-boarded
-into XOS.
+This section describes two example services that have been on-boarded into XOS.
 
-* [Simple Example Service](./external_content/simpleexampleservice.md): Runs a web server in a Kubernetes-managed pod.
-* [Example Service](./external_content/exampleservice.md): Runs a web server in an OpenStack-managed VM.
+* [Simple Example Service](simpleexampleservice/simple-example-service.md):
+  Runs a web server in a Kubernetes-managed pod.
+* [Example Service](exampleservice/example-service.md): Runs a web server in an
+  OpenStack-managed VM.
diff --git a/docs/external_content/exampleservice.md b/docs/exampleservice/example-service.md
similarity index 100%
rename from docs/external_content/exampleservice.md
rename to docs/exampleservice/example-service.md
diff --git a/docs/external_content/kubernetes.md b/docs/kubernetes/kubernetes-service.md
similarity index 100%
rename from docs/external_content/kubernetes.md
rename to docs/kubernetes/kubernetes-service.md
diff --git a/docs/external_content/onos.md b/docs/onos/README.md
similarity index 100%
rename from docs/external_content/onos.md
rename to docs/onos/README.md
diff --git a/docs/external_content/openstack.md b/docs/openstack/openstack-service.md
similarity index 100%
rename from docs/external_content/openstack.md
rename to docs/openstack/openstack-service.md
diff --git a/docs/platform.md b/docs/platform.md
index 109b1b1..f342117 100644
--- a/docs/platform.md
+++ b/docs/platform.md
@@ -5,11 +5,11 @@
 Either or both can be integrated into an XOS-managed system,
 and like any other service, they have models and synchronizers.
 The only difference is that their models are part of the
-[XOS core](core-models.md) (e.g., Slices, Instances, Networks) rather
+[XOS core](core_models.md) (e.g., Slices, Instances, Networks) rather
 than service extensions. This section describes three example platform
 services in more detail:
 
-* [Kubernetes](./external_content/kubernetes.md)
-* [OpenStack](./external_content/openstack.md)
-* [ONOS](./external_content/onos.md)
+* [Kubernetes](kubernetes/kubernetes-service.md)
+* [OpenStack](openstack/openstack-service.md)
+* [ONOS](onos/README.md)
 
diff --git a/docs/security_policies.md b/docs/security_policies.md
index c028e47..e6ff0d4 100644
--- a/docs/security_policies.md
+++ b/docs/security_policies.md
@@ -59,5 +59,5 @@
 ```
 
 For more information about security policy definitions, read about
-[xproto and xosgenx](/xos/dev/xproto.md).
+[xproto and xosgenx](dev/xproto.md).
 
diff --git a/docs/external_content/simpleexampleservice.md b/docs/simpleexampleservice/simple-example-service.md
similarity index 100%
rename from docs/external_content/simpleexampleservice.md
rename to docs/simpleexampleservice/simple-example-service.md