2017-06-28 17:46:25 +02:00
+++
title = "Code blocks"
2017-07-04 12:17:09 +02:00
weight = 1
2017-06-28 17:46:25 +02:00
+++
2017-11-02 16:37:06 +01:00
Markdown already supports code samples both inline (using single backticks like \`some code here\`) and in blocks. **Cupper** will syntax highlight HTML, CSS, and JavaScript if you provide the correct language in the formulation of the block.
2017-06-28 17:46:25 +02:00
So, this…
{{< codeBlock > }}
```html
< button aria-pressed="false">toggle me< /button>
```
{{< / codeBlock > }}
… will result in this:
```html
< button aria-pressed = "false" > toggle me< / button >
```
2017-11-02 16:37:06 +01:00
Note that the syntax highlighting uses a greyscale theme. **Cupper** is careful not to use color as part of its own design, because these colors may clash with those of the design being illustrated and discussed.
2017-06-28 17:46:25 +02:00
2017-08-15 10:55:30 +02:00
{{% note %}}
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 %}}
2017-10-07 11:36:18 +02:00
2017-10-08 14:00:44 +02:00
## Annotated code
2017-10-07 13:27:26 +02:00
2017-11-02 16:37:06 +01:00
**Cupper** 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:
2017-10-07 11:36:18 +02:00
{{< html > }}
2017-10-07 13:27:26 +02:00
< 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 >
2017-10-07 11:36:18 +02:00
{{< / html > }}
2017-10-07 13:27:26 +02:00
2017-10-08 14:00:44 +02:00
You mark out the highlighted areas using triple square brackets like so:
2017-10-07 13:27:26 +02:00
{{< codeBlock > }}
2017-10-08 14:00:44 +02:00
{ {< code>}}
< div [[[role="dialog"]]] [[[aria-labelledby="dialog-heading"]]]>
< button [[[aria-label="close"]]]>x< /button>
< h2 [[[id="dialog-heading"]]]>Confirmation< /h2>
2017-10-07 13:27:26 +02:00
< p>Press < strong > Okay< / strong > to confirm or < strong > Cancel< / strong > < /p>
< button>Okay< /button>
< button>Cancel< /button>
< /div>
2017-10-08 14:00:44 +02:00
{ {< /code>}}
2017-10-07 13:27:26 +02:00
{{< / codeBlock > }}
2017-10-08 14:00:44 +02:00
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:
2017-10-07 13:27:26 +02:00
2017-10-08 14:00:44 +02:00
{{< code numbered = "true" > }}
< div [ [ [ role = "dialog" ] ] ] [ [ [ aria-labelledby = "dialog-heading" ] ] ] >
< button [ [ [ aria-label = "close" ] ] ] > x< / button >
< h2 [ [ [ id = "dialog-heading" ] ] ] > Confirmation< / h2 >
2017-10-07 13:27:26 +02:00
< p > Press < strong > Okay< / strong > to confirm or < strong > Cancel< / strong > < / p >
< button > Okay< / button >
< button > Cancel< / button >
< / div >
2017-10-08 14:00:44 +02:00
{{< / 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`
2017-10-07 13:27:26 +02:00
You just include `numbered="true"` on the opening shortcode tag:
{{< codeBlock > }}
2017-10-08 14:00:44 +02:00
{ {< code numbered="true">}}
< div [[[role="dialog"]]] [[[aria-labelledby="dialog-heading"]]]>
< button [[[aria-label="close"]]]>x< /button>
< h2 [[[id="dialog-heading"]]]>Confirmation< /h2>
2017-10-07 13:27:26 +02:00
< p>Press < strong > Okay< / strong > to confirm or < strong > Cancel< / strong > < /p>
< button>Okay< /button>
< button>Cancel< /button>
< /div>
2017-10-08 14:00:44 +02:00
{ {< /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`
2017-10-07 13:27:26 +02:00
{{< / codeBlock > }}
2017-10-07 14:45:48 +02:00
2017-10-08 14:00:44 +02:00
### 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
2017-10-07 14:45:48 +02:00
{{% note %}}
2017-10-08 14:00:44 +02:00
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.
2017-10-07 14:45:48 +02:00
{{% /note %}}
