becarpenter-book6/99. Chapter Template/Markdown Usage.md

## 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)