Docu review done: Mon 03 Jul 2023 16:40:07 CEST

Table of content

General

Because no one can read your mind (yet)

Online documentation

Another online documentation

Internal header links

You can use the direct header name or you use the id from an html a tag

And depending on the markdown processors also custom heading ids

1. [Table of Contents](#table-of-contens)
2. [Headers](#headers)
...

Headers

also called headings

# This is an <h1> tag
## This is an <h2> tag
###### This is an <h6> tag

With HTML tag<a id="IDNAME"></a> or inline custom IDs #+ <HEEADER_NAME> {#<INLINE_ID>}, you can to have special characters in the header and still create a link

HTML tag sample:

<a id="headertag1"></a>
# This-is_an(<h1>) tag
<a id="headertag2"></a>
## This-is_an(<h2>) tag
<a id="headertag6"></a>
###### This-is_an(<h6>) tag

inline custom IDs sample:

# This-is_an(<h1>) tag {#headertag1}
## This-is_an(<h2>) tag {#headertag2}
###### This-is_an(<h6>) tag {#headertag6}

So if you have HTML tag/inline custom ID in place, you can use that one as a pointer like this:

[This-is_an(<h1>) tag](#headertag1)
[This-is_an(<h2>) tag](#headertag2)
[This-is_an(<h6>) tag](#headertag6)

Headers Best Practice

For compactibility, put blank lines before and after headers

Section above

## Headers Best Practice

For compactibility,....

Horizontal Rule

---

Emphasis

*This text will be italic*
_This will also be italic_

**This text will be bold**
__This will also be bold__

_You **can** combine them_

This text will be italic This will also be italic

This text will be bold This will also be bold

You can combine them

Lists

Unordered

* Item 1
* Item 2
    * Item 2a
    * Item 2b
  • Item 1
  • Item 2
    • Item 2a
    • Item 2b

Ordered

1. Item 1
2. Item 2
3. Item 3
    1. Item 3a
    2. Item 3b
  1. Item 1
  2. Item 2
  3. Item 3
    1. Item 3a
    2. Item 3b

Mixed

1. Item 1
1. Item 2
1. Item 3
    * Item 3a
    * Item 3b
  1. Item 1
  2. Item 2
  3. Item 3
    • Item 3a
    • Item 3b

Images

Inline style

Remote file: ![RemoteFile](https://gitea.sons-of-sparda.at/assets/img/logo.svg)

Locale file![LocaleFile](/images/mdadm_raid6.png)

Remote file: RemoteFile

Locale file: LocaleFile

The local file will only work if the path what you have specified exists in the same directory where the markdown file is stored Other wise it will look like above, where you just get the link shown but not he image it self

Reference style

Reference style remote file: ![RemoteFile][refstlogo]

[refstlogo]: https://gitea.sons-of-sparda.at/assets/img/logo.svg "Reference style logo"

Reference style remote file: RemoteFile

Links

Autodetect of url:                 https://github.com
Inline style:                      [Inlinestype-Github](https://github.com)
Inline style of url with title:    [Inlinestype-Github with title](https://github.com "GitHub Link")
External link mapping:             [GitHub](http://github.com)
Internal link in md:               [InternalMDLink](#links)
Internal link in md with spaces:   [InternalMDLinkWithSpaces](#inline-code)
Internal link in md with index:    [InternalMDLinkWithIndex](#pro-1)
Internal link in md with html tag: [InternalMDLinkWithHtmlTag](#imdlwht)
Reference link style:              [Arbitrary case-insensitive reference text] or [1]
Email link:                        <fancy-mail-link@sons-of-sparda.at>
Link on images:                    [![gitea svg](https://gitea.sons-of-sparda.at/assets/img/logo.svg "Link to gitea home")](https://gitea.sons-of-sparda.at)
[arbitrary case-insensitive reference text]: https://github.com
[1]: https://github.com
Link typeUrl
Autodetect of urlhttps://github.com
Inline styleInlinestype-Github
Inline style of url with titleInlinestype-Github with title
External link mappingGitHub
Internal link in mdInternalMDLink
Internal link in md with spacesInternalMDLinkWithSpaces
Internal link in md with indexInternalMDLinkWithIndex
Internal link in md with html tagInternalMDLinkWithHtmlTag
Reference link styleArbitrary case-insensitive reference text or 1
Email linkfancy-mail-link@sons-of-sparda.at
Link on imagesgitea svg

You can also point to inline html IDs. You create the inline link as above

[My first linline link](#mfll)

Markdown applications don’t agree on how to handle spaces in the middle of a URL. For compatibility, try to URL encode any spaces with %20.

[link](https://sons-of-sparda.at/site%20does%20not%20exist)

link

Then you create somewhere your ID tag inside the md file:

<a id="mfll"></a>

Links to IDs can be very helpful when:

  • your header is very long
  • your header contains special characters
  • your header exists multiple times (different solution for that below)

Inline custom IDs for headings

Many Markdown processors support custom IDs for headings — some Markdown processors automatically add them. Adding custom IDs allows you to link directly to headings and modify them with CSS. To add a custom heading ID, enclose the custom ID in curly braces on the same line as the heading.

### Inline custom IDs for headings {#icifh}

To link to a heading id, use the id as you would do normaly with a heading

If you have multiple times the same header, you can also create links based on index number of same header.

- [Option1](#option1)
  - [Pro](#pro)
  - [Con](#con)
- [Option2](#option2)
  - [Pro](#pro-1)
  - [Con](#con-1)
- [Option3](#option3)
  - [Pro](#pro-2)
  - [Con](#con-2)

# Option1
## Pro
## Con

# Option2
## Pro
## Con

# Option3
## Pro
## Con
Option1
Pro
Con
Option2
Pro
Con
Option3
Pro
Con

Footnotes

Footnotes allow you to add notes and references without cluttering the body of the document. When you create a footnote, a superscript number with a link appears where you added the footnote reference. Readers can click the link to jump to the content of the footnote at the bottom of the page.

To create a footnote reference, add a caret and an identifier inside brackets [^1]. Identifiers can be numbers or words, but they can’t contain spaces or tabs. Identifiers only correlate the footnote reference with the footnote itself — in the output, footnotes are numbered sequentially.

Add the footnote using another caret and number inside brackets with a colon and text [^1]: My footnote.. You don’t have to put footnotes at the end of the document. You can put them anywhere except inside other elements like lists, block quotes, and tables.

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    `{ my code }`

    Add as many paragraphs as you like.

Here’s a simple footnote,1 and here’s a longer one.2

1

This is the first footnote.

2

Here’s one with multiple paragraphs and code.

Indent paragraphs to include them in the footnote.

{ my code }

Add as many paragraphs as you like.

Definition Lists

Some Markdown processors allow you to create definition lists of terms and their corresponding definitions. To create a definition list, type the term on the first line. On the next line, type a colon followed by a space and the definition.

First Term
: This is the definition of the first term.

Second Term
: This is one definition of the second term.
: This is another definition of the second term.

First Term : This is the definition of the first term.

Second Term : This is one definition of the second term. : This is another definition of the second term.

Blockquotes

As Kanye West said:

> We're living the future so
> the present is our past.

As Kanye West said:

We’re living the future so the present is our past.

Nested blockquoates

> Blockquoats 1
>
>> Nested Blockquats 2

Blockquoats 1

Nested Blockquats 2

Blockquotes Best Practice

For compactibility, put blank lines before and after blockquotes

Line 1

> my blockquote

Line 3

Inline code

I think you should use an
`<addr>` element here instead.

I think you should use an <addr> element here instead.

Task Lists

- [x] @mentions, #refs, [links](markdown.md#task-lists), **formatting**, and <del>tags</del> supported
- [x] list syntax required (any unordered or ordered list supported)
- [x] this is a complete item
- [ ] this is an incomplete item
  • @mentions, #refs, links, formatting, and tags supported
  • list syntax required (any unordered or ordered list supported)
  • this is a complete item
  • this is an incomplete item

Tables

First Header | Second Header
------------ | -------------
Content from cell 1 | Content from cell 2 | Content from cell 3
Content in the first column | Content in the second column |  Content in the third column
*Still* | `renders` | **nicely**
First HeaderSecond HeaderThird Header
Content from cell 1Content from cell 2Content from cell 3
Content in the first columnContent in the second columnContent in the third column
Stillrendersnicely

Colons can be used to align columns

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |
TablesAreCool
col 3 isright-aligned$1600
col 2 iscentered$12
zebra stripesare neat$1

To create a new line sinside of a table, you can use the <br> tag like that:

Col1 | Col2 | Col3
---- | ---- | ----
one line | one line | first line <br> second line <br> third line
first line <br> second line | one line | one line
one line | first line <br> second line | one line
one line | one line | one very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very long line with no new line
Col1Col2Col3
one lineone linefirst line
second line
third line
first line
second line		one lineone line
one linefirst line
second line		one line
one lineone lineone very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very long line with no new line

Username AT mentions

Typing an @ symbol, followed by a username, will notify that person to come and view the comment. This is called an @mention, because you’re mentioning the individual. You can also @mention teams within an organization.

Automatic linking for URLs

Any URL (like http://www.github.com/) will be automatically converted into a clickable link.

Strike through

Any word wrapped with two tildes (like ~~this~~) will appear crossed out.

Any word wrapped with two tildes (like this) will appear crossed out.

Inline HTML

You can use raw HTML in your Markdown and it will mostly work pretty well.

<dl>
  <dt>Definition list</dt>
  <dd>Is something people use sometimes.</dd>

  <dt>Markdown in HTML</dt>
  <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
</dl>
Definition list
Is something people use sometimes.
Markdown in HTML
Does *not* work **very** well. Use HTML tags.

YouTube Videos

They can’t be added directly but you can add an image with a link to the video like this:

<a href="http://www.youtube.com/watch?feature=player_embedded&v=YOUTUBE_VIDEO_ID_HERE " target="_blank">
<img src="http://img.youtube.com/vi/YOUTUBE_VIDEO_ID_HERE/0.jpg"
alt="IMAGE ALT TEXT HERE" width="240" height="180" border="10" />
</a>

Markdown Crash Course

Or, in pure Markdown, but losing the image sizing and border:

[![IMAGE ALT TEXT HERE](http://img.youtube.com/vi/YOUTUBE_VIDEO_ID_HERE/0.jpg)](http://www.youtube.com/watch?v=YOUTUBE_VIDEO_ID_HERE)

Markdown Crash Crouse

TeX Mathematical Formulae

A full description of TeX math symbols is beyond the scope of this cheat sheet. Here’s a good reference, and you can try stuff out on CodeCogs. You can also play with formulae in the Markdown Here options page.

Here are some examples to try out:

Syntax highlighting

```markdown
> Use markdown highlighting
[because we can](#syntax-highlighting)
``` # no text, only close the section

Supported syntax highlighting languages:

NameFile extension
cucumber*.feature
abap*.abap
ada*.adb, *.ads, *.ada
ahk*.ahk, *.ahkl
apacheconf.htaccess, apache.conf, apache2.conf
applescript*.applescript
as*.as
as3*.as
asy*.asy
bash*.sh, *.ksh, *.bash, *.ebuild, *.eclass
bat*.bat, *.cmd
befunge*.befunge
blitzmax*.bmx
boo*.boo
brainfuck*.bf, *.b
c*.c, *.h
cfm*.cfm, *.cfml, *.cfc
cheetah*.tmpl, *.spt
cl*.cl, *.lisp, *.el
clojure*.clj, *.cljs
cmake*.cmake, CMakeLists.txt
coffeescript*.coffee
console*.sh-session
controlcontrol
cpp*.cpp, *.hpp, *.c++, *.h++, *.cc, *.hh, *.cxx, *.hxx, *.pde
csharp*.cs
css*.css
cython*.pyx, *.pxd, *.pxi
d*.d, *.di
delphi*.pas
diff*.diff, *.patch
dpatch*.dpatch, *.darcspatch
duel*.duel, *.jbst
dylan*.dylan, *.dyl
erb*.erb
erl*.erl-sh
erlang*.erl, *.hrl
evoque*.evoque
factor*.factor
felix*.flx, *.flxh
fortran*.f, *.f90
gas*.s, *.S
genshi*.kid
glsl*.vert, *.frag, *.geo
gnuplot*.plot, *.plt
go*.go
groff*.(1234567), *.man
haml*.haml
haskell*.hs
html*.html, *.htm, *.xhtml, *.xslt
hx*.hx
hybris*.hy, *.hyb
ini*.ini, *.cfg
io*.io
ioke*.ik
irc*.weechatlog
jade*.jade
java*.java
js*.js
jsp*.jsp
lhs*.lhs
llvm*.ll
logtalk*.lgt
lua*.lua, *.wlua
make*.mak, Makefile, makefile, Makefile.*, GNUmakefile
mako*.mao
maql*.maql
mason*.mhtml, *.mc, *.mi, autohandler, dhandler
markdown*.md
modelica*.mo
modula2*.def, *.mod
moocode*.moo
mupad*.mu
mxml*.mxml
myghty*.myt, autodelegate
nasm*.asm, *.ASM
newspeak*.ns2
objdump*.objdump
objectivec*.m
objectivej*.j
ocaml*.ml, *.mli, *.mll, *.mly
ooc*.ooc
perl*.pl, *.pm
php*.php, *.php(345)
postscript*.ps, *.eps
pot*.pot, *.po
pov*.pov, *.inc
prolog*.prolog, *.pro, *.pl
properties*.properties
protobuf*.proto
py3tb*.py3tb
pytb*.pytb
python*.py, *.pyw, *.sc, SConstruct, SConscript, *.tac
rb*.rb, *.rbw, Rakefile, *.rake, *.gemspec, *.rbx, *.duby
rconsole*.Rout
rebol*.r, *.r3
redcode*.cw
rhtml*.rhtml
rst*.rst, *.rest
sass*.sass
scala*.scala
scaml*.scaml
scheme*.scm
scss*.scss
smalltalk*.st
smarty*.tpl
sourceslistsources.list
splus*.S, *.R
sql*.sql
sqlite3*.sqlite3-console
squidconfsquid.conf
ssp*.ssp
tcl*.tcl
tcsh*.tcsh, *.csh
tex*.tex, *.aux, *.toc
text*.txt
v*.v, *.sv
vala*.vala, *.vapi
vbnet*.vb, *.bas
velocity*.vm, *.fhtml
vim*.vim, .vimrc
xml*.xml, *.xsl, *.rss, *.xslt, *.xsd, *.wsdl
xquery*.xqy, *.xquery
xslt*.xsl, *.xslt
yaml*.yaml, *.yml

Emojis

Emojis are common, in chats/messengers, mails and so on and of course, you can have them in markdown as well.

It depends on where you markdown file will be placed, based on that, different emojis are available

For gitea you can have a look at this list: https://gitea.com/gitea/gitea.com/issues/8 For github, you can have a look there: https://github.com/StylishThemes/GitHub-Dark/wiki/Emoji

In general the syntax looks like this:

:EMOJINAME:

It can be place everywhere :yellow_heart:

So have fun and enjoy them :wink:

Escaping Characters

To display a literal character that would otherwise be used to format text in a Markdown document, add a backslash \ in front of the character

\* Without the backslash, this would be a bullet in an unordered list.

* Without the backslash, this would be a bullet in an unordered list.

Characters you can escape

You can use a backslash to escape the following characters.

CharacterName
\backslash
`backtick (see also escaping backticks in code)
*asterisk
_underscore
{ }curly braces
[ ]brackets
< >angle brackets
( )parentheses
#pound sign
+plus sign
-minus sign (hyphen)
.dot
!exclamation mark
|pipe (see also escaping pipe in tables)

Escaping backticks

If the word or phrase you want to denote as code includes one or more backticks, you can escape it by enclosing the word or phrase in double backticks ``

``Use `code` in your Markdown file.``

Use `code` in your Markdown file.

Escaping Pipe in Tables

You can display a pipe | character in a table by using its HTML character code &#124; also putting it into a code section does not help you there.

Comments in Markdown

Markdown doesn’t include specific syntax for comments, but there is a workaround using the reference style links syntax. Using this syntax, the comments will not be output to the resulting HTML.

[]: # (This is a comment)
[]: # "And this is a comment"
[]: # 'Also this is a comment'
[//]: # (Yet another comment)
[comment]: # (Still another comment)

[]: # (This is a comment) []: # “And this is a comment” []: # ‘Also this is a comment’ [//]: # (Yet another comment) [comment]: # (Still another comment)

Each of these lines works the same way:

  • [...]: identifies a reference link (that won’t be used in the article)
  • # defines the destination, in this case # is the shortest valid value for a URL
  • (...), "...", and '...' define the reference title, which we repurpose to make a comment

Adding HTML Comments in Markdown

If you’d like for your comments to show up in the HTML output, a simple modified HTML comment syntax will work:

<!--- This is an HTML comment in Markdown -->

Unlike a “normal” HTML comment which opens with <!-- (two dashes), an HTML comment in Markdown opens with <!--- (three dashes). Some Markdown parsers support two-dash HTML comments, but the three-dash version is more universally compatible.