3.2 KiB
Markdown Usage
The basics of using the GitHub dialect of markdown are here. 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]. If you want them without square brackets for grammatical reasons, such as using 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 can be used for flow charts and state diagrams, e.g.:
```mermaid
flowchart LR
S[Start here] --> E[End here]
```
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">
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".