Skip to content

Commit

Permalink
feat: Enable Markdown processing in Nunjucks templates (#619)
Browse files Browse the repository at this point in the history 
closes #598

- Updated Nunjucks templates to use the `| markdown | safe` filter for processing Markdown content as HTML.
- Applied changes to the following files:
  - `how-to-create-accessible-documents-in-office-2016.njk`
  - `how-to-create-accessible-documents-in-office-365.njk`
  - `comment-creer-des-documents-accessibles-dans-microsoft-365.njk`
  - `comment-creer-des-documents-accessibles-dans-office-2016.njk`

These changes allow the use of Markdown in .njk files, ensuring that headings and other elements are rendered correctly with IDs and proper formatting.
  • Loading branch information
@shawnthompson
shawnthompson authored Jul 17, 2024
1 parent 30a2a33 commit 2d9e0a7
Show file tree
Hide file tree
Showing 5 changed files with 581 additions and 601 deletions.
7 changes: 6 additions & 1 deletion .eleventy.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ module.exports = function (eleventyConfig) {
const eleventySlugify = eleventyConfig.getFilter('slug');

let markdownItOptions = {
html: true, // you can include HTML tags
html: true, // Enable HTML tags in Markdown
};

const md = markdownIt(markdownItOptions)
Expand Down Expand Up @@ -128,6 +128,11 @@ module.exports = function (eleventyConfig) {
});
});

// Add custom Markdown filter for Nunjucks
eleventyConfig.addNunjucksFilter("markdown", function (value) {
return md.render(value);
});

return {
dir: {
input: "src",
Expand Down
279 changes: 144 additions & 135 deletions src/main/en/how-tos/microsoft-office/how-to-create-accessible-documents-in-microsoft-365.njk
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,138 +4,147 @@ description: Accessible practices for digital document creation.
toggle: comment-creer-des-documents-accessibles-dans-microsoft-365
---

<h2>What is an accessible document?</h2>
<p>An accessible document is fully usable by persons with and without disabilities. Making your documents accessible allows users to navigate them in different ways.</p>
<p>For example, a blind user may use a screen reader or a braille display. A person with a motor impairment may use a keyboard rather than a mouse. Other users may need to adjust the font size or spacing to compensate for vision loss or cognitive disabilities.</p>

<h3>Meeting accessibility standards</h3>
<p>Accessibility of digital content (including web pages and documents) is evaluated according to the Web Content Accessibility Guidelines (WCAG). Following this guide does not ensure full compliance with these guidelines, but it is a good start!</p>

<h2>Writing content</h2>
<p>Using plain language ensures that everyone, including persons with cognitive disabilities, can understand the content of documents and use the information effectively. Documents should be clear, concise, and well organized.</p>
<ul>
<li>Use short sentences and plain language</li>
<li>Measure to a Grade 8 reading level</li>
<li>Avoid jargon and unusual words</li>
<li>Define acronyms when first used</li>
<li>Follow best practices for the subject matter and intended audience</li>
</ul>

<h2>Document structure</h2>

<h3>Headings</h3>
<p>A good heading structure makes it easier to navigate and locate content, especially for users of screen readers. It is crucial to use built-in heading styles for all headings.</p>
<p>Apply a consecutive, logical heading order where higher level headings provide context to lower level headings. Do not skip heading levels. For example:</p>
<ul>
<li> Subsections of a level 1 heading should be heading level 2, not 3 or 4</li>
<li> Subsections of a level 2 heading should be heading level 3, etc.</li>
</ul>
<p>Avoid these <b>common heading errors</b>:</p>
<ul>
<li> Formatting the text (bold, larger size) instead of using heading styles</li>
<li> Using heading styles to format text (bold, larger size) when the text isn’t a heading</li>
<li> Using different colours, sizes, or fonts for headings of the same level</li>
</ul>

<h3>Tables</h3>
<p>Tables may be difficult to navigate or edit for users of screen readers. Design tables to be as simple as possible.</p>
<ul>
<li>Do not use tables for layout / styling</li>
<li>Use built-in software features to create tables</li>
<li>Define column headings and row headings</li>
<li>Add alt-text to tables with a short summary of the content</li>
<li>Avoid nested tables, merged cells, split cells, or blank rows / columns</li>
</ul>

<h3>Links to websites</h3>
<p>Link text should make sense even when read out of context, for example in a list of links.</p>
<ul>
<li>Use the name of the website or organization as link text</li>
<li>Don’t use the URL as the link text, unless the full URL needs to appear in print</li>
<li>Avoid generic wording like “Click here” or “Read more”</li>
<li>Make link text as short as possible while still making it clear where the link goes</li>
</ul>

<h3>Other special elements</h3>
<p>Use the software’s built-in functions to create elements which should be treated differently from normal body text. These include:</p>
<ul>
<li>Bulleted and numbered lists</li>
<li>Table of contents</li>
<li>Headers, footers, and page numbers</li>
</ul>
<p><strong>Avoid using text boxes</strong>. These are typically ignored by screen readers and are inaccessible to keyboard users.</p>
<h2>Formatting</h2>
<h3>Colours</h3>
<p>Text must have a contrast ratio of at least 4.5:1 against the background. Black text on a white background is always a safe choice.</p>
<ul>
<li>Check contrast with the <a href="https://developer.paciellogroup.com/resources/contrastanalyser/">Colour Contrast Analyser</a> or <a href="https://webaim.org/resources/contrastchecker/">WebAIM Contrast Checker</a></li>
<li>Avoid complex background images. If you must use a background image, use the <a href="https://www.brandwood.com/a11y/">Text on Background image a11y check</a></li>
<li>Include a contrasting outline/stroke around the text when the background cannot be changed to meet contrast requirements</li>
</ul>
<p>The same principles apply to meaningful non-text elements such as icons and charts, but the requirement is relaxed to 3:1. For example, adjacent slices in a pie chart should be easy to distinguish from each other.</p>
<h3>Fonts</h3>
<p>Choose fonts and styles that are easy to read rather than decorative.</p>
<ul>
<li>Use sans-serif fonts with sufficient spacing between letters and lines
<ul>
<li>Arial, Verdana, and Calibri are all sans-serif fonts</li>
</ul>
</li>
<li>Body text size should be 11 to 14 points for a print-style document like this one
<ul>
<li>Some fonts appear larger than others. Compare with 12 point Arial.</li>
</ul>
</li>
<li>Larger fonts should be used for presentations (18 point minimum)</li>
<li>Avoid using italics for more than a few words</li>
</ul>
<p>Do not rely solely on visual formatting to convey information. For example, avoid phrases like “priority tasks in bold”, “changes highlighted in yellow”, or “see the left sidebar for details”.</p>
<h2>Non-text elements</h2>
<p>Visual elements such as photos, icons, diagrams, and tables should include alternative text (“alt text”) that briefly answers the question “What information is the image conveying?”.</p>
<p>A good starting point for writing alt text is to imagine
that you are describing the image to a person over the phone.</p>
<h3>Short alternative text</h3>
<p>Keep your descriptions as brief as possible (at most 65 characters). Ignore details that don’t relate to the document. For example, a picture of a group of students appears in a document about hiring summer students.</p>
<ul>
<li>Good: “Students being trained in a boardroom”</li>
<li>Too long: “Five students in business attire sit in a boardroom looking at a projector screen while the presenter gestures towards the leftmost student”</li>
</ul>
<p>Avoid these <strong>common alt text errors</strong>:</p>
<ul>
<li>Putting text inside an image
<ul>
<li>If images of text can’t be avoided, include all visible text in the alt text</li>
</ul>
</li>
<li> Starting each description with “Image of…”
<ul>
<li>Do begin with “Screenshot of…” if the image is a screenshot</li>
</ul>
</li>
<li>Repeating the text of an adjacent caption</li>
<li>Describing decorative images (which don’t convey any meaningful information)
<ul>
<li>Instead, set alt=”” for the web, or set description as “decorative” in Word</li>
</ul>
</li>
</ul>
<h3>Long text description</h3>
<p>Sometimes the short alt-text isn’t enough to describe the visual element. In these cases, you should also provide a long description. Include this in the visible text if possible.</p>
<p>Examples:</p>
<ul>
<li>Road map with directions: Describe each step needed to follow the directions</li>
<li>Flow chart: Use numbered components to fully describe the process</li>
<li>Line graph: Describe trends, then include the data points in a table</li>
</ul>
<p>For more examples, see the W3C’s tutorial on <a href="https://www.w3.org/WAI/tutorials/images/complex/">Complex Images</a>.</p>
<h3>Video, audio, and multimedia</h3>
<p>Embedded audio or video requires a transcript. Videos should be captioned and audio-described. The player controls — start, pause and stop — must be accessible.</p>
<h2>Additional resources</h2>
<ul>
<li><a href="https://support.google.com/docs/answer/6199477?hl=en&amp;ref_topic=6039805">Google Docs – &quot;Make your document or presentation accessible&quot;</a></li>
<li><a href="https://support.microsoft.com/en-us/office/make-your-content-accessible-to-everyone-ecab0fcf-d143-4fe8-a2ff-6cd596bddc6d">Microsoft – &quot;Make your content accessible to everyone&quot;</a></li>
<li><a href="https://www.canada.ca/en/treasury-board-secretariat/services/government-communications/canada-content-style-guide.html#toc5">Government of Canada &quot;Canada.ca Content Style Guide”</a> </li>
<li><a href="https://support.office.com/en-us/article/test-your-document-s-readability-85b4969e-e80a-4777-8dd3-f7fc3c8b3fd2#__toc342546557">Flesch-Kincaid Reading-Ease Test</a> for English and <a href="http://www.scolarius.com/">Scolarius</a> for French</li>
<li><a href="https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html" rel="external">Understanding non-text contrast</a></li>
<li><a href="https://support.office.com/en-ie/article/add-alternative-text-to-a-shape-picture-chart-smartart-graphic-or-other-object-44989b2a-903c-4d9a-b742-6a75b451c669">Add alternative text – Microsoft Office Support</a></li>
</ul>
{# This allows us to use markdown in .njk files #}

{{ "
## What is an accessible document?
An accessible document is fully usable by persons with and without disabilities. Making your documents accessible allows users to navigate them in different ways.
For example, a blind user may use a screen reader or a braille display. A person with a motor impairment may use a keyboard rather than a mouse. Other users may need to adjust the font size or spacing to compensate for vision loss or cognitive disabilities.
### Meeting accessibility standards
Accessibility of digital content (including web pages and documents) is evaluated according to the Web Content Accessibility Guidelines (WCAG). Following this guide does not ensure full compliance with these guidelines, but it is a good start!
## Writing content
Using plain language ensures that everyone, including persons with cognitive disabilities, can understand the content of documents and use the information effectively. Documents should be clear, concise, and well organized.
- Use short sentences and plain language
- Measure to a Grade 8 reading level
- Avoid jargon and unusual words
- Define acronyms when first used
- Follow best practices for the subject matter and intended audience
## Document structure
### Headings
A good heading structure makes it easier to navigate and locate content, especially for users of screen readers. It is crucial to use built-in heading styles for all headings.
Apply a consecutive, logical heading order where higher level headings provide context to lower level headings. Do not skip heading levels. For example:
- Subsections of a level 1 heading should be heading level 2, not 3 or 4
- Subsections of a level 2 heading should be heading level 3, etc.
Avoid these **common heading errors**:
- Formatting the text (bold, larger size) instead of using heading styles
- Using heading styles to format text (bold, larger size) when the text isn’t a heading
- Using different colours, sizes, or fonts for headings of the same level
### Tables
Tables may be difficult to navigate or edit for users of screen readers. Design tables to be as simple as possible.
- Do not use tables for layout / styling
- Use built-in software features to create tables
- Define column headings and row headings
- Add alt-text to tables with a short summary of the content
- Avoid nested tables, merged cells, split cells, or blank rows / columns
### Links to websites
Link text should make sense even when read out of context, for example in a list of links.
- Use the name of the website or organization as link text
- Don’t use the URL as the link text, unless the full URL needs to appear in print
- Avoid generic wording like “Click here” or “Read more”
- Make link text as short as possible while still making it clear where the link goes
### Other special elements
Use the software’s built-in functions to create elements which should be treated differently from normal body text. These include:
- Bulleted and numbered lists
- Table of contents
- Headers, footers, and page numbers
**Avoid using text boxes**. These are typically ignored by screen readers and are inaccessible to keyboard users.
## Formatting
### Colours
Text must have a contrast ratio of at least 4.5:1 against the background. Black text on a white background is always a safe choice.
- Check contrast with the [Colour Contrast Analyser](https://developer.paciellogroup.com/resources/contrastanalyser/) or [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
- Avoid complex background images. If you must use a background image, use the [Text on Background image a11y check](https://www.brandwood.com/a11y/)
- Include a contrasting outline/stroke around the text when the background cannot be changed to meet contrast requirements
The same principles apply to meaningful non-text elements such as icons and charts, but the requirement is relaxed to 3:1. For example, adjacent slices in a pie chart should be easy to distinguish from each other.
### Fonts
Choose fonts and styles that are easy to read rather than decorative.
- Use sans-serif fonts with sufficient spacing between letters and lines
- Arial, Verdana, and Calibri are all sans-serif fonts
- Body text size should be 11 to 14 points for a print-style document like this one
- Some fonts appear larger than others. Compare with 12 point Arial.
- Larger fonts should be used for presentations (18 point minimum)
- Avoid using italics for more than a few words
Do not rely solely on visual formatting to convey information. For example, avoid phrases like “priority tasks in bold”, “changes highlighted in yellow”, or “see the left sidebar for details”.
## Non-text elements
Visual elements such as photos, icons, diagrams, and tables should include alternative text (“alt text”) that briefly answers the question “What information is the image conveying?”.
A good starting point for writing alt text is to imagine that you are describing the image to a person over the phone.
### Short alternative text
Keep your descriptions as brief as possible (at most 65 characters). Ignore details that don’t relate to the document. For example, a picture of a group of students appears in a document about hiring summer students.
- Good: “Students being trained in a boardroom”
- Too long: “Five students in business attire sit in a boardroom looking at a projector screen while the presenter gestures towards the leftmost student”
Avoid these **common alt text errors**:
- Putting text inside an image
- If images of text can’t be avoided, include all visible text in the alt text
- Starting each description with “Image of…”
- Do begin with “Screenshot of…” if the image is a screenshot
- Repeating the text of an adjacent caption
- Describing decorative images (which don’t convey any meaningful information)
- Instead, set `alt=\"\"` for the web, or set description as “decorative” in Word
### Long text description
Sometimes the short alt-text isn’t enough to describe the visual element. In these cases, you should also provide a long description. Include this in the visible text if possible.
Examples:
- Road map with directions: Describe each step needed to follow the directions
- Flow chart: Use numbered components to fully describe the process
- Line graph: Describe trends, then include the data points in a table
For more examples, see the W3C’s tutorial on [Complex Images](https://www.w3.org/WAI/tutorials/images/complex/).
### Video, audio, and multimedia
Embedded audio or video requires a transcript. Videos should be captioned and audio-described. The player controls — start, pause and stop — must be accessible.
## Additional resources
- [Google Docs – \"Make your document or presentation accessible\"](https://support.google.com/docs/answer/6199477?hl=en&amp;ref_topic=6039805)
- [Microsoft – \"Make your content accessible to everyone\"](https://support.microsoft.com/en-us/office/make-your-content-accessible-to-everyone-ecab0fcf-d143-4fe8-a2ff-6cd596bddc6d)
- [Government of Canada \"Canada.ca Content Style Guide\"](https://www.canada.ca/en/treasury-board-secretariat/services/government-communications/canada-content-style-guide.html#toc5)
- [Flesch-Kincaid Reading-Ease Test](https://support.office.com/en-us/article/test-your-document-s-readability-85b4969e-e80a-4777-8dd3-f7fc3c8b3fd2#__toc342546557) for English and [Scolarius](http://www.scolarius.com/) for French
- [Understanding non-text contrast](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html)
- [Add alternative text – Microsoft Office Support](https://support.office.com/en-ie/article/add-alternative-text-to-a-shape-picture-chart-smartart-graphic-or-other-object-44989b2a-903c-4d9a-b742-6a75b451c669)
" | markdown | safe }}
Loading

0 comments on commit 2d9e0a7

Please sign in to comment.