diff --git a/_build_cfg.yml b/_build_cfg.yml
index e41e48dddcd7..c1a54bc514c4 100644
--- a/_build_cfg.yml
+++ b/_build_cfg.yml
@@ -186,6 +186,8 @@ Topics:
     File: integrating_external_services
   - Name: Projects
     File: projects
+  - Name: Secrets
+    File: secrets
   - Name: Image Pull Secrets
     File: image_pull_secrets
   - Name: Resource Limits
diff --git a/dev_guide/secrets.adoc b/dev_guide/secrets.adoc
index 0728be36f4dd..d538cf00aa18 100644
--- a/dev_guide/secrets.adoc
+++ b/dev_guide/secrets.adoc
@@ -31,10 +31,11 @@ provides an overview on how developers can use them.
     }
 }
 ----
-<1> The `data` field must match the keys in the the "DNS_SUBDOMAIN" value in `_docs/design/identifiers.md_`.
+<1> The `data` field must match the keys in the the "DNS_SUBDOMAIN" value in
+`_docs/design/identifiers.md_`.
 ====
 
-== Properties of secrets
+== Properties of Secrets
 Key properties include:
 
 - Secret data can be referenced independently from its definition.
@@ -63,11 +64,13 @@ Therefore, if a secret is updated at the same time as pods are starting,
 then the version of the secret will be used for the pod will not be defined.
 
 [NOTE]
+====
 Currently, it is not possible to check the resource version of a secret object
 that was used when a pod was created. It is planned that pods will report this
 information, so that a controller could restart ones using a old
-`resourceVersion`. In the interim, do not update the data of existing secrets,
+`*resourceVersion*`. In the interim, do not update the data of existing secrets,
 but create new ones with distinct names.
+====
 
 == Creating and Using Secrets
 When creating secrets:
@@ -87,14 +90,15 @@ $ oc create -f secret.json
 ====
 
 === Secrets in Volumes
+See link:#examples[Examples].
 
 === Image Pull Secrets
-See link:dev_guide/image_pull_secrets.html[the image pull secrets] documentation
-for more information.
+See the link:image_pull_secrets.html[Image Pull Secrets] topic for more
+information.
 
 == Restrictions
 Secret volume sources are validated to ensure that the specified object
-reference points to a `Secret` object. Therefore, a secret needs to be created
+reference points to a `*Secret*` object. Therefore, a secret needs to be created
 before the pods that depend on it.
 
 Secret API objects reside in a namespace. They can only be referenced by pods in
@@ -108,15 +112,15 @@ Currently, when mounting a secret, the service account for a pod must have the
 secret in the list of mountable secrets. If a secret is in a template pods will
 be rejected until the pod's service account is updated.
 
-=== Secret data keys
-Secret keys have to be in a DNS subdomain.
+=== Secret Data Keys
+Secret keys must be in a DNS subdomain.
 
 == Examples
 
-=== Example: Pod consuming secret data in volume
-The following is an example yaml of a pod comsuming data in a volume:
-
+.YAML of a Pod Consuming Data in a Volume
 ====
+
+[source,yaml]
 ----
 apiVersion: v1
 kind: Pod