docs/markdown-primer.rst

   1 .. _markdown-primer:
   2
   3 Markdown Primer
   4 ===============
   5
   6   "Markdown is a text-to-HTML conversion tool for web writers. Markdown allows
   7   you to write using an easy-to-read, easy-to-write plain text format, then
   8   convertit to structurally valid XHTML (or HTML)."
   9
  10   --  John Gruber, https://daringfireball.net/projects/markdown/
  11
  12
  13 The "Notes" panel of the Proxmox Backup Server web-interface supports
  14 rendering Markdown text.
  15
  16 Proxmox Backup Server supports CommonMark with most extensions of GFM (GitHub
  17 Flavoured Markdown), like tables or task-lists.
  18
  19 .. _markdown_basics:
  20
  21 Markdown Basics
  22 ---------------
  23
  24 Note that we only describe the basics here. Please search the web for more
  25 extensive resources, for example on https://www.markdownguide.org/
  26
  27 Headings
  28 ~~~~~~~~
  29
  30 .. code-block:: md
  31
  32   # This is a Heading h1
  33   ## This is a Heading h2
  34   ##### This is a Heading h5
  35
  36
  37 Emphasis
  38 ~~~~~~~~
  39
  40 Use ``*text*`` or ``_text_`` for emphasis.
  41
  42 Use ``**text**`` or ``__text__`` for bold, heavy-weight text.
  43
  44 Combinations are also possible, for example:
  45
  46 .. code-block:: md
  47
  48   _You **can** combine them_
  49
  50
  51 Links
  52 ~~~~~
  53
  54 You can use automatic detection of links. For example,
  55 ``https://forum.proxmox.com/`` would transform it into a clickable link.
  56
  57 You can also control the link text, for example:
  58
  59 .. code-block:: md
  60
  61   Now, [the part in brackets will be the link text](https://forum.proxmox.com/).
  62
  63 Lists
  64 ~~~~~
  65
  66 Unordered Lists
  67 ^^^^^^^^^^^^^^^
  68
  69 Use ``*`` or ``-`` for unordered lists, for example:
  70
  71 .. code-block:: md
  72
  73   * Item 1
  74   * Item 2
  75   * Item 2a
  76   * Item 2b
  77
  78
  79 You can create nested lists by adding indentation.
  80
  81 Ordered Lists
  82 ^^^^^^^^^^^^^
  83
  84 .. code-block:: md
  85
  86   1. Item 1
  87   1. Item 2
  88   1. Item 3
  89     1. Item 3a
  90     1. Item 3b
  91
  92 NOTE: The integer of ordered lists does not need to be correct, they will be numbered automatically.
  93
  94 Task Lists
  95 ^^^^^^^^^^
  96
  97 Task lists use a empty box ``[ ]`` for unfinished tasks and a box with an `X` for finished tasks.
  98
  99 For example:
 100
 101
 102 .. code-block:: md
 103
 104   - [X] First task already done!
 105   - [X] Second one too
 106   - [ ] This one is still to-do
 107   - [ ] So is this one
 108
 109 Tables
 110 ~~~~~~
 111
 112 Tables use the pipe symbol ``|`` to separate columns, and ``-`` to separate the
 113 table header from the table body. In that separation, you can also set the text
 114 alignment, making one column left-, center-, or right-aligned.
 115
 116
 117 .. code-block:: md
 118
 119   | Left columns  | Right columns |  Some  | More | Cols.| Centering Works Too
 120   | ------------- |--------------:|--------|------|------|:------------------:|
 121   | left foo      | right foo     | First  | Row  | Here | >center<           |
 122   | left bar      | right bar     | Second | Row  | Here | 12345              |
 123   | left baz      | right baz     | Third  | Row  | Here | Test               |
 124   | left zab      | right zab     | Fourth | Row  | Here | ☁️☁️☁️              |
 125   | left rab      | right rab     | And    | Last | Here | The End            |
 126
 127 Note that you do not need to align the columns nicely with white space, but that makes
 128 editing tables easier.
 129
 130 Block Quotes
 131 ~~~~~~~~~~~~
 132
 133 You can enter block quotes by prefixing a line with ``>``, similar as in plain-text emails.
 134
 135 .. code-block:: md
 136
 137   > Markdown is a lightweight markup language with plain-text-formatting syntax,
 138   > created in 2004 by John Gruber with Aaron Swartz.
 139   >
 140   >> Markdown is often used to format readme files, for writing messages in online discussion forums,
 141   >> and to create rich text using a plain text editor.
 142
 143 Code and Snippets
 144 ~~~~~~~~~~~~~~~~~
 145
 146 You can use backticks to avoid processing a group of words or paragraphs. This
 147 is useful for preventing a code or configuration hunk from being mistakenly
 148 interpreted as markdown.
 149
 150 Inline Code
 151 ^^^^^^^^^^^
 152
 153 Surrounding part of a line with single backticks allows you to write code
 154 inline, for examples:
 155
 156 .. code-block:: md
 157
 158   This hosts IP address is `10.0.0.1`.
 159
 160 Entire Blocks of Code
 161 ^^^^^^^^^^^^^^^^^^^^^
 162
 163 For code blocks spanning several lines, you can use triple-backticks to start
 164 and end such a block, for example:
 165
 166 .. code-block:: md
 167
 168   ```
 169   # This is the network config I want to remember here
 170   auto vmbr2
 171   iface vmbr2 inet static
 172           address 10.0.0.1/24
 173           bridge-ports ens20
 174           bridge-stp off
 175           bridge-fd 0
 176           bridge-vlan-aware yes
 177           bridge-vids 2-4094
 178
 179   ```