---
title: Accessibility Guidelines
content_template: templates/concept
weight:
---

{{% capture overview %}}

This page gives accessibility guidelines for the Kubernetes documentation.

{{% /capture %}}

{{% capture body %}}

# Writing accessible content

If documentation is meant to serve as a tool for learning and comprehension, then we want to write docs that are truly for everyone ‐ regardless of the technology they use to read it.

## Guidelines to write content that can be presented through a screen reader without losing info or structure.

This is to ensure that being able to see the page, including its visual layout and color use, is not required in order to be able to understand the information presented.

Markdown elements should be used to define the structure and meaning of the elements on the page, including headings, lists, paragraphs, and table elements (including row and column headers).

### Front matter
Hugo uses front matter information to create things like author attribution, categories, and page layout. Copying an existing file, then updating its filename and front matter to can be an easy way to help ensure everything is formatted properly.

[Rajie: We may need to create a template with all the attributes we want in the front matter. Currently, the front matter in our .md files are not consistent]

### Line breaks
Use a single newline to separate block-level content like headings, lists, images, code blocks, and others. The exception is second-level headings, where it should be two newlines. This helps visualize the overall structure of content in a code editor.

### Headings
Remember that screen readers are linear output devices which means they output items on a page one at a time, so if there is a lot of content on your page, applying headings gives the page a structure that allows the user to easily navigate, without having to read loads of content that is of no use, value, or interest to them.
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>Use only one first-level heading per page.</td><td>Use first level heading in blog posts, as Hugo will automatically convert the title section of your post’s front matter into a first-level heading.</td></tr><tr><td>Use ordered headings to provide a meaningful high-level outline of your content.</td><td>Use headings level 4 through 6, unless it is absolutely necessary. If your content is that detailed, it may need to be broken into separate articles.</td>
<tr><td>Use pound or hash signs (#) for non-blog post content,</td><td> Use underlines (--- or ===) to designate first-level headings.</td></tr>
<tr><td>Use sentence case for headings. For example, **Extend kubectl with plugins**</td><td>Use title case for headings. For example, **Extend Kubectl With Plugins** </td></tr>

</table>

### Paragraphs

<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td><ul><li>Try to keep the paragraphs on the shorter side. 5 to 6 sentences maximum.</li>
<li> Use three hyphens (---) to create a horizontal rule. Use horizontal rules for breaks in paragraph content. For example, a change of scene in a story, or a shift of topic within a section.</li></ul></td><td><ul><li>Indent the first paragraph with space characters. For example, ⋅⋅⋅Three spaces before a paragraph will indent it.</li>
<li> Use horizontal rules for decoration.</li></ul>
</td></tr>
</table>

### Links
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>Links should provide context for the content they link to. Certain ports are open on your machines. See <a href="#check-required-ports">Check required ports</a> for more details.</td><td>Use ambiguous terms like “click here”. Certain ports are open on your machines. See <a href="#check-required-ports">here</a> for more details.</td></tr> <tr><td>Use Markdown-style links ([link text](URL)).</td><td><ul><li>Use HTML style links (<link href="/media/examples/link-element-example.css" target="_blank">Visit our tutorial!)</li><li>Create links that open in new tabs or windows.For example, [example website](https://example.com){target="_blank"}</li></td></tr></ul>
</td></tr>
</table>

### Lists
Grouping related items not just looks good visually, but also helps the non-sighted users. When a screen reader comes across a list—whether it is an ordered or unordered list—it will be announced to the user that there is a group of list items. The user can then use the arrow keys to cursor up and down between the various items in the list.
Website navigation links can also be marked up as list items; after all they are nothing but a group of related links.
- End each item in an enumerated list with a period if one or more items in the list are complete sentences. (For the sake of parallelism, normally all items or none should be complete sentences.)
- If a vertical list completes a sentence begun in the introduction to the list, the final period is omitted unless the items in the list are separated by commas or semicolons.
- Uses dashes (-) for unordered lists.
- Use the number one (1.) for ordered lists.
- Use one space after a list item.
- Indent nested lists with four spaces (for example, ⋅⋅⋅⋅-).
- List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either four spaces or one tab.

### Code

<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td><ul><li>Use single backticks to enclose inline code. For example, `var example = true`.</li><li>Use triple backticks before and after a multi-line block of code for fenced code blocks.</li><li> Use meaningful variable names that have a context.</li><li>Ensure that there are no trailing spaces in the code, unless it is absolutely neccesary.</li></ul></td><td><ul><li>Use multi-line blocks of code to create diagrams, flowcharts, or other illustrations.</li><li>Use variable names such as 'foo','bar', and 'baz' that are not meaningful and lack context.</li>
</ul>
</td></tr>
</table>

{{< note >}} Syntax highlighting in the code block should conform to the [contrast guidelines.](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0&showtechniques=141%2C143#contrast-minimum)

### Tables

The semantic purpose of a data table is to present tabular data. Sighted users can quickly scan the table but a screen reader goes through line by line. Proper markup must be added to help the screen reader make the correct associations that a sighted user would.

#### Example of an accessible data table.

<table>
<caption>Monthly Budget</caption>
<thead>
<tr>
<th scope="col">Month</th>
<th scope="col">Amount Earned</th>
<th scope="col">Amount Spent</th>
<th scope="col">Amount Saved</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">January</th>
<td>$2500</td>
<td>$1500</td>
<td>$500</td>
</tr>
<tr>
<th scope="row">February</th>
<td>$2700</td>
<td>$1500</td>
<td>$700</td>
</tr>
</tbody>
</table>
{% endhighlight %}

Making an accessible table isn’t hard and can be broken down into two main things.

1. Add a table caption.

2. Mark row and column headings using the 'scope' attribute

#### Row and column headings
For sighted users, row and column headings of tables are often highlighted visually. The screen reader will need this information coded into the markup.

## Do not rely solely on sensory characteristics of components such as shape, size, visual location, orientation, or sound.
Users should not be required to identify elements solely by their shape or their position on the page.
* Don’t use directional terms as the only clue to location. Left, right, up, down, bottom, above, and below aren’t very useful for people who use screen-reading software. If you must use a directional term, provide additional text about the location, such as in the <b>Save As</b> dialog box, on the <b>Standard</b> toolbar, or in the title bar.

<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>The <b>Comparing changes</b> page summarizes the changes you made, GitHub compares your new branch (the <b>head repository</b> and <b>compare</b> drop-down list) to the current state of the <b>base repository</b> and <b>base</b> branch (`master` on the`kubernetes/website` repository by default). Verify the changes that you made to the file in <b>Unified</b> or <b>Split</b> view for the file that you changed, and if everything is right, click <b>Create pull request</b>.</td><td>The next screen summarizes the changes you made, by comparing your new branch (the <b>head fork</b> and <b>compare</b> selection boxes) to the current state of the <b>base fork</b> and <b>base</b> branch (`master` on the`kubernetes/website` repository by default). You can change any of the selection boxes, but don't do that now. Have a look at the difference viewer on the bottom of the screen, and if everything looks right, click <b>Create pull request</b>.</td></tr>
</table>

## Designing accessible experiences

{{% /capture %}}

{{% capture whatsnext %}}

{{% /capture %}}