From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 74016981D; Fri, 1 Apr 2022 12:20:17 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 6720125767; Fri, 1 Apr 2022 12:19:47 +0200 (CEST) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [94.136.29.106]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id A1E7625754; Fri, 1 Apr 2022 12:19:45 +0200 (CEST) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 7A568459C9; Fri, 1 Apr 2022 12:19:45 +0200 (CEST) From: Stefan Sterz To: pbs-devel@lists.proxmox.com, pve-devel@lists.proxmox.com Date: Fri, 1 Apr 2022 12:19:05 +0200 Message-Id: <20220401101908.1154385-2-s.sterz@proxmox.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220401101908.1154385-1-s.sterz@proxmox.com> References: <20220401101908.1154385-1-s.sterz@proxmox.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL -0.000 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record T_SCC_BODY_TEXT_LINE -0.01 - Subject: [pve-devel] [PATCH proxmox-backup v4 1/4] fix #3067: docs: add markdown primer from pve to pbs X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 01 Apr 2022 10:20:17 -0000 this copies the markdown primer from the pve docs to allow access to it via the help buttons in the gui Signed-off-by: Stefan Sterz --- docs/index.rst | 1 + docs/markdown-primer.rst | 178 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 179 insertions(+) create mode 100644 docs/markdown-primer.rst diff --git a/docs/index.rst b/docs/index.rst index daa61249..713b09d8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -50,6 +50,7 @@ in the section entitled "GNU Free Documentation License". file-formats.rst backup-protocol.rst calendarevents.rst + markdown-primer.rst glossary.rst GFDL.rst diff --git a/docs/markdown-primer.rst b/docs/markdown-primer.rst new file mode 100644 index 00000000..01ce1d6d --- /dev/null +++ b/docs/markdown-primer.rst @@ -0,0 +1,178 @@ +.. _markdown-primer: + +Markdown Primer +=============== + + "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 + convertit to structurally valid XHTML (or HTML)." + + -- John Gruber, https://daringfireball.net/projects/markdown/ + + +The Proxmox Backup Server (PBS) web-interface has support for using Markdown to +rendering rich text formatting in node and virtual guest notes. + +PBS 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 +~~~~~~~~ + +.. code-block:: md + + # 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: + +.. code-block:: md + + _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: + +.. code-block:: md + + Now, [the part in brackets will be the link text](https://forum.proxmox.com/). + +Lists +~~~~~ + +Unordered Lists +^^^^^^^^^^^^^^^ + +Use ``*`` or ``-`` for unordered lists, for example: + +.. code-block:: md + + * Item 1 + * Item 2 + * Item 2a + * Item 2b + + +Adding an indentation can be used to created nested lists. + +Ordered Lists +^^^^^^^^^^^^^ + +.. code-block:: md + + 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: + + +.. code-block:: md + + - [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. + + +.. code-block:: md + + | 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. + +.. code-block:: md + + > 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: + +.. code-block:: md + + 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: + +.. code-block:: md + + ``` + # 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 + + ``` -- 2.30.2