4.6 KiB
+++ title = "Code blocks" weight = 1 +++
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.
So, this…
{{}}
<button aria-pressed="false">toggle me</button>
{{}}
… will result in this:
<button aria-pressed="false">toggle me</button>
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.
{{% 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 %}}
Annotated code
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:
{{<html>}}
Confirmation
Press Okay to confirm or Cancel
Okay CancelYou mark out the highlighted areas using triple square brackets like so:
{{}} {{<code>}} <div ] ]> <button ]>x</button> <h2 ]>Confirmation</h2> <p>Press Okay to confirm or Cancel</p> <button>Okay</button> <button>Cancel</button> </div> {{</code>}} {{}}
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:
{{}}
x
Confirmation
Press Okay to confirm or Cancel
Okay
Cancel
{{}}
- The dialog is only announced as a dialog if it takes the
dialogARIA role - The
aria-labelledbyrelationship attribute makes the element carrying theidit points to its label - The close button uses
aria-labelto provide the text label "close", overriding the text content - The heading is used as the dialog's label. The
aria-labelledbyattribute points to itsid
You just include numbered="true" on the opening shortcode tag:
{{}} {{<code numbered="true">}} <div ] ]> <button ]>x</button> <h2 ]>Confirmation</h2> <p>Press Okay to confirm or Cancel</p> <button>Okay</button> <button>Cancel</button> </div> {{</code>}}
- The dialog is only announced as a dialog if it takes the
dialogARIA role - The
aria-labelledbyrelationship attribute makes the element carrying theidit points to its label - The close button uses
aria-labelto provide the text label "close", overriding the text content - The heading is used as the dialog's label. The
aria-labelledbyattribute points to itsid{{}}
JavaScript example
{{}}
/* 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');
}
}
});
}());
{{}}
- The
regionrole announces the block as a region - The
aria-labeldescribes the kind of content to be expected in the region
{{% note %}}
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 %}}