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 <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Luigi Pinca <[email protected]>
nodejs · Jun 27, 2020 · 4323346 · 4323346
1 parent c492a27
commit 4323346
Showing 1 changed file with 26 additions and 2 deletions.
diff --git a/doc/guides/doc-style-guide.md b/doc/guides/doc-style-guide.md
@@ -30,7 +30,29 @@
 * When documenting APIs, update the YAML comment associated with the API as
   appropriate. This is especially true when introducing or deprecating an API.
 * For code blocks:
-  * Use [language aware fences][]. (<code>```js</code>)
+  * Use [language][]-aware fences. (<code>```js</code>)
+  * For the [info string][], use one of the following.
+
+    | Meaning       | Info string       |
+    | ------------- | ----------------- |
+    | Bash          | `bash`            |
+    | C             | `c`               |
+    | C++           | `cpp`             |
+    | CoffeeScript  | `coffee`          |
+    | Diff          | `diff`            |
+    | HTTP          | `http`            |
+    | JavaScript    | `js`              |
+    | JSON          | `json`            |
+    | Markdown      | `markdown`        |
+    | Plaintext     | `text`            |
+    | Powershell    | `powershell`      |
+    | R             | `r`               |
+    | Shell Session | `console`         |
+
+    If one of your language-aware fences needs an info string that is not
+    already on this list, you may use `text` until the grammar gets added to
+    [`remark-preset-lint-node`][].
+
   * Code need not be complete. Treat code blocks as an illustration or aid to
     your point, not as complete running programs. If a complete running program
     is necessary, include it as an asset in `assets/code-examples` and link to
@@ -74,8 +96,10 @@
 
 See also API documentation structure overview in [doctools README][].
 
-[language aware fences]: https://github.com/highlightjs/highlight.js/blob/master/SUPPORTED_LANGUAGES.md
+[info string]: https://github.github.com/gfm/#info-string
+[language]: https://github.com/highlightjs/highlight.js/blob/master/SUPPORTED_LANGUAGES.md
 [Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types
 [serial commas]: https://en.wikipedia.org/wiki/Serial_comma
 [plugin]: https://editorconfig.org/#download
 [doctools README]: ../../tools/doc/README.md
+[`remark-preset-lint-node`]: https://github.com/nodejs/remark-preset-lint-node