diff --git a/docs/ItaniumMangleAbiTags.rst b/docs/ItaniumMangleAbiTags.rst
index 6d50acad4b64c2ef16c698741a455209324802a5..2d65031b70e47a7fa78db1ab63715125012ddde8 100644
--- a/docs/ItaniumMangleAbiTags.rst
+++ b/docs/ItaniumMangleAbiTags.rst
@@ -33,15 +33,18 @@ the same <substitution> the <unqualified-name> is.
 
 They are mangled as:
 
+.. code-block:: none
+
     <abi-tags> ::= <abi-tag>*   # sort by name
     <abi-tag> ::= B <tag source-name>
 
 Example:
 
+.. code-block:: c++
+
     __attribute__((abi_tag("test")))
     void Func();
-
-    gets mangled as: _Z4FuncB4testv (prettified as `Func[abi:test]()`)
+    // gets mangled as: _Z4FuncB4testv (prettified as `Func[abi:test]()`)
 
 Active tags
 ===========
@@ -52,6 +55,8 @@ enum), the explicit tags are the active tags.
 For variables and functions, the active tags are the explicit tags plus any
 "required tags" which are not in the "available tags" set:
 
+.. code-block:: none
+
     derived-tags := (required-tags - available-tags)
     active-tags := explicit-tags + derived-tags
 
@@ -68,15 +73,16 @@ Otherwise the function requires any implicit or explicit tag used in the name
 for the return type.
 
 Example:
+
+.. code-block:: c++
+
     namespace A {
       inline namespace B __attribute__((abi_tag)) {
         struct C { int x; };
       }
     }
 
-    A::C foo();
-
-    gets mangled as: _Z3fooB1Bv (prettified as `foo[abi:B]()`)
+    A::C foo(); // gets mangled as: _Z3fooB1Bv (prettified as `foo[abi:B]()`)
 
 Required tags for a variable
 ============================
@@ -99,4 +105,3 @@ in the type of a cast operator) are NOT available.
 Example: a cast operator to std::string (which is
 std::__cxx11::basic_string<...>) will use 'cxx11' as an active tag, as it is
 required from the return type `std::string` but not available.
-
diff --git a/docs/index.rst b/docs/index.rst
index 81a15b8e188771975435bbc5e09473565e3af921..6028fb8ec2f10cca9ac05767a12d728d13131ee0 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -76,6 +76,7 @@ Design Documents
    DriverInternals
    PTHInternals
    PCHInternals
+   ItaniumMangleAbiTags
 
 
 Indices and tables