diff --git a/content/patterns/writing/references.md b/content/patterns/writing/references.md
index 4550a84..f5b2253 100644
--- a/content/patterns/writing/references.md
+++ b/content/patterns/writing/references.md
@@ -46,6 +46,10 @@ Here's the more verbose output:
 
 {{% wcag include="2.1.1, 4.1.2" descriptions="true" %}}
 
+{{% note %}}
+Both omitting the `descriptions` attribute and including it with a "false" value will omit descriptions. If it is included it _must_ have a value. A boolean attribute will break the output.
+{{% /note %}}
+
 ## Inclusive Design Principle references
 
 Some inclusive design concepts are not reducible to success or fail criteria. This is why The Paciello Group wrote the [Inclusive Design Principles](http://inclusivedesignprinciples.org/). These can be listed by name.
diff --git a/docs/patterns/writing/references/index.html b/docs/patterns/writing/references/index.html
index e2a7d11..e714f4e 100644
--- a/docs/patterns/writing/references/index.html
+++ b/docs/patterns/writing/references/index.html
@@ -786,14 +786,25 @@ I can reference the {{% pattern "Notes & warnings" %}} pattern here.
 </ul>
 
 
+<aside aria-label="note" class="note">
+  <div>
+    <svg class="sign" aria-hidden="true" viewBox="0 0 41.667306 41.66729" focusable="false">
+      <use xlink:href="#info"></use>
+    </svg>
+    <p>Both omitting the <code>descriptions</code> attribute and including it with a &ldquo;false&rdquo; value will omit descriptions. If it is included it <em>must</em> have a value. A boolean attribute will break the output.</p>
+
+  </div>
+</aside>
+
+
 <h2 id="inclusive-design-principle-references">Inclusive Design Principle references</h2>
 
 <p>Some inclusive design concepts are not reducible to success or fail criteria. This is why The Paciello Group wrote the <a href="http://inclusivedesignprinciples.org/">Inclusive Design Principles</a>. These can be listed by name.</p>
 
-<p><pre class=""><code  data-codeblock-shortcode>
+<pre class=""><code  data-codeblock-shortcode>
 &#x7b;{% principles include="Add value, Be consistent" descriptions="true" %}}
 </code></pre>
-</p>
+
 
 <p>Here&rsquo;s the output with <code>descriptions=&quot;true&quot;</code>:</p>
 
diff --git a/docs/print-version/index.html b/docs/print-version/index.html
index 7366bce..2eea0d5 100644
--- a/docs/print-version/index.html
+++ b/docs/print-version/index.html
@@ -1402,14 +1402,25 @@ I can reference the &#x7b;{% pattern "Notes & warnings" %}} pattern here.
 </ul>
 
 
+<aside aria-label="note" class="note">
+  <div>
+    <svg class="sign" aria-hidden="true" viewBox="0 0 41.667306 41.66729" focusable="false">
+      <use xlink:href="#info"></use>
+    </svg>
+    <p>Both omitting the <code>descriptions</code> attribute and including it with a &ldquo;false&rdquo; value will omit descriptions. If it is included it <em>must</em> have a value. A boolean attribute will break the output.</p>
+
+  </div>
+</aside>
+
+
 <h2 id="inclusive-design-principle-references">Inclusive Design Principle references</h2>
 
 <p>Some inclusive design concepts are not reducible to success or fail criteria. This is why The Paciello Group wrote the <a href="http://inclusivedesignprinciples.org/">Inclusive Design Principles</a>. These can be listed by name.</p>
 
-<p><pre class=""><code  data-codeblock-shortcode>
+<pre class=""><code  data-codeblock-shortcode>
 &#x7b;{% principles include="Add value, Be consistent" descriptions="true" %}}
 </code></pre>
-</p>
+
 
 <p>Here&rsquo;s the output with <code>descriptions=&quot;true&quot;</code>:</p>
 
diff --git a/docs/service-worker.js b/docs/service-worker.js
index cb350c4..280f0d1 100644
--- a/docs/service-worker.js
+++ b/docs/service-worker.js
@@ -37,7 +37,7 @@
 /* eslint-disable indent, no-unused-vars, no-multiple-empty-lines, max-nested-callbacks, space-before-function-paren, quotes, comma-spacing */
 'use strict';
 
-var precacheConfig = [["404.html","64c7057a5dcac7a561798f6f87b412ff"],["browserconfig.xml","67c3113b1574fecc6015d56d774e1d38"],["categories/index.xml","1c183b48cab635f689386c900b9dc4aa"],["css/fonts/miriamlibre-bold.woff","96496f6f06535d25b3bcba876917ca35"],["css/fonts/miriamlibre-bold.woff2","668defa44d9a74dd709ce0c826a5eb11"],["css/images/arrow_effect.svg","1434d178461f70c16b77acb4bdbc51e3"],["css/images/icon-tick.svg","35d4d4728ea80d254508b2bca4109d70"],["css/images/stripe.svg","fa3f32a026b6a1bb04ee98d963432e15"],["css/prism.css","004029c8c70ed2bbaa5d9debcf14f8c7"],["css/styles.css","e1fbb227e992da50deafd3728d406f1a"],["images/android-icon-144x144.png","43e1f47f182b13d0dee15f510213e928"],["images/android-icon-192x192.png","4c07782e52e0ab714074e6d3d69dc3ec"],["images/android-icon-36x36.png","3b2cd8c925a66bf84c89b68bb30e5f62"],["images/android-icon-48x48.png","45dc386eea1d8a46216a8b6de9b156c6"],["images/android-icon-512x512.png","42d6b28cc7eb41810a5392c81368340a"],["images/android-icon-72x72.png","b04c64637efed2b04fa900ddfcbfe75d"],["images/android-icon-96x96.png","bd9c126a4d6baf7ce442122ce0e89e11"],["images/apple-icon-precomposed.png","478755b1c3e0d2c8aea975033cff9ac8"],["images/apple-icon.png","478755b1c3e0d2c8aea975033cff9ac8"],["images/apple-touch-icon-114x114.png","95804b2192b0cea406b54cb31345c47d"],["images/apple-touch-icon-120x120.png","b5da0625c9e876bdf9768875f7dd9cca"],["images/apple-touch-icon-144x144.png","976151c9ecd72311dc6024917292209d"],["images/apple-touch-icon-152x152.png","8bd6a2e592c1c8463b5205ba8436227e"],["images/apple-touch-icon-180x180.png","56a93f4271dea903196794095e9f9ccc"],["images/apple-touch-icon-57x57.png","977183ab3bfb98da8d79e025f1cb4946"],["images/apple-touch-icon-60x60.png","55e9e05103a9b472a52f4c572a73b2b2"],["images/apple-touch-icon-72x72.png","1ef87a2887baab846f2501beb27445ee"],["images/apple-touch-icon-76x76.png","769826cd7526df4db7f4ba1a820158bd"],["images/bad_design_system.png","9c0e87a34e7d842b0e2831dc947249aa"],["images/browser-chrome-android.svg","3100b2a9c5f0e34982c717fc2aa46d73"],["images/browser-chrome.svg","fa39b4be6727525330e928f582fbe80a"],["images/browser-edge.svg","9e8265ab8f6a701587a4271dd3aa6a73"],["images/browser-firefox-android.svg","452df7b9e83c70a07e8e03b4e8dab9c4"],["images/browser-firefox.svg","d3093eda664be3d0cc6d791e1386420f"],["images/browser-ie.svg","13e192cf2b3fe17e7049a49b7d085caa"],["images/browser-opera.svg","95d65630c9f7deef6a3098af8f5baf9f"],["images/browser-safari-ios.svg","f729e629ec998ec40d313495d7257741"],["images/browser-safari.svg","523ee9491f5a937b8975f4d23aa77f62"],["images/favicon-16x16.png","7a99c20d6c00babddd26d03607b8721d"],["images/favicon-32x32.png","129881474a1bf130027bff7a1e89febd"],["images/favicon-96x96.png","bd9c126a4d6baf7ce442122ce0e89e11"],["images/favicon.ico","81c46feedbfcc6c6dc9495e4fd5adfad"],["images/icon-info.svg","53a6c555ce41f818556c71ab0dfc533b"],["images/icon-tag.svg","f067bbbc072941b2a0335679300bfc6c"],["images/icon-warning.svg","2a4322abbee9aed694fadb50e98a1f61"],["images/logo.svg","50293a256b796b9a737f1969d511a98e"],["images/ms-icon-144x144.png","43e1f47f182b13d0dee15f510213e928"],["images/ms-icon-150x150.png","e73370837ab9060772a18d62aaacd0f0"],["images/ms-icon-310x310.png","8a7143516b929702e3309bb537a99c5c"],["images/ms-icon-70x70.png","d7c6e7368733d53b5f979546d5aa4fe9"],["images/open_in_desktop.png","e899d6679b011aa7b0e783683d90d99b"],["images/samsung_homescreen.png","5ef40e64a18f966ce5c9084a024256db"],["images/serve_from_docs.png","15ae9eac3737a21593ebe00a9312bf9e"],["index.html","ed6f299f3ada8884cde3d1aa8f087999"],["index.xml","57a3c0aa0932b3634b447ccd63d44254"],["js/dom-scripts.js","1d87ba44d730c37fae139d4ac47b118a"],["js/prism.js","0c1fb8d3a69ee7c91dbf0f361ded7763"],["js/service-worker-registration.js","d60f01dc1393cbaaf4f7435339074d5e"],["manifest.json","47399fd703e572a010a718a351c37b03"],["patterns/coding/code-blocks/index.html","ef9787d50a223a865686b709fbb56b35"],["patterns/coding/color-palettes/index.html","dbd0b5ec8d5c920a5b3e6a9d16dfe4ea"],["patterns/coding/command-line/index.html","08a2bede6d49ed0c0966c7251f025349"],["patterns/coding/demo-embedding/index.html","edb617ff5677a855240b29e78e7cfe12"],["patterns/coding/file-trees/index.html","2018ee28e6741dd2b039c96a9cb1cf6f"],["patterns/coding/index.html","fa95d165746f7006400f5a6289a24bca"],["patterns/coding/index.xml","9103e9b80e3ea47df0759c7646b4b174"],["patterns/coding/tested/index.html","885fad18412f4fb6b93bc3d5f9245c5f"],["patterns/coding/writing-inline-demos/index.html","22a4e8166c3fdb14778174ede26ba127"],["patterns/index.html","3088821ec9ee3424fe0ce7826e8b663d"],["patterns/index.xml","276f7358cc6c122ee8b38ec4f86f116f"],["patterns/installation/index.html","4b5b97dba40cb1131b22536e0f40c526"],["patterns/media/including-images/index.html","5501f1b162de829ebba408fe93e2e871"],["patterns/media/including-videos/index.html","68c1b03ce92b5d78be46b312670ab49f"],["patterns/media/index.html","c2e39c5f91dbf5ae238b53881ded734a"],["patterns/media/index.xml","69e133cec08e19eeb33cb005e90590e3"],["patterns/printing/index.html","21cbb13255f6606783e35781d05b3cd0"],["patterns/serving/index.html","74bcbf568897a307e7d156c2679cd8b5"],["patterns/setup/index.html","f64759b069335c7e868c50505756f161"],["patterns/updating/index.html","e6f19a2d952417a9ffa353489f13f1c7"],["patterns/writing/expandable-sections/index.html","56dff4c7ee6bc6cc75805da0471fd67f"],["patterns/writing/index.html","6b876040b71134ead191ec7ea8b222dc"],["patterns/writing/index.xml","53aea727e5ea1133e83cd6a859115e7e"],["patterns/writing/markdown-and-metadata/index.html","2f8a7b540428740bcf3c6f76fe575eb7"],["patterns/writing/notes-and-warnings/index.html","f4d3ae3e5cf35b67b2834b04c0e5a305"],["patterns/writing/project-structure/index.html","6582a714b06c27a5f11fce7675b740e8"],["patterns/writing/references/index.html","fbf5694633516f2453f504a16360bf32"],["patterns/writing/snippets/index.html","defd3b88e44cef79a0ad246aab417cad"],["patterns/writing/tables-of-contents/index.html","2aef3ef8756d51908cd971115e076513"],["print-version/index.html","7028697209bc6e20dcdd2aafbe7e4fa7"],["sitemap.xml","e3f27a45b9955c8ee5f7f72517c65417"],["tags/index.xml","7445f2e8ccc722d44e7533263233d2df"],["tags/markdown/index.html","d6d084b6803ba11bfff11a789689859a"],["tags/markdown/index.xml","5387a8d0317e6b6641e0803ac2f5af3c"],["tags/metadata/index.html","e8c8ede1b409776b684986065f8ef511"],["tags/metadata/index.xml","098f151053be1a17654318a88433154b"]];
+var precacheConfig = [["404.html","64c7057a5dcac7a561798f6f87b412ff"],["browserconfig.xml","67c3113b1574fecc6015d56d774e1d38"],["categories/index.xml","1c183b48cab635f689386c900b9dc4aa"],["css/fonts/miriamlibre-bold.woff","96496f6f06535d25b3bcba876917ca35"],["css/fonts/miriamlibre-bold.woff2","668defa44d9a74dd709ce0c826a5eb11"],["css/images/arrow_effect.svg","1434d178461f70c16b77acb4bdbc51e3"],["css/images/icon-tick.svg","35d4d4728ea80d254508b2bca4109d70"],["css/images/stripe.svg","fa3f32a026b6a1bb04ee98d963432e15"],["css/prism.css","004029c8c70ed2bbaa5d9debcf14f8c7"],["css/styles.css","e1fbb227e992da50deafd3728d406f1a"],["images/android-icon-144x144.png","43e1f47f182b13d0dee15f510213e928"],["images/android-icon-192x192.png","4c07782e52e0ab714074e6d3d69dc3ec"],["images/android-icon-36x36.png","3b2cd8c925a66bf84c89b68bb30e5f62"],["images/android-icon-48x48.png","45dc386eea1d8a46216a8b6de9b156c6"],["images/android-icon-512x512.png","42d6b28cc7eb41810a5392c81368340a"],["images/android-icon-72x72.png","b04c64637efed2b04fa900ddfcbfe75d"],["images/android-icon-96x96.png","bd9c126a4d6baf7ce442122ce0e89e11"],["images/apple-icon-precomposed.png","478755b1c3e0d2c8aea975033cff9ac8"],["images/apple-icon.png","478755b1c3e0d2c8aea975033cff9ac8"],["images/apple-touch-icon-114x114.png","95804b2192b0cea406b54cb31345c47d"],["images/apple-touch-icon-120x120.png","b5da0625c9e876bdf9768875f7dd9cca"],["images/apple-touch-icon-144x144.png","976151c9ecd72311dc6024917292209d"],["images/apple-touch-icon-152x152.png","8bd6a2e592c1c8463b5205ba8436227e"],["images/apple-touch-icon-180x180.png","56a93f4271dea903196794095e9f9ccc"],["images/apple-touch-icon-57x57.png","977183ab3bfb98da8d79e025f1cb4946"],["images/apple-touch-icon-60x60.png","55e9e05103a9b472a52f4c572a73b2b2"],["images/apple-touch-icon-72x72.png","1ef87a2887baab846f2501beb27445ee"],["images/apple-touch-icon-76x76.png","769826cd7526df4db7f4ba1a820158bd"],["images/bad_design_system.png","9c0e87a34e7d842b0e2831dc947249aa"],["images/browser-chrome-android.svg","3100b2a9c5f0e34982c717fc2aa46d73"],["images/browser-chrome.svg","fa39b4be6727525330e928f582fbe80a"],["images/browser-edge.svg","9e8265ab8f6a701587a4271dd3aa6a73"],["images/browser-firefox-android.svg","452df7b9e83c70a07e8e03b4e8dab9c4"],["images/browser-firefox.svg","d3093eda664be3d0cc6d791e1386420f"],["images/browser-ie.svg","13e192cf2b3fe17e7049a49b7d085caa"],["images/browser-opera.svg","95d65630c9f7deef6a3098af8f5baf9f"],["images/browser-safari-ios.svg","f729e629ec998ec40d313495d7257741"],["images/browser-safari.svg","523ee9491f5a937b8975f4d23aa77f62"],["images/favicon-16x16.png","7a99c20d6c00babddd26d03607b8721d"],["images/favicon-32x32.png","129881474a1bf130027bff7a1e89febd"],["images/favicon-96x96.png","bd9c126a4d6baf7ce442122ce0e89e11"],["images/favicon.ico","81c46feedbfcc6c6dc9495e4fd5adfad"],["images/icon-info.svg","53a6c555ce41f818556c71ab0dfc533b"],["images/icon-tag.svg","f067bbbc072941b2a0335679300bfc6c"],["images/icon-warning.svg","2a4322abbee9aed694fadb50e98a1f61"],["images/logo.svg","50293a256b796b9a737f1969d511a98e"],["images/ms-icon-144x144.png","43e1f47f182b13d0dee15f510213e928"],["images/ms-icon-150x150.png","e73370837ab9060772a18d62aaacd0f0"],["images/ms-icon-310x310.png","8a7143516b929702e3309bb537a99c5c"],["images/ms-icon-70x70.png","d7c6e7368733d53b5f979546d5aa4fe9"],["images/open_in_desktop.png","e899d6679b011aa7b0e783683d90d99b"],["images/samsung_homescreen.png","5ef40e64a18f966ce5c9084a024256db"],["images/serve_from_docs.png","15ae9eac3737a21593ebe00a9312bf9e"],["index.html","ed6f299f3ada8884cde3d1aa8f087999"],["index.xml","57a3c0aa0932b3634b447ccd63d44254"],["js/dom-scripts.js","1d87ba44d730c37fae139d4ac47b118a"],["js/prism.js","0c1fb8d3a69ee7c91dbf0f361ded7763"],["js/service-worker-registration.js","d60f01dc1393cbaaf4f7435339074d5e"],["manifest.json","47399fd703e572a010a718a351c37b03"],["patterns/coding/code-blocks/index.html","ef9787d50a223a865686b709fbb56b35"],["patterns/coding/color-palettes/index.html","dbd0b5ec8d5c920a5b3e6a9d16dfe4ea"],["patterns/coding/command-line/index.html","08a2bede6d49ed0c0966c7251f025349"],["patterns/coding/demo-embedding/index.html","edb617ff5677a855240b29e78e7cfe12"],["patterns/coding/file-trees/index.html","2018ee28e6741dd2b039c96a9cb1cf6f"],["patterns/coding/index.html","fa95d165746f7006400f5a6289a24bca"],["patterns/coding/index.xml","9103e9b80e3ea47df0759c7646b4b174"],["patterns/coding/tested/index.html","885fad18412f4fb6b93bc3d5f9245c5f"],["patterns/coding/writing-inline-demos/index.html","22a4e8166c3fdb14778174ede26ba127"],["patterns/index.html","3088821ec9ee3424fe0ce7826e8b663d"],["patterns/index.xml","276f7358cc6c122ee8b38ec4f86f116f"],["patterns/installation/index.html","4b5b97dba40cb1131b22536e0f40c526"],["patterns/media/including-images/index.html","5501f1b162de829ebba408fe93e2e871"],["patterns/media/including-videos/index.html","68c1b03ce92b5d78be46b312670ab49f"],["patterns/media/index.html","c2e39c5f91dbf5ae238b53881ded734a"],["patterns/media/index.xml","69e133cec08e19eeb33cb005e90590e3"],["patterns/printing/index.html","21cbb13255f6606783e35781d05b3cd0"],["patterns/serving/index.html","74bcbf568897a307e7d156c2679cd8b5"],["patterns/setup/index.html","f64759b069335c7e868c50505756f161"],["patterns/updating/index.html","e6f19a2d952417a9ffa353489f13f1c7"],["patterns/writing/expandable-sections/index.html","56dff4c7ee6bc6cc75805da0471fd67f"],["patterns/writing/index.html","6b876040b71134ead191ec7ea8b222dc"],["patterns/writing/index.xml","53aea727e5ea1133e83cd6a859115e7e"],["patterns/writing/markdown-and-metadata/index.html","2f8a7b540428740bcf3c6f76fe575eb7"],["patterns/writing/notes-and-warnings/index.html","f4d3ae3e5cf35b67b2834b04c0e5a305"],["patterns/writing/project-structure/index.html","6582a714b06c27a5f11fce7675b740e8"],["patterns/writing/references/index.html","944274c1a4c028fa868e658726ea3fd6"],["patterns/writing/snippets/index.html","defd3b88e44cef79a0ad246aab417cad"],["patterns/writing/tables-of-contents/index.html","2aef3ef8756d51908cd971115e076513"],["print-version/index.html","311b2b998f8876b3f30dce34237600d3"],["sitemap.xml","e3f27a45b9955c8ee5f7f72517c65417"],["tags/index.xml","7445f2e8ccc722d44e7533263233d2df"],["tags/markdown/index.html","d6d084b6803ba11bfff11a789689859a"],["tags/markdown/index.xml","5387a8d0317e6b6641e0803ac2f5af3c"],["tags/metadata/index.html","e8c8ede1b409776b684986065f8ef511"],["tags/metadata/index.xml","098f151053be1a17654318a88433154b"]];
 var cacheName = 'sw-precache-v3-sw-precache-' + (self.registration ? self.registration.scope : '');
 
 
diff --git a/themes/infusion/layouts/shortcodes/principles.html b/themes/infusion/layouts/shortcodes/principles.html
index 3778a23..ca846ac 100644
--- a/themes/infusion/layouts/shortcodes/principles.html
+++ b/themes/infusion/layouts/shortcodes/principles.html
@@ -2,7 +2,7 @@
 {{ $included := replace (.Get "include") ", " "," }}
 {{ $included := apply (split $included ",") "lower" "." }}
 {{ $descriptions := .Get "descriptions" }}
-<ul class="principles {{ if $descriptions }}with-desc{{ end }}">
+<ul class="principles {{ if and ($descriptions) (ne $descriptions "false") }}with-desc{{ end }}">
   {{ range $JSON.principles }}
     {{ if in $included (lower .title) }}
       <li>
@@ -15,7 +15,7 @@
           </a>:
         </strong>
         <em>{{ .strapline }}</em>
-        {{ if $descriptions }}
+        {{ if and ($descriptions) (ne $descriptions "false") }}
           <p>{{ .description }}</p>
         {{ end }}
       </li>
diff --git a/themes/infusion/layouts/shortcodes/wcag.html b/themes/infusion/layouts/shortcodes/wcag.html
index 5296911..574af64 100644
--- a/themes/infusion/layouts/shortcodes/wcag.html
+++ b/themes/infusion/layouts/shortcodes/wcag.html
@@ -2,7 +2,7 @@
 {{ $included := replace (.Get "include") ", " "," }}
 {{ $included := split $included "," }}
 {{ $descriptions := .Get "descriptions" }}
-<ul class="wcag {{ if $descriptions }}with-desc{{ end }}">
+<ul class="wcag {{ if and ($descriptions) (ne $descriptions "false") }}with-desc{{ end }}">
   {{ range $JSON }}
     {{ if in $included .ref_id }}
       <li>
@@ -12,7 +12,7 @@
           </svg>
           {{ .ref_id }} {{ .title }}</a> (level {{ .level }}){{ if $descriptions }}:{{ end }}
         </strong>
-        {{ if $descriptions }}
+        {{ if and ($descriptions) (ne $descriptions "false") }}
           {{ .description }}
           {{ if .special_cases }}
             <ul>