2.4 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.
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
{{{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.
Diagrams can be ASCII art when applicable, 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">
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".