cupper-hugo-theme/exampleSite/content/patterns/writing/references.md

64 lines
2.6 KiB
Markdown
Raw Normal View History

2017-06-28 11:34:21 +02:00
+++
title = "References"
+++
## Cross-references
2017-11-02 16:37:06 +01:00
**Cupper** identifies the main content files in your documentation as _patterns_, and they're kept in the **content/ patterns** folder. It's easy to cross-reference patterns using the `pattern` shortcode. For example, I can reference the {{% pattern "Notes & warnings" %}} pattern. Here's what the markdown looks like, including the shortcode:
2017-06-28 11:34:21 +02:00
{{<codeBlock>}}
2017-06-28 17:46:25 +02:00
I can reference the &#x7b;{% pattern "Notes & warnings" %}} pattern here.
2017-06-28 11:34:21 +02:00
{{</codeBlock>}}
This saves you having to worry about pathing and decorates the generated link with a bookmark icon, identifying the link as a pattern reference visually.
2017-06-28 17:46:25 +02:00
{{% note %}}
The title argument you supply to the shortcode must be exactly the same as the referenced pattern's `title` metadata value and is case sensitive.
{{% /note %}}
2017-06-28 11:34:21 +02:00
## WCAG References
2017-09-07 10:31:52 +02:00
[WCAG 2.0](https://www.w3.org/TR/WCAG/) is the _de facto_ standard for accessible interfaces. When writing about inclusive interfaces, sometimes you'll want to refer to WCAG to highlight which success criteria the pattern meets.
2017-06-28 11:34:21 +02:00
2017-11-02 16:37:06 +01:00
Instead of having to copy and paste content and links to WCAG, **Cupper** provides a shortcode mechanism that lets you simply list the success criteria by number:
2017-06-28 11:34:21 +02:00
{{<codeBlock>}}
&#x7b;{% wcag include="1.2.1, 1.3.1, 4.1.2" %}}
{{</codeBlock>}}
This generates a list of references that includes the names of each criterion and links to them directly. Like this:
{{% wcag include="2.1.1, 4.1.2" %}}
2017-07-08 13:21:43 +02:00
{{% note %}}
You don't have to leave spaces after the comma separators. They are optional.
{{% /note %}}
2017-06-28 11:34:21 +02:00
### Full descriptions
Sometimes, you'll want to include the full descriptions of the success criteria inline. This is possible by setting `descriptions` to `true`:
{{<codeBlock>}}
&#x7b;{% wcag include="1.3.1, 4.1.2" descriptions="true" %}}
{{</codeBlock>}}
Here's the more verbose output:
{{% wcag include="2.1.1, 4.1.2" descriptions="true" %}}
2017-10-06 18:06:33 +02:00
{{% 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 %}}
2017-06-28 11:34:21 +02:00
## 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.
{{<codeBlock>}}
&#x7b;{% principles include="Add value, Be consistent" descriptions="true" %}}
{{</codeBlock>}}
Here's the output with `descriptions="true"`:
2017-07-08 13:21:43 +02:00
{{% principles include="Add value,Be consistent" descriptions="true" %}}