Skip to content

Latest commit

 

History

History
125 lines (91 loc) · 4.09 KB

Markdown Usage.md

File metadata and controls

125 lines (91 loc) · 4.09 KB
Raw

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 1: References will be surrounded by square brackets thus: [RFC8200]. If you want them without square brackets for grammatical reasons, such as using RFC 8200 as a noun, use three curly brackets:

  {{{RFC8200}}}
  {{{2. Addresses}}}

Note 2: If you string several references together, e.g.,

  {{RFC4291}}{{RFC8200}}

they will be shown in a single pair of square brackets with commas: [RFC4291, RFC 8200].

Note 3: If you need to refer to a specific section of an RFC and you know the appropriate hashtag, you can use this format:

  Section 2.5.6 of {{{RFC3513#section-2.5.6}}}

However, makeBook cannot algorithmically create or check the hashtag, so you must get it right.

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.                             |

More complex diagrams may be included using PNG generated by a separate drawing tool such as mermaid or dia, with the PNG file also stored here on GitHub, e.g.:

Source of mermaid diagram:

```mermaid
flowchart LR
    S[Start here] --> E[End here]
```

Embedded in markdown as a PNG file generated by mermaid.live:

<img src="./example1.png" width=250 alt="Start here, end here">

Displayed thus:

Start here, end here

Example generated with dia:

<img src="./diag.png" alt="Disk feeding tape">

Disk feeding tape

Please add alternate text to help people with visual difficulties.

Note 4: Direct use of mermaid in markdown source is not recommended, as it causes difficulty when generating a PDF version of book6.

Note 5: Earlier versions of this section recommended SVG format. This has been removed since SVG causes difficulty when generating a PDF version of book6.

Existing diagrams in JPG format can be inserted in the same way.

Previous Next Top