18cbfe76e8
Inline `code spans` are now mentioned alongsize bold and italics where it makes the most sense to have them, and the preformatted text document has been updated to show the raw Markdown for each example. Each of these documents also cross-references the other, as an aid to the reader. Several sections in `preformatted-text.md` have been renamed for clarity, with `<a id="old-section-title"></a>` anchors such that inbound links with [fragment identifiers](https://en.wikipedia.org/wiki/URI_fragment#Basics) (direct section links) should not break as a result. Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/805 Reviewed-by: Robert Wolff <mahlzahn@posteo.de>
3 KiB
| eleventyNavigation | ||||||||
|---|---|---|---|---|---|---|---|---|
|
In technical writing, code blocks, commands to be typed verbatim, or program output are commonly represented by monospaced or fixed-width fonts. These blocks are considered preformatted, because internal whitespace is to be preserved.
There are three ways to use preformatted text within your Markdown documents:
- Indenting 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.
- Wrapping HTML
<pre></pre>tags around a block of text.
Fenced code blocks can optionally specify a rendering hint to apply syntax highlighting to the block.
Indented blocks
You can preformat a block of text or code by indenting the code with 4 or more spaces, or a tab character.
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 unintentionally preformatted; for this reason, it is disabled in some Markdown renderers, including in Codeberg Documentation.
Fenced code blocks
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 their own line, then our text, then another line containing another 3 backticks.
```
this
is
displayed
as
preformatted
```
The result:
this
is
displayed
as
preformatted
Rendering hints (syntax highlighting)
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). 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:
#!/bin/bash
echo "Hello world"
If the hint is omitted, the section will be rendered without syntax highlighting:
```
#!/bin/bash
echo "Hello world"
```
The result:
#!/bin/bash
echo "Hello world"