11. Markdown

Vývoj vanilkové příchuti Linuxu: Knihy kouzel byl 1. března 2025 ukončen. Tento text je zachován jako historický, ale chyby již nejsou opravovány. Odnože projektu pod kompatibilní licencí jsou vítány.

syntaxe

1. Úvod

Markdown je jednoduchý a praktický značkovací jazyk pro pohodlné psaní i čtení textů s jednoduchým formátováním v editorech prostého textu. Je primárně určen k převodu do HTML, kde se na výsledek aplikují kaskádové styly.

Bohužel existuje řada ne zcela kompatibilních implementací Markdownu. Proto se tato kapitola zaměřuje především na původní (standardní) Markdown, který je základem pro všechny ostatní varianty, a poměrně značně rozšířenou variantu Markdown Extra.

2. Zaklínadla: Markdown

^2/1 Nadpisy

@nadpis první/druhé/třetí/čtvrté/páté/šesté úrovně#1

# nadpis

## nadpis

### nadpis

#### nadpis

##### nadpis

###### nadpis

^2/2 Základní formátování

@dva odstavce#1

první odstavec

prázdná řádka

druhý odstavec

@tučný text#2

**text**

@kurzíva#3

*text*

@vložený kód v rámci řádku (obecně/příklad)#4 ⁽¹⁾

`kód`

````PRIKLAD="*```*"````

@víceřádkový kód#5

první řádek

[ další řádka]

^2/3 Odkazy a obrázky

@hypertextový odkaz (normální/zjednodušený)#1 ⁽²⁾

[text odkazu](adresa-odkazu[ "titulek"])

<adresa-odkazu>

@předdefinovaný hypertextový odkaz (definice/použití)#2 ⁽³⁾

[identifikátor]: [bílé znaky]adresa-odkazu[ "titulek"]

[text odkazu][identifikátor]

@vložit obrázek (jako znak)#3

![alternativní text](adresa-odkazu[ "titulek"])

@předdefinovaný obrázek (definice/použití)#4

[identifikátor]: [bílé znaky]adresa-obrázku[ "titulek"]

![alternativní text][identifikátor]

^2/4 Seznamy a odsazení

@odrážkovaný seznam#1

* položka seznamu

[* další položka seznamu]

prázdný řádek

@automaticky číslovaný seznam#2

1. položka seznamu

[1. další položka seznamu]

prázdná řádka

@výrazné odsazení odstavce zleva (první úroveň)#3

> začátek textu

[> pokračování]

@výrazné odsazení odstavce zleva (druhá úroveň)#4

> > začátek textu

[> > pokračování]

3. Zaklínadla: Markdown Extra

@tabulka#1 ⁽⁴⁾

| záhlaví 1 [| další záhlaví]

| zarovnání 1 [| další zarovnání]

[| buňka 1 [| další buňka]]

@poznámka pod čarou (odkaz na poznámku/text poznámky)#2 ⁽⁵⁾

[^id]

[^id]: text poznámky

@seznam definic se dvěma definicemi (druhá má dva pojmy)#3

první pojem

: odstavec popisující první pojem

prázdný řádek

druhý pojem

třetí pojem

: odstavec popisující druhý a třetí pojem

@víceřádkový kód#4 ⁽⁶⁾

~~~[ .CSS-třída]

řádka kódu

~~~

@nadpis s kotvou/odkaz na takový nadpis#5

nadpis [bílé znaky]{#id}

[text odkazu](#id[ "titulek"])

@zkratky (<abbr>)(definice/použití)#6

*[zkratka]: vysvětlení

zkratka

^3/1 Ostatní

@komentář#1

@horizontální čára#2

***

4. Zaklínadla: Nestandardní

@podtržení#1

text

@přeškrtnutý text#2

~~text~~

@kód se zvýrazněním syntaxe#3

```syntaxe

řádka kódu

```

5. Parametry příkazů

@převod Markdownu na HTML5#1

pandoc -f gfm -t html5 -o výstupní-soubor vstupní-soubor

6. Instalace na Ubuntu

@příkaz pandoc pro konverzi na HTML a jiné formáty#1

sudo apt-get install pandoc

@editor (grafický)#2

sudo apt-get install retext

Existuje i modernější a propracovanější editor Remarkable (licence MIT) zaměřený především na Arch Linux, ale je možno ho nainstalovat i v Ubuntu.

7. Ukázka

# Ukázka Markdownu

## Nadpis druhé úrovně

Text prvního

odstavce obsahuje část **tučně**, část *kurzívou* a část podtrženou a také ``vložený kód se zpětným apostrofem (`)``.

Text druhého odstavce. [Odkaz s textem](http://www.slovnik-synonym.cz/), [s id][Slovník synonym], [znovu s id][Slovník synonym] a <http://www.slovnik-synonym.cz/>.

Obrázky: ![tento][ve výstavbě] a ![tento](../obrázky/ve-výstavbě.png).

[Slovník synonym]: http://www.slovnik-synonym.cz/

[ve výstavbě]: ../obrázky/ve-výstavbě.png

[^pozn-pod-carou]: S poznámkou pod čarou.

> Odstavec odsazený

na první úroveň[^pozn-pod-carou].

> > Odstavec odsazený

na druhou úroveň.

### Tabulka (Markdown Extra)

| Sloupec 1 | Sloupec 2 | Sloupec 3

| :--- | --- | ---:

| vlevo | na střed | vpravo

8. Tipy a zkušenosti

Asi nejhorším problémem v Markdownu je odzvláštňování. Speciální znaky se totiž odzvláštňují zpětným lomítkem pouze tehdy, když mají speciální význam; v ostatních případech se zpětné lomítko před takovým znakem exportuje jako normální znak. Problém však je, že inteprety Markdownu se velmi značně liší v tom, které znaky a v jakých kontextech považují za speciální. Proto nelze dosáhnout zcela jednotných výsledků. Standardní Markdown však zaručuje možnost zpětným lomíkem odzvláštnit: !, #, *, +, -, ., \, _, ` a všechny tři druhy závorek. Markdown Extra k tomu přidává znaky : a |.
Identifikátory předdefinovaných odkazů a obrázků jsou prakticky obecné řetězce. Vhodný identifikátor je i např. „3.12;Dobrý den/Žlutoučký kůň*“. Jejich maximální délka je ale omezena implementací.
V Markdownu můžete přímo používat inline prvky HTML (např. či ). Při konverzi na jiný formát než HTML však tyto prvky pravděpodobně nebudou podporovány.
Markdown (standardní) umožňuje vložit zalomení řádky pomocí dvou či více mezer na konci řádky. Osobně to nedoporučuji, protože některé textové editory (např. vim) bílé znaky na konci řádku nezobrazují a některé nástroje je mohou považovat za překlep a automaticky odstranit. Doporučuji místo toho používat HTML značku , případně .
Markdown neumožňuje vloženému obrázku definovat rozměry. Toto můžete učinit buď pomocí CSS, nebo místo syntaxe Markdownu přímo použít značku <img>.
Po prvním spuštění ReTextu doporučuji otevřít Úpravy / Nastavení a zaškrtnout políčka „Vždy použít živý náhled“, „Zvýrazňovat aktuální řádek“ a „Zobrazovat čísla řádků“ a restartovat ReText. S těmito nastaveními mi připadne práce pohodlnější.

9. Další zdroje informací

Doporučuji prohledat online zdroje nebo prostě experimentovat. Velmi obsáhlým a formálně přesným zdrojem je „Specifikace GitHub Flavored Markdown“.

Stránka na Wikipedii
Markdown Cheatsheet (anglicky)
Oficiální stránky: Markdown Syntax (anglicky)
GitHub Help: Basic writing and formatting syntax (anglicky)
Markdown Extra Syntax (anglicky)
Video: Markdown Syntax Cheat Sheet (anglicky)
Video: Markdown Tutorial (anglicky)
Video: How to Write MarkDown (anglicky)
Specifikace GitHub Flavored Markdown (anglicky)
Manuálová stránka o Markdownu (anglicky)
Manuálová stránka příkazu markdown (anglicky)
Balíček pandoc (anglicky)
Balíček retext (anglicky)
Balíček Remarkable v ALUR (anglicky)

10. Zákulisí kapitoly

V této verzi kapitoly chybí:

GFM (GitHub Flavoured Markdown) (nicméně všechna uvedená zaklínadla na GitHubu fungují)

Tato kapitola záměrně nepokrývá:

1 Ve vloženém kódu se neinterpretují žádné formátovací sekvence ani odzvláštnění (dokonce i zpětné lomítko si tam zachovává význam obyčejného znaku), proto je potřeba zvláštní přístup, pokud má vložený kód obsahovat zpětné apostrofy. K otevření a uzavření vloženého kódu můžete použít libovolný počet zpětných apostrofů, ale musí být stejný pro otevření i pro uzavření a vyšší než maximální počet zpětných apostrofů vyskytujících se ve formátovaném kódu vedle sebe.

2 Některé interprety markdownu automaticky převádějí úplné URL adresy na hypertextové odkazy bez zjevné možnosti odzvláštnění.

3 Definice se uvádí pro každý identifikátor pouze jednou a může být kdekoliv v dokumentu (ale na samostatné řádce). Definovaný identifikátor může být použit na více místech, a to i s různými texty odkazů. Identifikátor může začínat číslem a obsahovat mezery a není citlivý na velikost písmen!

4 Zarovnání je „:---“ vlevo, „---“ na střed nebo „---:“ vpravo. Řádek se záhlavím a řádka se zarovnáními jsou povinné, ostatní řádky tabulky jsou nepovinné. Buňky tabulky mohou obsahovat formátování.

5 Omezení: Na jednu poznámku pod čarou lze odkazovat tímto způsobem pouze jednou!

6 Pro tuto syntaxi můžete použít i více než tři znaky ~, ale jejich počet v zahajující a ukončující řádce se musí shodovat.

Datum, čas a kalendář

Soubory a adresáře

Regulární výrazy