From e405e82f74babb75600f8f1d94055885968d5701 Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Tue, 23 Jun 2020 03:45:00 -0400 Subject: [PATCH] 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: https://github.com/nodejs/node/pull/33510 Refs: https://github.com/nodejs/node/pull/33507 Refs: https://github.com/nodejs/node/pull/33483 Refs: https://github.com/nodejs/node/pull/33531 Refs: https://github.com/nodejs/node/pull/33542 Refs: https://github.com/nodejs/node/pull/33028 Refs: https://github.com/nodejs/node/pull/33548 Refs: https://github.com/nodejs/node/pull/33486 PR-URL: https://github.com/nodejs/node/pull/34024 Reviewed-By: Anna Henningsen Reviewed-By: Rich Trott Reviewed-By: James M Snell Reviewed-By: Luigi Pinca --- doc/guides/doc-style-guide.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/doc/guides/doc-style-guide.md b/doc/guides/doc-style-guide.md index 59d9d493b770c6..c4e1f0aa36a371 100644 --- 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][]. (```js) + * Use [language][]-aware fences. (```js) + * 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