diff --git a/src/README.md b/src/README.md
index 8031387..8c60315 100644
--- a/src/README.md
+++ b/src/README.md
@@ -37,7 +37,7 @@ Use this charm with the Keystone charm, running with preferred-api-version=3:
 
 In a bundle:
 
-```
+```yaml
     applications:
     # ...
       keystone-saml-mellon:
@@ -133,16 +133,16 @@ the post-deployment configuration steps. For example https://samltest.id/saml/id
 Get the idP's metadata XML. This will be the resource file for idp-metdata.xml.
 The XML will be unique for each idP. See example [idP metadata](https://samltest.id/saml/idp).
 The XML must be generated by your idP rather than
-attempting to create this document on your own. 
+attempting to create this document on your own.
 
 Generate a certificate key pair for keystone as a Service Provider (SP). See
-openssl document ion on how to. This certificate key pair will not be validated
+openssl documentation on how to. This certificate key pair will not be validated
 so it may or may not be signed by your certificate authority.
-The key PEM file is the resource file for sp-private-key.pem. The certificate
+The key PEM file is the resource file for `sp-private-key.pem`. The certificate
 PEM data will be placed in an XML document and will become the
-sp-signing-keyinfo.xml resource file.
+`sp-signing-keyinfo.xml` resource file.
 
-```
+```xml
 <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
     <ds:X509Data>
         <ds:X509Certificate>
@@ -158,28 +158,28 @@ sp-signing-keyinfo.xml resource file.
 ```
 
 Set the protocol. This must match the protocol used in the post-deployment
-configuration steps. We recommend the protocol "mapped."
+configuration steps. We recommend the protocol "mapped".
 
-  juju config keystone-saml-mellon protocol-name=mapped
+    juju config keystone-saml-mellon protocol-name=mapped
 
 Determine and configure the NameID SAML specification(s). This is the format
 for the user identification you expect to receive from the idP. Federated users
 generated in the keystone database will use this NameID as the uid.
 
- juju config keystone-saml-mellon nameid-formats="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
+    juju config keystone-saml-mellon nameid-formats="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
 
 If proxies are invoked at any point between the idP and keystone as SP set
 subject-confirmation-data-address-check to false.
 
- juju config keystone-saml-mellon subject-confirmation-data-address-check=False
+    juju config keystone-saml-mellon subject-confirmation-data-address-check=false
 
 Attach resources
 
- juju attach-resource keystone-saml-mellon idp-metadata=./idp-metadata.xml sp-private-key=./sp-private-key.pem. sp-signing-keyinfo=./sp-signing-keyinfo.xml
+    juju attach-resource keystone-saml-mellon idp-metadata=./idp-metadata.xml sp-private-key=./sp-private-key.pem. sp-signing-keyinfo=./sp-signing-keyinfo.xml
 
 Get keystones SP metadata XML and exchange it with your idP
 
- juju run-action keystone-saml-mellon/0 get-sp-metadata
+    juju run-action keystone-saml-mellon/0 get-sp-metadata --wait
 
 # Post-deployment Configuration
 
@@ -209,66 +209,72 @@ following is a simple example. Constraints can be added on the remote side. For
 example group membership.
 See [mapping documentation](https://docs.openstack.org/keystone/latest/admin/federation/mapping_combinations.html) upstream.
 
-```
-    openstack domain create federated_domain
-    openstack group create federated_users --domain federated_domain
-    # Get the federated_users group id and assign the role Member
-    GROUP_ID=$(openstack group show federated_users --domain federated_domain | grep -v domain_id | grep id |awk '{print $4}')
-    openstack role add --group ${GROUP_ID} --domain federated_domain Member
+```bash
+openstack domain create federated_domain
+openstack group create federated_users --domain federated_domain
+# Get the federated_users group id and assign the role Member
+GROUP_ID=$(openstack group show federated_users --domain federated_domain | grep -v domain_id | grep id |awk '{print $4}')
+openstack role add --group ${GROUP_ID} --domain federated_domain Member
 
-    # Use the URL for your idP's metadata for remote-id. The name can be
-    # arbitrary.
-    openstack identity provider create --remote-id https://samltest.id/saml/idp --domain federated_domain samltest 
+# Use the URL for your idP's metadata for remote-id. The name can be
+# arbitrary.
+openstack identity provider create --remote-id https://samltest.id/saml/idp --domain federated_domain samltest
 
-    # Get the federated_domain id and add it to the rules.json map
-    DOMAIN_ID=$(openstack domain show federated_domain |grep id |awk '{print $4}')
-    cat > rules.json <<EOF
-    [{
-            "local": [
-                {
-                    "user": {
-                        "name": "{0}"
+# Get the federated_domain id and add it to the rules.json map
+DOMAIN_ID=$(openstack domain show federated_domain |grep id |awk '{print $4}')
+cat > rules.json <<EOF
+[{
+        "local": [
+            {
+                "user": {
+                    "name": "{0}"
+                },
+                "group": {
+                    "domain": {
+                        "id": "${DOMAIN_ID}"
                     },
-                    "group": {
-                        "domain": {
-                            "id": "${DOMAIN_ID}"
-                        },
-                        "name": "federated_users"
-                    },
-                    "projects": [
-                    {
-                        "name": "{0}_project",
-                        "roles": [
-                                     {
-                                         "name": "Member"
-                                     }
-                                 ]
-                    }
-                    ]
-               }
-            ],
-            "remote": [
+                    "name": "federated_users"
+                },
+                "projects": [
                 {
-                    "type": "MELLON_NAME_ID"
+                    "name": "{0}_project",
+                    "roles": [
+                                 {
+                                     "name": "Member"
+                                 }
+                             ]
                 }
-            ]
-    }]
-    EOF
+                ]
+           }
+        ],
+        "remote": [
+            {
+                "type": "MELLON_NAME_ID"
+            }
+        ]
+}]
+EOF
 
-    # Use the rules.json created above.
-    openstack mapping create --rules rules.json samltest_mapping
-    # The name should be mapped or saml here and must match the configuration
-    # setting protocol-name. We recommend using "mapped"
-    openstack federation protocol create mapped --mapping samltest_mapping --identity-provider samltest
-    # list related projects
-    openstack federation project list
-    # Note and auto generated domain has been created. This is where auto
-    # generated users and projects will be created.
-    openstack domain list
+# Use the rules.json created above.
+openstack mapping create --rules rules.json samltest_mapping
+# The name should be mapped or saml here and must match the configuration
+# setting protocol-name. We recommend using "mapped"
+openstack federation protocol create mapped --mapping samltest_mapping --identity-provider samltest
+# list related projects
+openstack federation project list
+# Note and auto generated domain has been created. This is where auto
+# generated users and projects will be created.
+openstack domain list
 ```
 
 # Bugs
 
-Please report bugs on [Launchpad](https://bugs.launchpad.net/charm-keystone-saml-mellon/+filebug).
+Please report bugs on [Launchpad][lp-bugs-charm-keystone-saml-mellon].
 
-For general questions please refer to the OpenStack [Charm Guide](https://docs.openstack.org/charm-guide/latest/).
+For general charm questions refer to the [OpenStack Charm Guide][cg].
+
+<!-- LINKS -->
+
+[cg]: https://docs.openstack.org/charm-guide
+[cdg]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide
+[lp-bugs-charm-keystone-saml-mellon]: https://bugs.launchpad.net/charm-keystone-saml-mellon/+filebug