hugopoi/cupper-hugo-theme
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

html shortcode to code shortcode

Browse Source
This commit is contained in:
Heydon Pickering 2017-10-08 13:00:44 +01:00
parent 362e846524
commit 56152cb712
10 changed files with 205 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
content/patterns/coding/code-blocks.md
View File

@ -25,11 +25,9 @@ Note that the syntax highlighting uses a greyscale theme. **Infusion** is carefu
To preserve the wrapping inside code blocks, horizontal scrolling is implemented. To make sure scrolling is keyboard accessible, code blocks are focusable. An `aria-label` is provided to identify the code block to screen reader users.
{{% /note %}}
## Annotated HTML
## Annotated code
Since the structure of HTML is critical to interoperable web interfaces, **Infusion** offers the ability to highlight and annotate specific HTML elements and attributes using the `html` shortcode.
Take an accessible dialog. You may wish to point out key attributes that make that dialog support assistive technologies:
**Infusion** offers the ability to highlight and annotate specific parts of your code examples using the `code` shortcode. Take an accessible dialog. You may wish to point out key attributes that make that dialog support assistive technologies:
{{<html>}}
<div ((role="dialog")) ((aria-labelledby="dialog-heading"))>
@ -41,46 +39,78 @@ Take an accessible dialog. You may wish to point out key attributes that make th
</div>
{{</html>}}
You mark out the highlighted areas with double parentheses like so:
You mark out the highlighted areas using triple square brackets like so:
{{<codeBlock>}}
&#x7b;{&lt;html>}}
&lt;div ((role="dialog")) ((aria-labelledby="dialog-heading"))>
&lt;button ((aria-label="close"))>x&lt;/button>
&lt;h2 ((id="dialog-heading"))>Confirmation&lt;/h2>
&#x7b;{&lt;code>}}
&lt;div [[[role="dialog"]]] [[[aria-labelledby="dialog-heading"]]]>
&lt;button [[[aria-label="close"]]]>x&lt;/button>
&lt;h2 [[[id="dialog-heading"]]]>Confirmation&lt;/h2>
&lt;p>Press <strong>Okay</strong> to confirm or <strong>Cancel</strong>&lt;/p>
&lt;button>Okay&lt;/button>
&lt;button>Cancel&lt;/button>
&lt;/div>
&#x7b;{&lt;/html>}}
&#x7b;{&lt;/code>}}
{{</codeBlock>}}
Better still, if you include `numbered="true"`, each highlight is enumerated so you can reference it directly in the ensuing text.
Better still, if you include `numbered="true"`, each highlight is enumerated so you can reference it directly in the ensuing text. If you follow the shortcode directly with an ordered list, the styles match:
{{<html numbered="true">}}
<div ((role="dialog")) ((aria-labelledby="dialog-heading"))>
<button ((aria-label="close"))>x</button>
<h2 ((id="dialog-heading"))>Confirmation</h2>
{{<code numbered="true">}}
<div [[[role="dialog"]]] [[[aria-labelledby="dialog-heading"]]]>
<button [[[aria-label="close"]]]>x</button>
<h2 [[[id="dialog-heading"]]]>Confirmation</h2>
<p>Press <strong>Okay</strong> to confirm or <strong>Cancel</strong></p>
<button>Okay</button>
<button>Cancel</button>
</div>
{{</html>}}
{{</code>}}
1. The dialog is only announced as a dialog if it takes the `dialog` ARIA role
2. The `aria-labelledby` relationship attribute makes the element carrying the `id` it points to its label
3. The close button uses `aria-label` to provide the text label "close", overriding the text content
4. The heading is used as the dialog's label. The `aria-labelledby` attribute points to its `id`
You just include `numbered="true"` on the opening shortcode tag:
{{<codeBlock>}}
&#x7b;{&lt;html numbered="true">}}
&lt;div ((role="dialog")) ((aria-labelledby="dialog-heading"))>
&lt;button ((aria-label="close"))>x&lt;/button>
&lt;h2 ((id="dialog-heading"))>Confirmation&lt;/h2>
&#x7b;{&lt;code numbered="true">}}
&lt;div [[[role="dialog"]]] [[[aria-labelledby="dialog-heading"]]]>
&lt;button [[[aria-label="close"]]]>x&lt;/button>
&lt;h2 [[[id="dialog-heading"]]]>Confirmation&lt;/h2>
&lt;p>Press <strong>Okay</strong> to confirm or <strong>Cancel</strong>&lt;/p>
&lt;button>Okay&lt;/button>
&lt;button>Cancel&lt;/button>
&lt;/div>
&#x7b;{&lt;/html>}}
&#x7b;{&lt;/code>}}
1. The dialog is only announced as a dialog if it takes the `dialog` ARIA role
2. The `aria-labelledby` relationship attribute makes the element carrying the `id` it points to its label
3. The close button uses `aria-label` to provide the text label "close", overriding the text content
4. The heading is used as the dialog's label. The `aria-labelledby` attribute points to its `id`
{{</codeBlock>}}
### JavaScript example
{{<code numbered="true">}}
/* Enable scrolling by keyboard of code samples */
(function () {
var codeBlocks = document.querySelectorAll('pre, .code-annotated');
Array.prototype.forEach.call(codeBlocks, function (block) {
if (block.querySelector('code')) {
block.setAttribute([[['role', 'region']]]);
block.setAttribute([[['aria-label', 'code sample']]]);
if (block.scrollWidth > block.clientWidth) {
block.setAttribute('tabindex', '0');
}
}
});
}());
{{</code>}}
1. The `region` role announces the block as a region
2. The `aria-label` describes the kind of content to be expected in the region
{{% note %}}
As you may have noticed, using specified highlights with the `html` shortcode sacrifices syntax highlighting.
As you may have noticed, using specified highlights with the `code` shortcode sacrifices syntax highlighting. If you want syntax highlighting you must use the markdown triple back-tick syntax and annotation is not available.
{{% /note %}}

26
docs/css/styles.css
View File

@ -519,11 +519,11 @@ pre[class*=language-][data-line] {
pre[class*=language-] code * {
margin-top: 0 !important;
}
[data-codeblock-shortcode], .html-annotated code {
[data-codeblock-shortcode], .code-annotated code {
display: inline-block;
margin-top: -1rem;
}
.html-annotated {
.code-annotated {
overflow-y: hidden;
overflow-x: auto;
padding: 1.5rem;
@ -536,7 +536,8 @@ pre[class*=language-] code * {
padding: 0.0625rem 0.33rem;
border-radius: 0.5rem;
}
.numbered .highlight::after {
.numbered .highlight::after,
.code-annotated.numbered + ol li::before {
counter-increment: annotation;
content: counter(annotation);
font-weight: bold;
@ -548,16 +549,17 @@ pre[class*=language-] code * {
padding: 0.125em 0.5em;
vertical-align: 0.33em;
}
/*main {
display: block;
counter-reset: fig;
min-height: 100vh;
.code-annotated.numbered + ol {
list-style: none;
counter-reset: annotation;
}
.code-annotated.numbered + ol li::before {
font-size: 0.66em;
margin-right: 0.33em;
vertical-align: 0.25em;
}
figcaption::before {
counter-increment: fig;
content: 'Figure ' counter(fig) ':\0020';
font-weight: bold;
}*/
/* file tree lists */
.file-tree {
overflow-x: auto;

2
docs/js/dom-scripts.js
View File

@ -82,7 +82,7 @@
/* Enable scrolling by keyboard of code samples */
(function () {
var codeBlocks = document.querySelectorAll('pre, .html-annotated');
var codeBlocks = document.querySelectorAll('pre, .code-annotated');
Array.prototype.forEach.call(codeBlocks, function (block) {
if (block.querySelector('code')) {

77
docs/patterns/coding/code-blocks/index.html
View File

@ -425,17 +425,15 @@
</aside>
<h2 id="annotated-html">Annotated HTML</h2>
<h2 id="annotated-code">Annotated code</h2>
<p>Since the structure of HTML is critical to interoperable web interfaces, <strong>Infusion</strong> offers the ability to highlight and annotate specific HTML elements and attributes using the <code>html</code> shortcode.</p>
<p>Take an accessible dialog. You may wish to point out key attributes that make that dialog support assistive technologies:</p>
<p><strong>Infusion</strong> offers the ability to highlight and annotate specific parts of your code examples using the <code>code</code> shortcode. Take an accessible dialog. You may wish to point out key attributes that make that dialog support assistive technologies:</p>
<div class="html-annotated "><code>
<div class="code-annotated "><code>
&lt;div <span class='highlight'>role=&#34;dialog&#34;</span> <span class='highlight'>aria-labelledby=&#34;dialog-heading&#34;</span>&gt;
&lt;button <span class='highlight'>aria-label=&#34;close&#34;</span>&gt;x&lt;/button&gt;
&lt;h2 <span class='highlight'>id=&#34;dialog-heading&#34;</span>&gt;Confirmation&lt;/h2&gt;
@ -446,28 +444,28 @@
</code></div>
<p>You mark out the highlighted areas with double parentheses like so:</p>
<p>You mark out the highlighted areas using triple square brackets like so:</p>
<pre class=""><code data-codeblock-shortcode>
&#x7b;{&lt;html>}}
&lt;div ((role="dialog")) ((aria-labelledby="dialog-heading"))>
&lt;button ((aria-label="close"))>x&lt;/button>
&lt;h2 ((id="dialog-heading"))>Confirmation&lt;/h2>
&#x7b;{&lt;code>}}
&lt;div [[[role="dialog"]]] [[[aria-labelledby="dialog-heading"]]]>
&lt;button [[[aria-label="close"]]]>x&lt;/button>
&lt;h2 [[[id="dialog-heading"]]]>Confirmation&lt;/h2>
&lt;p>Press <strong>Okay</strong> to confirm or <strong>Cancel</strong>&lt;/p>
&lt;button>Okay&lt;/button>
&lt;button>Cancel&lt;/button>
&lt;/div>
&#x7b;{&lt;/html>}}
&#x7b;{&lt;/code>}}
</code></pre>
<p>Better still, if you include <code>numbered=&quot;true&quot;</code>, each highlight is enumerated so you can reference it directly in the ensuing text.</p>
<p>Better still, if you include <code>numbered=&quot;true&quot;</code>, each highlight is enumerated so you can reference it directly in the ensuing text. If you follow the shortcode directly with an ordered list, the styles match:</p>
<div class="html-annotated numbered"><code>
<div class="code-annotated numbered"><code>
&lt;div <span class='highlight'>role=&#34;dialog&#34;</span> <span class='highlight'>aria-labelledby=&#34;dialog-heading&#34;</span>&gt;
&lt;button <span class='highlight'>aria-label=&#34;close&#34;</span>&gt;x&lt;/button&gt;
&lt;h2 <span class='highlight'>id=&#34;dialog-heading&#34;</span>&gt;Confirmation&lt;/h2&gt;
@ -478,27 +476,68 @@
</code></div>
<ol>
<li>The dialog is only announced as a dialog if it takes the <code>dialog</code> ARIA role</li>
<li>The <code>aria-labelledby</code> relationship attribute makes the element carrying the <code>id</code> it points to its label</li>
<li>The close button uses <code>aria-label</code> to provide the text label &ldquo;close&rdquo;, overriding the text content</li>
<li>The heading is used as the dialog&rsquo;s label. The <code>aria-labelledby</code> attribute points to its <code>id</code></li>
</ol>
<p>You just include <code>numbered=&quot;true&quot;</code> on the opening shortcode tag:</p>
<pre class=""><code data-codeblock-shortcode>
&#x7b;{&lt;html numbered="true">}}
&lt;div ((role="dialog")) ((aria-labelledby="dialog-heading"))>
&lt;button ((aria-label="close"))>x&lt;/button>
&lt;h2 ((id="dialog-heading"))>Confirmation&lt;/h2>
&#x7b;{&lt;code numbered="true">}}
&lt;div [[[role="dialog"]]] [[[aria-labelledby="dialog-heading"]]]>
&lt;button [[[aria-label="close"]]]>x&lt;/button>
&lt;h2 [[[id="dialog-heading"]]]>Confirmation&lt;/h2>
&lt;p>Press <strong>Okay</strong> to confirm or <strong>Cancel</strong>&lt;/p>
&lt;button>Okay&lt;/button>
&lt;button>Cancel&lt;/button>
&lt;/div>
&#x7b;{&lt;/html>}}
&#x7b;{&lt;/code>}}
1. The dialog is only announced as a dialog if it takes the `dialog` ARIA role
2. The `aria-labelledby` relationship attribute makes the element carrying the `id` it points to its label
3. The close button uses `aria-label` to provide the text label "close", overriding the text content
4. The heading is used as the dialog's label. The `aria-labelledby` attribute points to its `id`
</code></pre>
<h3 id="javascript-example">JavaScript example</h3>
<div class="code-annotated numbered"><code>
/* Enable scrolling by keyboard of code samples */
(function () {
var codeBlocks = document.querySelectorAll(&#39;pre, .code-annotated&#39;);
Array.prototype.forEach.call(codeBlocks, function (block) {
if (block.querySelector(&#39;code&#39;)) {
block.setAttribute(<span class='highlight'>&#39;role&#39;, &#39;region&#39;</span>);
block.setAttribute(<span class='highlight'>&#39;aria-label&#39;, &#39;code sample&#39;</span>);
if (block.scrollWidth &gt; block.clientWidth) {
block.setAttribute(&#39;tabindex&#39;, &#39;0&#39;);
}
}
});
}());
</code></div>
<ol>
<li>The <code>region</code> role announces the block as a region</li>
<li>The <code>aria-label</code> describes the kind of content to be expected in the region</li>
</ol>
<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>As you may have noticed, using specified highlights with the <code>html</code> shortcode sacrifices syntax highlighting.</p>
<p>As you may have noticed, using specified highlights with the <code>code</code> shortcode sacrifices syntax highlighting. If you want syntax highlighting you must use the markdown triple back-tick syntax and annotation is not available.</p>
</div>
</aside>

77
docs/print-version/index.html
View File

@ -1709,17 +1709,15 @@ toc = false
</aside>
<h2 id="annotated-html">Annotated HTML</h2>
<h2 id="annotated-code">Annotated code</h2>
<p>Since the structure of HTML is critical to interoperable web interfaces, <strong>Infusion</strong> offers the ability to highlight and annotate specific HTML elements and attributes using the <code>html</code> shortcode.</p>
<p>Take an accessible dialog. You may wish to point out key attributes that make that dialog support assistive technologies:</p>
<p><strong>Infusion</strong> offers the ability to highlight and annotate specific parts of your code examples using the <code>code</code> shortcode. Take an accessible dialog. You may wish to point out key attributes that make that dialog support assistive technologies:</p>
<div class="html-annotated "><code>
<div class="code-annotated "><code>
&lt;div <span class='highlight'>role=&#34;dialog&#34;</span> <span class='highlight'>aria-labelledby=&#34;dialog-heading&#34;</span>&gt;
&lt;button <span class='highlight'>aria-label=&#34;close&#34;</span>&gt;x&lt;/button&gt;
&lt;h2 <span class='highlight'>id=&#34;dialog-heading&#34;</span>&gt;Confirmation&lt;/h2&gt;
@ -1730,28 +1728,28 @@ toc = false
</code></div>
<p>You mark out the highlighted areas with double parentheses like so:</p>
<p>You mark out the highlighted areas using triple square brackets like so:</p>
<pre class=""><code data-codeblock-shortcode>
&#x7b;{&lt;html>}}
&lt;div ((role="dialog")) ((aria-labelledby="dialog-heading"))>
&lt;button ((aria-label="close"))>x&lt;/button>
&lt;h2 ((id="dialog-heading"))>Confirmation&lt;/h2>
&#x7b;{&lt;code>}}
&lt;div [[[role="dialog"]]] [[[aria-labelledby="dialog-heading"]]]>
&lt;button [[[aria-label="close"]]]>x&lt;/button>
&lt;h2 [[[id="dialog-heading"]]]>Confirmation&lt;/h2>
&lt;p>Press <strong>Okay</strong> to confirm or <strong>Cancel</strong>&lt;/p>
&lt;button>Okay&lt;/button>
&lt;button>Cancel&lt;/button>
&lt;/div>
&#x7b;{&lt;/html>}}
&#x7b;{&lt;/code>}}
</code></pre>
<p>Better still, if you include <code>numbered=&quot;true&quot;</code>, each highlight is enumerated so you can reference it directly in the ensuing text.</p>
<p>Better still, if you include <code>numbered=&quot;true&quot;</code>, each highlight is enumerated so you can reference it directly in the ensuing text. If you follow the shortcode directly with an ordered list, the styles match:</p>
<div class="html-annotated numbered"><code>
<div class="code-annotated numbered"><code>
&lt;div <span class='highlight'>role=&#34;dialog&#34;</span> <span class='highlight'>aria-labelledby=&#34;dialog-heading&#34;</span>&gt;
&lt;button <span class='highlight'>aria-label=&#34;close&#34;</span>&gt;x&lt;/button&gt;
&lt;h2 <span class='highlight'>id=&#34;dialog-heading&#34;</span>&gt;Confirmation&lt;/h2&gt;
@ -1762,27 +1760,68 @@ toc = false
</code></div>
<ol>
<li>The dialog is only announced as a dialog if it takes the <code>dialog</code> ARIA role</li>
<li>The <code>aria-labelledby</code> relationship attribute makes the element carrying the <code>id</code> it points to its label</li>
<li>The close button uses <code>aria-label</code> to provide the text label &ldquo;close&rdquo;, overriding the text content</li>
<li>The heading is used as the dialog&rsquo;s label. The <code>aria-labelledby</code> attribute points to its <code>id</code></li>
</ol>
<p>You just include <code>numbered=&quot;true&quot;</code> on the opening shortcode tag:</p>
<pre class=""><code data-codeblock-shortcode>
&#x7b;{&lt;html numbered="true">}}
&lt;div ((role="dialog")) ((aria-labelledby="dialog-heading"))>
&lt;button ((aria-label="close"))>x&lt;/button>
&lt;h2 ((id="dialog-heading"))>Confirmation&lt;/h2>
&#x7b;{&lt;code numbered="true">}}
&lt;div [[[role="dialog"]]] [[[aria-labelledby="dialog-heading"]]]>
&lt;button [[[aria-label="close"]]]>x&lt;/button>
&lt;h2 [[[id="dialog-heading"]]]>Confirmation&lt;/h2>
&lt;p>Press <strong>Okay</strong> to confirm or <strong>Cancel</strong>&lt;/p>
&lt;button>Okay&lt;/button>
&lt;button>Cancel&lt;/button>
&lt;/div>
&#x7b;{&lt;/html>}}
&#x7b;{&lt;/code>}}
1. The dialog is only announced as a dialog if it takes the `dialog` ARIA role
2. The `aria-labelledby` relationship attribute makes the element carrying the `id` it points to its label
3. The close button uses `aria-label` to provide the text label "close", overriding the text content
4. The heading is used as the dialog's label. The `aria-labelledby` attribute points to its `id`
</code></pre>
<h3 id="javascript-example">JavaScript example</h3>
<div class="code-annotated numbered"><code>
/* Enable scrolling by keyboard of code samples */
(function () {
var codeBlocks = document.querySelectorAll(&#39;pre, .code-annotated&#39;);
Array.prototype.forEach.call(codeBlocks, function (block) {
if (block.querySelector(&#39;code&#39;)) {
block.setAttribute(<span class='highlight'>&#39;role&#39;, &#39;region&#39;</span>);
block.setAttribute(<span class='highlight'>&#39;aria-label&#39;, &#39;code sample&#39;</span>);
if (block.scrollWidth &gt; block.clientWidth) {
block.setAttribute(&#39;tabindex&#39;, &#39;0&#39;);
}
}
});
}());
</code></div>
<ol>
<li>The <code>region</code> role announces the block as a region</li>
<li>The <code>aria-label</code> describes the kind of content to be expected in the region</li>
</ol>
<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>As you may have noticed, using specified highlights with the <code>html</code> shortcode sacrifices syntax highlighting.</p>
<p>As you may have noticed, using specified highlights with the <code>code</code> shortcode sacrifices syntax highlighting. If you want syntax highlighting you must use the markdown triple back-tick syntax and annotation is not available.</p>
</div>
</aside>

2
docs/service-worker.js
View File

File diff suppressed because one or more lines are too long

5
themes/infusion/layouts/shortcodes/code.html Normal file
View File

@ -0,0 +1,5 @@
{{ $code := .Inner | htmlEscape }}
{{ $code := replace $code "[[[" "<span class='highlight'>" }}
{{ $code := replace $code "]]]" "</span>" }}
{{ $numbered := .Get "numbered" }}
<div class="code-annotated {{ if and ($numbered) (ne $numbered "false") }}numbered{{ end }}"><code>{{ $code | safeHTML }}</code></div>

2
themes/infusion/layouts/shortcodes/html.html
View File

@ -2,4 +2,4 @@
{{ $html := replace $html "((" "<span class='highlight'>" }}
{{ $html := replace $html "))" "</span>" }}
{{ $numbered := .Get "numbered" }}
<div class="html-annotated {{ if and ($numbered) (ne $numbered "false") }}numbered{{ end }}"><code>{{ $html | safeHTML }}</code></div>
<div class="code-annotated {{ if and ($numbered) (ne $numbered "false") }}numbered{{ end }}"><code>{{ $html | safeHTML }}</code></div>

26
themes/infusion/static/css/styles.css
View File

@ -519,11 +519,11 @@ pre[class*=language-][data-line] {
pre[class*=language-] code * {
margin-top: 0 !important;
}
[data-codeblock-shortcode], .html-annotated code {
[data-codeblock-shortcode], .code-annotated code {
display: inline-block;
margin-top: -1rem;
}
.html-annotated {
.code-annotated {
overflow-y: hidden;
overflow-x: auto;
padding: 1.5rem;
@ -536,7 +536,8 @@ pre[class*=language-] code * {
padding: 0.0625rem 0.33rem;
border-radius: 0.5rem;
}
.numbered .highlight::after {
.numbered .highlight::after,
.code-annotated.numbered + ol li::before {
counter-increment: annotation;
content: counter(annotation);
font-weight: bold;
@ -548,16 +549,17 @@ pre[class*=language-] code * {
padding: 0.125em 0.5em;
vertical-align: 0.33em;
}
/*main {
display: block;
counter-reset: fig;
min-height: 100vh;
.code-annotated.numbered + ol {
list-style: none;
counter-reset: annotation;
}
.code-annotated.numbered + ol li::before {
font-size: 0.66em;
margin-right: 0.33em;
vertical-align: 0.25em;
}
figcaption::before {
counter-increment: fig;
content: 'Figure ' counter(fig) ':\0020';
font-weight: bold;
}*/
/* file tree lists */
.file-tree {
overflow-x: auto;

2
themes/infusion/static/js/dom-scripts.js
View File

@ -82,7 +82,7 @@
/* Enable scrolling by keyboard of code samples */
(function () {
var codeBlocks = document.querySelectorAll('pre, .html-annotated');
var codeBlocks = document.querySelectorAll('pre, .code-annotated');
Array.prototype.forEach.call(codeBlocks, function (block) {
if (block.querySelector('code')) {