From: Thomas Lamprecht Date: Mon, 5 Jul 2021 12:16:37 +0000 (+0200) Subject: add markdown primer for gui notes onlineHelp X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=commitdiff_plain;h=44d211d2fcd9dd446fb7f06826dbb208c54c799b add markdown primer for gui notes onlineHelp Signed-off-by: Thomas Lamprecht --- diff --git a/markdown-primer.adoc b/markdown-primer.adoc new file mode 100644 index 0000000..dbeb270 --- /dev/null +++ b/markdown-primer.adoc @@ -0,0 +1,174 @@ +Markdown Primer +=============== + +[quote, John Gruber, https://daringfireball.net/projects/markdown/] +____ +Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you +to write using an easy-to-read, easy-to-write plain text format, then convert +it to structurally valid XHTML (or HTML). +____ + +The {pve} web-interface has support for using Markdown to rendering rich text +formatting in node and virtual guest notes. + +{pve} supports CommonMark with most extensions of GFM (GitHub Flavoured Markdown), +like tables or task-lists. + +[[markdown_basics]] + +Markdown Basics +--------------- + +Note that we only describe the basics here, please search the web for more +extensive resources, for example on https://www.markdownguide.org/ + +Headings +~~~~~~~~ + +---- +# This is a Heading h1 +## This is a Heading h2 +##### This is a Heading h5 +---- + + +Emphasis +~~~~~~~~ + +Use `*text*` or `_text_` for emphasis. + +Use `**text**` or `__text__` for bold, heavy-weight text. + +Combinations are also possible, for example: + +---- +_You **can** combine them_ +---- + +Links +~~~~~ + +You can use automatic detection of links, for example, +`https://forum.proxmox.com/` would transform it into a clickable link. + +You can also control the link text, for example: + +---- +Now, [the part in brackets will be the link text](https://forum.proxmox.com/). +---- + +Lists +~~~~~ + +Unordered Lists +^^^^^^^^^^^^^^^ + +Use `*` or `-` for unordered lists, for example: + +---- +* Item 1 +* Item 2 +* Item 2a +* Item 2b +---- + +Adding an indentation can be used to created nested lists. + +Ordered Lists +^^^^^^^^^^^^^ + +---- +1. Item 1 +1. Item 2 +1. Item 3 + 1. Item 3a + 1. Item 3b +---- + +NOTE: The integer of ordered lists does not need to be correct, they will be numbered automatically. + +Task Lists +^^^^^^^^^^ + +Task list use a empty box `[ ]` for unfinished tasks and a box with an `X` for finished tasks. + +For example: + +---- +- [X] First task already done! +- [X] Second one too +- [ ] This one is still to-do +- [ ] So is this one +---- + +Tables +~~~~~~ + +Tables use the pipe symbol `|` to separate columns, and `-` to separate the +table header from the table body, in that separation one can also set the text +alignment, making one column left-, center-, or right-aligned. + +---- +| Left columns | Right columns | Some | More | Cols.| Centering Works Too +| ------------- |--------------:|--------|------|------|:------------------:| +| left foo | right foo | First | Row | Here | >center< | +| left bar | right bar | Second | Row | Here | 12345 | +| left baz | right baz | Third | Row | Here | Test | +| left zab | right zab | Fourth | Row | Here | ☁️☁️☁️ | +| left rab | right rab | And | Last | Here | The End | +---- + +Note that you do not need to align the columns nicely with white space, but that makes +editing tables easier. + +Block Quotes +~~~~~~~~~~~~ + +You can enter block quotes by prefixing a line with `>`, similar as in plain-text emails. + +---- +> Markdown is a lightweight markup language with plain-text-formatting syntax, +> created in 2004 by John Gruber with Aaron Swartz. +> +>> Markdown is often used to format readme files, for writing messages in online discussion forums, +>> and to create rich text using a plain text editor. +---- + + +Code and Snippets +~~~~~~~~~~~~~~~~~ + +You can use backticks to avoid processing for a few word or paragraphs. That is useful for +avoiding that a code or configuration hunk gets mistakenly interpreted as markdown. + +Inline code +^^^^^^^^^^^ + +Surrounding part of a line with single backticks allows to write code inline, +for examples: + +---- +This hosts IP address is `10.0.0.1`. +---- + +Whole blocks of code +^^^^^^^^^^^^^^^^^^^^ + +For code blocks spanning several lines you can use triple-backticks to start +and end such a block, for example: + +---- +``` +# This is the network config I want to remember here +auto vmbr2 +iface vmbr2 inet static + address 10.0.0.1/24 + bridge-ports ens20 + bridge-stp off + bridge-fd 0 + bridge-vlan-aware yes + bridge-vids 2-4094 + +``` +---- + diff --git a/pve-admin-guide.adoc b/pve-admin-guide.adoc index 3614c03..f2cb040 100644 --- a/pve-admin-guide.adoc +++ b/pve-admin-guide.adoc @@ -309,6 +309,9 @@ Firewall Macro Definitions include::pve-firewall-macros.adoc[] +:leveloffset: 1 +[appendix] +include::markdown-primer.adoc[] :leveloffset: 1 [appendix]