squiid/rust
1
0
Fork 0
Code Issues Pull requests Projects Activity

Rollup merge of #81389 - ehuss:rustdoc-cmark-extensions, r=GuillaumeGomez

Browse source 
rustdoc: Document CommonMark extensions.

This updates the rustdoc book to include some documentation on the CommonMark extensions that rustdoc supports.
This commit is contained in:
Yuki Okushi 2021-01-27 04:43:30 +09:00 committed by GitHub
parent acbd1010ef 1c0a52d304
commit ebe28f7a77
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 65 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

66
src/doc/rustdoc/src/how-to-write-documentation.md
View file

@ -153,11 +153,73 @@ and finally provides a code example.
## Markdown
`rustdoc` uses the [commonmark markdown specification]. You might be
`rustdoc` uses the [CommonMark markdown specification]. You might be
interested into taking a look at their website to see what's possible to do.
- [commonmark quick reference]
- [current spec]
In addition to the standard CommonMark syntax, `rustdoc` supports several
extensions:
### Strikethrough
Text may be rendered with a horizontal line through the center by wrapping the
text with two tilde characters on each side:
```text
An example of ~~strikethrough text~~.
```
This example will render as:
> An example of ~~strikethrough text~~.
This follows the [GitHub Strikethrough extension][strikethrough].
### Footnotes
A footnote generates a small numbered link in the text which when clicked
takes the reader to the footnote text at the bottom of the item. The footnote
label is written similarly to a link reference with a caret at the front. The
footnote text is written like a link reference definition, with the text
following the label. Example:
```text
This is an example of a footnote[^note].
[^note]: This text is the contents of the footnote, which will be rendered
towards the bottom.
```
This example will render as:
> This is an example of a footnote[^note].
>
> [^note]: This text is the contents of the footnote, which will be rendered
> towards the bottom.
The footnotes are automatically numbered based on the order the footnotes are
written.
### Tables
Tables can be written using pipes and dashes to draw the rows and columns of
the table. These will be translated to HTML table matching the shape. Example:
```text
| Header1 | Header2 |
|---------|---------|
| abc | def |
```
This example will render similarly to this:
> | Header1 | Header2 |
> |---------|---------|
> | abc | def |
See the specification for the [GitHub Tables extension][tables] for more
details on the exact syntax supported.
[`backtrace`]: https://docs.rs/backtrace/0.3.50/backtrace/
[commonmark markdown specification]: https://commonmark.org/
@ -170,3 +232,5 @@ interested into taking a look at their website to see what's possible to do.
[standard library]: https://doc.rust-lang.org/stable/std/index.html
[current spec]: https://spec.commonmark.org/current/
[`std::env`]: https://doc.rust-lang.org/stable/std/env/index.html#functions
[strikethrough]: https://github.github.com/gfm/#strikethrough-extension-
[tables]: https://github.github.com/gfm/#tables-extension-