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

Clarify code sample language in contributing docs (#38290)

Browse Source
This commit is contained in:
Ethan Palm
2023-06-22 13:08:16 -07:00
committed by GitHub
parent 50cfe07e20
commit f5102f03e3
2 changed files with 5 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -99,7 +99,7 @@ Code annotations only work in articles with the `layout: inline` frontmatter pro
## Code sample syntax highlighting
To render syntax highlighting in command line instructions, we use triple backticks followed by the term `shell`.
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.
### Usage
@@ -107,9 +107,7 @@ To render syntax highlighting in command line instructions, we use triple backti
git init YOUR_REPO
```
This syntax highlighting renders light text on a dark background, and should be reserved for command line instructions.
Within the command-line 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. 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.
**Copy-able code blocks**

5
contributing/content-style-guide.md
View File

@@ -56,6 +56,7 @@ Style your CTAs using the following format.
Keep lines in code samples to about 60 characters, to avoid requiring readers to scroll horizontally in the code block. Locate explanatory text before the code block, rather than using comments inside the code block. See "[Code sample syntax highlighting](./content-markup-reference.md#code-sample-syntax-highlighting)" for more information on the syntax and formatting of code blocks.
Within code blocks:
- Specify the language of the sample after the first code fence. For a list of all supported languages, see [Code languages](/Users/ethanpalm/docs-internal/contributing/content-markup-reference.md).
- Do not use markup before the command output.
- Only use `$` before the command itself if you’re showing the command’s output in the same block.
- If you show a command and the command's output, do not make the code block copyable.
@@ -63,13 +64,13 @@ Within code blocks:
- If your code example includes content that should be parsed (for example, HTML tags to format text), wrap that section in `<pre>` `</pre>` tags to parse rather than escape the content in the section.
- **Use**:
```
``` YAML
GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
```
- **Avoid**:
```
``` YAML
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```