Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add allowed info strings to style guide #34024

Closed
wants to merge 2 commits into from
Closed

doc: add allowed info strings to style guide #34024

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
92f2f0d
doc: add allowed info strings to style guide
DerekNonGeneric Jun 23, 2020
14fd89b
fixup! doc: add allowed info strings to style guide
DerekNonGeneric Jun 23, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 26 additions & 2 deletions doc/guides/doc-style-guide.md
View file
Open in desktop
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 @@ -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