markdown-primer.adoc

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