From 1ec9cad276c87e6f2bcf78945ae59b13583a9864 Mon Sep 17 00:00:00 2001
From: ernstki <ernstki@noreply.codeberg.org>
Date: Mon, 15 Jun 2026 19:29:57 +0200
Subject: [PATCH] docs: expand "preformatted text" section w/ verbatim examples

This makes it more beginner-friendly, because it shows exactly what to
type.

Signed-off-by: ernstki <ernstki@noreply.codeberg.org>
---
 content/markdown/preformatted-text.md | 83 +++++++++++++++++++++------
 1 file changed, 66 insertions(+), 17 deletions(-)

diff --git a/content/markdown/preformatted-text.md b/content/markdown/preformatted-text.md
index a490474..ddf7afb 100644
--- a/content/markdown/preformatted-text.md
+++ b/content/markdown/preformatted-text.md
@@ -6,29 +6,63 @@ eleventyNavigation:
   order: 50
 ---
 
-There are two ways to use monospace preformatted text within your Markdown document:
+<!-- TODO: _For inline code spans, see [Introduction to Markdown § Monospaced font (code)](../introduction-to-markdown#monospaced-font-code)._ -->
 
-- Using indentation
-- Using one or more backticks at the beginning and the end of a preformatted section
+In technical writing, code blocks, commands to be typed, or verbatim output are commonly represented by monospaced or fixed-width fonts. These blocks considered _preformatted_ text, because internal whitespace is preserved.
+
+There are three ways to use preformatted text within your Markdown documents:
+
+- [Indenting](#using-indentation) each line of a block of text by 4 or more spaces, or a tab character.
+- Beginning and ending a block of text with a row of 3 or more backtick (\`) or tilde (~) characters, referred to as a ["fenced" code block](#using-backticks).
+- Wrapping HTML `<pre></pre>` tags around a block of text.
+
+Fenced code blocks can optionally [specify a rendering hint](#rendering-hints) to apply syntax highlighting to the block.
 
 ## Using indentation
 
-You can preformat a section of text or code by indenting the code with 4 or more spaces, or a tab.
+You can preformat a block of text or code by indenting the code with **4 or more spaces, or a tab character**.
 
-Using indentation, it's not possible to add a rendering hint. It's also not possible to preformat text within a line
-using this syntax.
+Example:
+
+```
+    This block of text
+    will be preformatted
+         and internal whitespace will be preserved.
+```
+
+Result:
+
+```
+This block of text
+will be preformatted
+     and internal whitespace will be preserved.
+```
+
+Using indentation, it's not possible to add a rendering hint, so the block will not be syntax-highlighted.
 
 Indentation-based preformatting sometimes causes false positives where text is
-preformatted that isn't supposed to. For this reason, it is disabled in some
+uninentionally preformatted; for this reason, it is disabled in some
 Markdown renderers, including in Codeberg Documentation.
 
 ## Using backticks
 
-A better way of preformatting a section of text is by starting a section of text with one or more backtick characters.
+As an alternative, you can create blocks of preformatted text by starting and ending the block with a row of 3 or more backtick (\`) or tilde (~) characters. There should be an equal number of these characters at both start and end.
 
-Here, we use 3 backtick characters on its own line, then our text, then another line containing 3 more backticks.
+Here, we use 3 backtick characters (\`\`\`) on their own line, then our text, then another line containing another 3 backticks. 
 
-```markdown
+~~~
+```
+this
+is
+displayed
+as
+preformatted
+```
+~~~
+
+The result:
+
+```
 this
 is
 displayed
@@ -36,16 +70,21 @@ as
 preformatted
 ```
 
-You can also preformat a section of text within a line using backtick syntax.
-The following text is for example `preformatted` by using the backtick syntax.
-
 ### Rendering hints
 
 Sometime renderers use hints to syntax highlight the code in a preformatted section.
 
-To provide a hint, simply add the language name at the end of the introductory backtick(s).
+To provide a hint, simply add the language name at the end of the introductory backtick(s). For example, using `shell` as the hint will tell the renderer that the given code should be highlighted as a shell script:
 
-For example, using `shell` as the hint will tell the renderer that the given code should be highlighted as a shell script:
+~~~
+```shell
+#!/bin/bash
+
+echo "Hello world"
+```
+~~~
+
+The result:
 
 ```shell
 #!/bin/bash
@@ -53,10 +92,20 @@ For example, using `shell` as the hint will tell the renderer that the given cod
 echo "Hello world"
 ```
 
-The same thing would be rendered without syntax highlighting if the hint is not given:
+If the hint is omitted, the section will be rendered without syntax highlighting:
 
-```text
+~~~
+```
 #!/bin/bash
 
 echo "Hello world"
 ```
+~~~
+
+The result:
+
+```
+#!/bin/bash
+
+echo "Hello world"
+```
\ No newline at end of file