mirror of
https://codeberg.org/Codeberg/Documentation.git
synced 2026-08-15 14:53:29 -07:00
a8f296562d
Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/841 Reviewed-by: Gusted <gusted@noreply.codeberg.org>
182 lines
5.1 KiB
Markdown
182 lines
5.1 KiB
Markdown
---
|
|
eleventyNavigation:
|
|
key: IntroductionToMarkdown
|
|
title: Introduction to Markdown
|
|
parent: Markdown
|
|
order: 20
|
|
---
|
|
|
|
<!-- markdownlint-disable MD049 MD050 -->
|
|
|
|
Markdown files are basically normal text files. The file extension `.md` specifies that a file can be rendered as Markdown.
|
|
You can also use Markdown in many parts of Codeberg (Issues, Pull Requests, etc.).
|
|
|
|
## Text section
|
|
|
|
To write a Markdown file, simply create a new file, and edit it with a text editor of your choice.
|
|
Markdown doesn't consider single line breaks as the start of a new paragraph.
|
|
You can write all your text into one long line or introduce a new line every once in a while.
|
|
It is common practice to introduce a new line at around 80 characters to enable users to easily read the plain
|
|
un-rendered version of the Markdown file.
|
|
However, it's recommended to make a line break in Markdown when it makes sense, e.g. at the end of a sentence.
|
|
It makes diffs easier to understand, as the context of the complete sentence is preserved.
|
|
|
|
If you want to start a new paragraph, use two or more empty new lines to separate the text.
|
|
Beware that when rendering with Forgejo, line breaks are rendered differently in repos and comment fields.
|
|
For example, one line break in a comment leads to a new paragraph.
|
|
|
|
### Highlighting text sections
|
|
|
|
In paragraphs, it is possible to highlight passages using **bold** and _italics_.
|
|
|
|
### Bold
|
|
|
|
To make text bold, use two asterisks at the start of the section you want to highlight `**`
|
|
At the end of the section, add another two asterisks `**`.
|
|
Alternatively you can use two underscore characters `__` at the beginning and end of the section
|
|
to get the same effect.
|
|
|
|
Here are a few examples.
|
|
|
|
```markdown
|
|
This is **bold text**.
|
|
```
|
|
|
|
This gets rendered as
|
|
|
|
This is **bold text**.
|
|
|
|
<!-- prettier-ignore-start -->
|
|
```markdown
|
|
This is also __bold text__.
|
|
```
|
|
|
|
This gets rendered as
|
|
|
|
This is also __bold text__.
|
|
<!-- prettier-ignore-end -->
|
|
|
|
### Italics
|
|
|
|
To make text italic use one asterisk at the start of the section you want to highlight `*`
|
|
At the end of the section, add another asterisk `*`.
|
|
Alternatively you can use one underscore character `_` at the beginning and end of the section
|
|
to get the same effect.
|
|
|
|
Here are a few examples.
|
|
|
|
<!-- prettier-ignore-start -->
|
|
```markdown
|
|
This is *italic text*.
|
|
```
|
|
|
|
This gets rendered as
|
|
|
|
This is *italic text*.
|
|
<!-- prettier-ignore-end -->
|
|
|
|
```markdown
|
|
This is also _italic text_.
|
|
```
|
|
|
|
This gets rendered as
|
|
|
|
This is also _italic text_.
|
|
|
|
### Strikethrough
|
|
|
|
To strikethrough use `~~` around the text.
|
|
|
|
```markdown
|
|
This is ~~strikethrough text~~.
|
|
```
|
|
|
|
is rendered as
|
|
|
|
This is ~~strikethrough text~~.
|
|
|
|
### Monospaced font (code)
|
|
|
|
_For preformatted code blocks, see "[Preformatted Text](/markdown/preformatted-text)."_
|
|
|
|
It is a common convention in technical writing to use a monospaced or
|
|
fixed-width font to indicate code, literal text to be typed at a command
|
|
prompt, or program output.
|
|
|
|
To create a span of inline text with a monospaced font, wrap the text in
|
|
backtick (\`) characters, like so:
|
|
|
|
```markdown
|
|
This text contains an `inline code` span.
|
|
```
|
|
|
|
which renders as
|
|
|
|
This text contains an `inline code` span.
|
|
|
|
### Footnotes
|
|
|
|
To add footnotes use the syntax `[^name]` inline, and define them with:<br>
|
|
`[^name]:text.`
|
|
|
|
```markdown
|
|
Text with a footnote.[^1]
|
|
|
|
[^1]: A footnote.
|
|
```
|
|
|
|
is rendered as
|
|
|
|
|
|
|
|
## Forgejo-specific formatting
|
|
|
|
### Emoticons
|
|
|
|
Text may contain references to emoticons which are rendered as a small image, similar to an emoji.
|
|
You can render these by typing the name of the emoticon you want to use, surrounded by colons (`:`), like this `:codeberg:`.
|
|
|
|
Some examples are `:codeberg:` which is rendered as
|
|
<img
|
|
src="https://codeberg.org/assets/img/emoji/codeberg.png"
|
|
class="codeberg-design" style="border-style:none;width:1em;height:1em"
|
|
alt="The Codeberg mountain" />
|
|
and `:forgejo:` which is rendered as
|
|
<img
|
|
src="https://codeberg.org/assets/img/emoji/forgejo.png"
|
|
class="codeberg-design" style="border-style:none;height:1em;width:1em"
|
|
alt="The forgejo f letter" />.
|
|
|
|
### Referencing issues and pull requests
|
|
|
|
Issues and pull requests in Codeberg/Forgejo can be referenced in the comments of an issue or a pull request by using a
|
|
hash `#` followed by the number of the issue or pull request.
|
|
The renderer will then include a link to the referenced issue into the comment.
|
|
After that, a link to the comment containing the reference will be added to the issues referenced in this way.
|
|
|
|
### Checkboxes
|
|
|
|
You can add checkboxes to comments by using list items with a space surrounded by square brackets `- [ ]`. These can be
|
|
checked/unchecked later without editing the comment.
|
|
This can for example be useful when creating a Todo list.
|
|
|
|
### Mermaid diagrams
|
|
|
|
Forgejo can render [Mermaid diagrams](https://mermaid-js.github.io/mermaid/#/) in issues, pull requests and comments.
|
|
|
|
Use the render hint `mermaid` on the preformatted section containing the code of the mermaid diagram.
|
|
|
|
E.g.
|
|
|
|
````markdown
|
|
```mermaid
|
|
graph TD;
|
|
A(stuff)-->B[one];
|
|
A-->C[two];
|
|
A-->D[three];
|
|
```
|
|
````
|
|
|
|
is rendered to:
|
|
|
|
|