mirror of
https://github.com/becarpenter/book6.git
synced 2024-05-07 02:54:53 +00:00
96 lines
3.2 KiB
Markdown
96 lines
3.2 KiB
Markdown
## Markdown Usage
|
|
|
|
The basics of using the GitHub dialect of markdown are
|
|
[here](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax).
|
|
As a general rule, please use the simpler constructs and avoid fancy
|
|
formatting.
|
|
|
|
And don't forget, a separate .md file for each new section in any
|
|
chapter of the book.
|
|
|
|
For some markdown editing tools, flowed text with no line breaks
|
|
is a nuisance. Preferably, wrap the text at ~72 characters.
|
|
makeBook will do this whenever it needs to write a file back,
|
|
using the `mdformat` tool.
|
|
|
|
Web references can be done in basic markdown form, i.e.:
|
|
|
|
```
|
|
[text](URL) to refer to any valid URL
|
|
```
|
|
|
|
but a feature adapted from kramdown is also available, e.g.
|
|
|
|
```
|
|
{{RFC8200}} to refer to an RFC
|
|
{{BCP198}} to refer to an IETF Best Current Practice
|
|
{{STD86}} to refer to an IETF Internet Standard
|
|
{{I-D.ietf-v6ops-xxx}} to refer to an Internet Draft
|
|
{{draft-ietf-v6ops-xxx}} the same!
|
|
{{Last Section}} to refer to a section in the present chapter
|
|
{{2. Addresses}} to refer to a section in another chapter (the single space is required)
|
|
```
|
|
|
|
Such references will be fixed up by the next run of makeBook, since they
|
|
are unknown to GitHub's built-in markdown. There is some checking of the
|
|
RFCs, draft names, etc. (but only when makeBook has web access).
|
|
|
|
Note that references will be surrounded by square brackets thus:
|
|
\[[RFC8200](https://www.rfc-editor.org/info/rfc8200)\]. If you want them
|
|
without square brackets for grammatical reasons, such as using
|
|
[RFC8200](https://www.rfc-editor.org/info/rfc8200) as a noun, use
|
|
*three* curly brackets:
|
|
|
|
```
|
|
{{{RFC8200}}}
|
|
{{{2. Addresses}}}
|
|
```
|
|
|
|
Diagrams can be ASCII art when applicable, using `~~~` before and after,
|
|
e.g.:
|
|
|
|
```
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
|Version| Traffic Class | Flow Label |
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
| Payload Length | Next Header | Hop Limit |
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
| etc. |
|
|
```
|
|
|
|
The
|
|
[*mermaid* tool](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams)
|
|
can be used for flow charts and state diagrams, e.g.:
|
|
|
|
````
|
|
```mermaid
|
|
flowchart LR
|
|
S[Start here] --> E[End here]
|
|
```
|
|
````
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
S[Start here] --> E[End here]
|
|
```
|
|
|
|
Other types of diagrams could be included using SVG generated by a
|
|
separate drawing tool such as *dia*, with the SVG file also stored here
|
|
on GitHub, e.g.:
|
|
|
|
```
|
|
<img src="./diag.svg" alt="Disk feeding tape">
|
|
```
|
|
|
|
<img src="./diag.svg" alt="Disk feeding tape">
|
|
|
|
Please add alternate text to help people with visual difficulties.
|
|
|
|
Existing diagrams in PNG or JPG format can be inserted in the same way,
|
|
although SVG has the advantage of being a text format "under the
|
|
covers".
|
|
|
|
<!-- Link lines generated automatically; do not delete -->
|
|
|
|
### [<ins>Previous</ins>](Section%20Template.md) [<ins>Next</ins>](Last%20Section.md) [<ins>Chapter Contents</ins>](99.%20Chapter%20Template.md)
|