jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 09:57:42 -05:00
Code Issues Projects Releases Wiki Activity

Update placeholder guidance (#40258)

Browse Source 
Co-authored-by: Felicity Chapman <felicitymay@github.com>
This commit is contained in:
Ethan Palm
2023-08-09 14:24:21 -07:00
committed by GitHub
parent 056cd701d5
commit 1f3b8aba8b
2 changed files with 36 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
contributing/content-markup-reference.md
View File

@@ -101,13 +101,17 @@ Code annotations only work in articles with the `layout: inline` frontmatter pro
To render syntax highlighting in command line instructions, we use triple backticks followed by the language of the sample. For a list of all supported languages, see the [Code languages](https://github.com/github/docs/blob/main/data/variables/code-languages.yml) file.
Do not use HTML to style or modify code samples.
### Usage
```shell
git init YOUR_REPO
git init YOUR-REPO
```
Within the code sample syntax, use all uppercase text to indicate placeholder text or content that varies for each user, such as a user or repository name. By default, codeblocks will escape the content within the triple backticks. If you need to write sample code that parses the content (for example, to italicize text within `<em>` tags instead of passing the tags through literally), wrap the codeblock in `<pre>` `</pre>` tags.
Within the code sample syntax, use all uppercase text to indicate placeholder text or content that varies for each user, such as a user or repository name. Introduce and explain any placeholders before the code sample so that people know what to replace the placeholder text with and because screen readers may not differentiate between upper and lowercase text, so placeholders may not be immediately apparent when read aloud. For example, "In the following example, replace `YOUR-USERNAME` with your GitHub username."
By default, codeblocks will escape the content within the triple backticks. If you need to write sample code that parses the content, wrap the codeblock in `<pre>` `</pre>` tags.
**Copy-able code blocks**
@@ -123,8 +127,8 @@ Octicons are icons used across GitHub’s interface. We reference octicons when
If you're referencing an octicon that appears in the UI, identify whether the octicon is the entire label of the UI element (e.g., a button that is labeled only with "+") or whether it's only decorative, in addition to another label (e.g., a button is labeled "+ Add message").
- If the octicon is the entire label, use your browser's developer tools to inspect the octicon and determine what screen reader users will hear instead. Then, use that text for the `aria-label` (e.g., `{% octicon "plus" aria-label="Add file" %}`). Occasionally, in the UI, the octicon itself will not have an `aria-label`, but a surrounding element such as a `<summary>` or `<div>` tag will.
- If the octicon is decorative, it's likely hidden to screen readers with the `aria-hidden=true` attribute. If so, for consistency with the product, use `aria-hidden="true"` in the Liquid syntax for the octicon in the docs as well (e.g., `"{% octicon "plus" aria-hidden="true" %} Add message"`).
- If the octicon is the entire label, use your browser's developer tools to inspect the octicon and determine what screen reader users will hear instead. Then, use that text for the `aria-label` (e.g., `{% octicon "plus" aria-label="Add file" %}`). Occasionally, in the UI, the octicon itself will not have an `aria-label`, but a surrounding element such as a `<summary>` or `<div>` tag will.
- If the octicon is decorative, it's likely hidden to screen readers with the `aria-hidden=true` attribute. If so, for consistency with the product, use `aria-hidden="true"` in the Liquid syntax for the octicon in the docs as well (e.g., `"{% octicon "plus" aria-hidden="true" %} Add message"`).
If you're using the octicon in another way, such as using the "check" and "x" icons to reflect binary values in tables, use the `aria-label` to describe the meaning of the octicon, not its visual characteristics. For example, if you're using a "x" icon in the "Supported" column of a table, use "Not supported" as the `aria-label`. For more information, see [Tables](./content-style-guide.md#use-clear-consistent-symbols-and-labels) in the style guide.