Commit 04ceeaf
doc: add allowed info strings to style guide
This commit adds the list of agreed-upon info strings to the
documentation style guide to aid with future development and
maintenance.
Refs: #33510
Refs: #33507
Refs: #33483
Refs: #33531
Refs: #33542
Refs: #33028
Refs: #33548
Refs: #33486
PR-URL: #34024
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>1 parent b1c9f75 commit 04ceeaf
1 file changed
Lines changed: 26 additions & 2 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -30,7 +30,29 @@ | |||
| 30 | 30 | * When documenting APIs, update the YAML comment associated with the API as | |
| 31 | 31 | appropriate. This is especially true when introducing or deprecating an API. | |
| 32 | 32 | * For code blocks: | |
| 33 | - * Use [language aware fences][]. (<code>```js</code>) | ||
| 33 | + * Use [language][]-aware fences. (<code>```js</code>) | ||
| 34 | + * For the [info string][], use one of the following. | ||
| 35 | + | ||
| 36 | + | Meaning | Info string | | ||
| 37 | + | ------------- | ----------------- | | ||
| 38 | + | Bash | `bash` | | ||
| 39 | + | C | `c` | | ||
| 40 | + | C++ | `cpp` | | ||
| 41 | + | CoffeeScript | `coffee` | | ||
| 42 | + | Diff | `diff` | | ||
| 43 | + | HTTP | `http` | | ||
| 44 | + | JavaScript | `js` | | ||
| 45 | + | JSON | `json` | | ||
| 46 | + | Markdown | `markdown` | | ||
| 47 | + | Plaintext | `text` | | ||
| 48 | + | Powershell | `powershell` | | ||
| 49 | + | R | `r` | | ||
| 50 | + | Shell Session | `console` | | ||
| 51 | + | ||
| 52 | + If one of your language-aware fences needs an info string that is not | ||
| 53 | + already on this list, you may use `text` until the grammar gets added to | ||
| 54 | + [`remark-preset-lint-node`][]. | ||
| 55 | + | ||
| 34 | 56 | * Code need not be complete. Treat code blocks as an illustration or aid to | |
| 35 | 57 | your point, not as complete running programs. If a complete running program | |
| 36 | 58 | is necessary, include it as an asset in `assets/code-examples` and link to | |
@@ -75,8 +97,10 @@ | |||
| 75 | 97 | ||
| 76 | 98 | See also API documentation structure overview in [doctools README][]. | |
| 77 | 99 | ||
| 78 | - [language aware fences]: https://github.com/highlightjs/highlight.js/blob/master/SUPPORTED_LANGUAGES.md | ||
| 100 | + [info string]: https://github.github.com/gfm/#info-string | ||
| 101 | + [language]: https://github.com/highlightjs/highlight.js/blob/master/SUPPORTED_LANGUAGES.md | ||
| 79 | 102 | [Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types | |
| 80 | 103 | [serial commas]: https://en.wikipedia.org/wiki/Serial_comma | |
| 81 | 104 | [plugin]: https://editorconfig.org/#download | |
| 82 | 105 | [doctools README]: ../../tools/doc/README.md | |
| 106 | + [`remark-preset-lint-node`]: https://github.com/nodejs/remark-preset-lint-node | ||
0 commit comments