Syntaxe Markdown

Píšete v Markdownu, tak jak ho znáte z GitHubu nebo z README souborů? Texy ho čte podle specifikace CommonMark i s rozšířeními GitHub Flavored Markdown, a navíc text vysází: dodá správné uvozovky, pomlčky a pevné mezery a opraví rozbité HTML. Tady najdete všechno, co v Markdownu můžete napsat.

Tahák

Zápisy označené 🔸 patří k rozšíření GitHub Flavored Markdown (GFM). Fungují tam, kde je web zapne. Programátor to udělá jedním voláním, jak popisuje konfigurace.

Odstavce a zalomení řádků

Odstavec tvoří jeden nebo více řádků, které jdou těsně za sebou. Texy je spojí do jednoho souvislého textu, takže se nemusíte bát, že se věta zlomí tam, kde jste v editoru odřádkovali. Nový odstavec začne až po prázdném řádku:

Toto je první odstavec. Může mít klidně více řádků
a Texy je spojí do jednoho.

Až tady, po prázdném řádku, začíná druhý odstavec.

Potřebujete text jen odřádkovat, třeba v adrese? Ukončete řádek dvěma mezerami nebo zpětným lomítkem:

Jana Nováková··
U Sušárny 5\
150 00 Praha 5

Tečky ·· tu zastupují dvě mezery, které by jinak nebyly vidět. Protože je nevidíte ani v editoru, je zpětné lomítko spolehlivější volba.

Formátování textu

Podtržítko funguje jen na hranici slova, takže nazev_souboru_txt zůstane, jak je. Hvězdička zvýrazní i část slova: **sušené**švestky.

Nadpisy

Nadpis začíná mřížkou. Čím víc mřížek, tím menší nadpis, od # pro nejvyšší úroveň až po ###### pro šestou:

# Jak jsme sušili švestky

## Sklizeň

## Sušení

Nadpis první a druhé úrovně můžete napsat i podtržením, rovnítky pro první a pomlčkami pro druhou:

Jak jsme sušili švestky
=======================

Sklizeň
-------

Odkazy

Text odkazu patří do hranatých závorek, adresa hned za něj do kulatých. Za adresu můžete v uvozovkách připsat titulek, který prohlížeč ukáže po najetí myší:

Sušárnu jsme koupili v [obchodě](https://example.com/susarna "Obchod u nádraží").

Když na stejnou adresu odkazujete víckrát, nebo by dlouhá adresa znepřehlednila text, použijte referenci. V textu je jen její jméno a adresu napíšete kamkoli do článku, klidně až na konec:

Recept najdete [tady][recept] a babiččinu verzi [ještě tady][recept].

Adresu nebo e-mail, které se mají zobrazit tak, jak jsou, stačí dát do špičatých závorek:

Napište nám na <jana@example.com> nebo se podívejte na <https://example.com>.

V GFM 🔸 se odkazem stane i adresa bez závorek, pokud začíná www., http:// nebo https://.

Obrázky

Obrázek se píše stejně jako odkaz, jen s vykřičníkem na začátku. Text v hranatých závorkách popisuje obrázek pro ty, kdo ho nevidí, a za adresou může být titulek:

![Sušárna na půdě](susarna.jpg "Naše sušárna")

Rozměry, zarovnání, CSS třídu ani popisek pod obrázkem Markdown zapsat neumí. Pokud je potřebujete, podívejte se na obrázky v syntaxi Texy.

Seznamy

Odrážkový seznam začíná pomlčkou, hvězdičkou nebo plusem, číslovaný číslem s tečkou nebo závorkou. Vnořený seznam odsadíte tak, aby začínal pod textem nadřazené položky:

- švestky
- jablka
  - kyselá
  - sladká

1. natrhat
2. umýt
3. sušit

Číslovaný seznam začne číslem první položky, takže 3. na začátku ho začne trojkou. Další čísla Texy dopočítá samo, klidně tedy můžete psát všude 1..

V GFM 🔸 se z položky stane zaškrtávací políčko, když začíná [ ] nebo [x]:

- [x] natrhat švestky
- [ ] koupit sušárnu

Citace

Citace začíná znakem > na začátku řádku. Uvnitř citace funguje všechno ostatní, včetně dalších odstavců, seznamů nebo vnořené citace:

> Sušit, a pořádně.
>
> Babička

Kód

Kód v textu uzavřete do zpětných apostrofů, třeba `$texy->process()`. Pokud kód sám zpětný apostrof obsahuje, použijte na obou stranách dva.

Delší kód napíšete do bloku mezi řádky se třemi zpětnými apostrofy. Za ty první můžete připsat jazyk, podle kterého web kód obarví:

 ```php
 $texy = new Texy\Texy;
 ```

Blokem kódu je i text odsazený aspoň čtyřmi mezerami. Uvnitř kódu se nic neformátuje a nemění, typografie se ho netýká.

Tabulky

Tabulky patří k GFM 🔸. Buňky oddělíte svislítky, pod první řádek, který tvoří záhlaví, napíšete oddělovač z pomlček:

| Ovoce   | Doba sušení | Teplota |
|---------|:-----------:|--------:|
| švestky | 12 h        | 60 °C   |
| jablka  | 6 h         | 55 °C   |

Dvojtečky v oddělovači určují zarovnání sloupce: vlevo :---, na střed :---: a vpravo ---:. Svislítka nemusí být pod sebou, srovnání slouží jen pro čitelnost. Slučovat buňky tabulky v Markdownu nejde, umí to tabulky v syntaxi Texy.

Vodorovná čára

Tři nebo více pomlček, hvězdiček či podtržítek na samostatném řádku vytvoří vodorovnou čáru. Pomlčky musí od textu nad nimi oddělovat prázdný řádek, jinak by z textu udělaly nadpis.

Konec první části.

---

Začátek druhé části.

HTML v textu

Kde Markdown nestačí, můžete psát přímo HTML, v textu i jako celý blok:

Text s <mark>vyznačením</mark>.

<div class="tip">
Tip: sušte v tenké vrstvě.
</div>

Specifikace CommonMark takové HTML pouští do výstupu beze změny. Texy navíc hlídá, aby bylo správně uzavřené. Když autor značku zapomene uzavřít nebo je uzavře v opačném pořadí, Texy to opraví a zbytek stránky zůstane v pořádku:

Babičce to <b>určitě <i>chutnalo</b>.

<p>Babičce to <b>určitě <i>chutnalo</i></b><i>.</i></p>

Na webu, kam píšou návštěvníci, bude HTML nejspíš vypnuté a značky se zobrazí jako obyčejný text. GFM 🔸 navíc vždy zneškodní značky, které by mohly stránku ohrozit, jako <script> nebo <iframe>.

Psaní speciálních znaků

Chcete napsat hvězdičku, která nemá nic zvýraznit, nebo číslo s tečkou na začátku řádku, které nemá začít seznam? Dejte před znak zpětné lomítko:

\*tohle není kurzíva\*

1986\. byl dobrý rok na švestky.

Zpětným lomítkem jde takto zneplatnit kterýkoli znak se zvláštním významem, například \#, \[ nebo \|.

Co k Markdownu přidá Texy

Všechno výše je standardní Markdown a stejně by ho četl každý převodník, který dodržuje specifikaci. Texy k tomu text navíc vysází, aniž byste museli cokoli psát jinak:

Sušárna pojme 40 kg ovoce, otevřeno máme 9-17... A s dotazy k nám.

<p>Sušárna pojme 40&nbsp;kg ovoce, otevřeno máme 9–17… A&nbsp;s&nbsp;dotazy
k&nbsp;nám.</p>

Mezi čísly je pomlčka místo spojovníku, tři tečky se staly výpustkou a za jednopísmennými předložkami a spojkami i mezi číslem a jednotkou stojí pevná mezera, takže se na konci řádku neodtrhnou od slova, ke kterému patří. Texy navíc nahradí rovné uvozovky správnými uvozovkami podle jazyka a umí dělit dlouhá slova. Všechny úpravy popisuje typografie v syntaxi Texy, pro Markdown platí stejně.

Kódu v textu ani bloků kódu se typografie netýká.

Když Markdown nestačí

Markdown je záměrně jednoduchý a některé věci v něm zapsat nejde: obrázek s rozměry, zarovnáním a popiskem pod ním, CSS třídu u odstavce nebo sloučené buňky tabulky. Na to má Texy vlastní syntaxi, která je v základu stejně jednoduchá a s takovými věcmi počítá:

[* susarna.jpg 300x200 .(Sušárna na půdě)[photo] >] *** Foto: Jana Nováková

Jestli vám Markdown přestává stačit, podívejte se na Syntaxi Texy.