Skip to content

Commit

Permalink
doc: add allowed info strings to style guide
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
Derek Lewis authored and codebytere committed Jul 12, 2020
1 parent b1c9f75 commit 04ceeaf
Showing 1 changed file with 26 additions and 2 deletions.
28 changes: 26 additions & 2 deletions doc/guides/doc-style-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -75,8 +97,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

0 comments on commit 04ceeaf

Please sign in to comment.