Markdown

Tyto skripta se kompilují pomocí mdbook, je tedy možné používat všechny tímto programem podporované konstrukce.

Časem je cílem podorovat i build do pdf, což nejspíš omezí některé syntaxe, aby mohl proběhnout build do html i do pdf ze stejného zdrojového kódu.

Navíc jsou do mdbook nainstalované preprocessory, které umožňují používat další druhy syntaxe. Preprocesory jsou uvedeny cca v pořadí, ve kterém se spoštějí:

checklist 📘

Umožňuje vložit do markdownu inline TODO, ze kterých se udělá globální seznam ve speciální kapitole, s odkazy.

Příklad

Kvůli konfliktu syntaxu s jinja templatováním je nutné použít pro vytvoření TODO jinja makro:

{{ todo("This and that needs to be done") }}

minijinja 📘

Umožňuje napříč celými skripty používat jinja templates (specifikace) pomocí implementace minijinja (rozdíly oproti specifikaci).

Templates, včetně souborů obsahující makra, jsou ve složce templates. Globální proměnné lze přidat v book.toml.

Naimportování všech důležitých maker lze provést pomocí {% include prelude %}, kde prelude je v book.toml zadefinované jako "prelude.md", které se nachází v templates/ a importuje makra. NEW: prelude se includuje ve všech kapitolách automaticky, není potřeba includovat nic z ní.

Příklad

{% set authors = ["Michal Vojáček", "Michal Javor"] %}

Autoři těchto skript jsou {{ authors | join(", ") }}.

| Číslo | Autor |
|------:|:------|
{% for author in authors -%}
| {{ loop.index }} | {{ author }} |
{% endfor -%}
| end | end |

{% call spoiler(el="div") %}
{{ gate("xor", "OUT", "IN1", "IN2") }}
{% endcall %}

Autoři těchto skript jsou Michal Vojáček, Michal Javor.

cmdrun 📘

Umožňuje do skript přidat výstup libovolného unix příkazu, což je užitečné např. pro generování výstupů z logisimu, nebo buildování latexu.

Přichází s tím samozřejmě určitý risk, proto doporučuji provozovat mdbook builder v dockeru. Všechny použití tohoto preprocesoru lze najít pomocí:

grep -roP '\<\!\-\- cmdrun\K.+(?=\-\-\>)' --exclude-dir book .

Příklad

Jako příklad seznam všech použití toho preprocesoru ve skriptech (příkaz výše):

./src/90_ostatni/markdown.md: cd ../.. && grep --color=no -roP '\<\!\-\- cmdrun\K.+(?=\-\-\>)' --exclude-dir book . 

katex 📘

Umožňuje použití $ a $$ pro psaní matematických výrazů.

Příklad

$$\nabla f(x)\in {\mathbb{R}}^n$$

image-size 📘

Markdown neumožňuje specifikaci velikosti a centrování obrázků, tento preprocesor tuto funkcionalitu přidává.

Do budoucna chci projekt upravit a rozvolnit syntaxi, aby šlo specifikovat pouze zarovnání, bez šířky.
✏️ TODO: Forknout mdbook-image-size a rozvolnit syntaxi

Příklad

admonish 📘

Umožňuje vytvářet HTML "bannery", které volitelně můžou být rozbalovací.

Vyvolává se pomocí ```admonish info title="Title",collapsible=true, kde místo info můžou být následující vestavěné styly:

Příklad

quiz

✏️ TODO: quiz

toc

✏️ TODO: toc

kroki

✏️ TODO: kroki

emojicodes 📘

Umožňuje vkládat do textu emoji pomocí Github shortcode ohraničeného ::

Kompletní seznam shortcodes

Příklad

👨‍❤️‍👨 👩‍❤️‍👩 ✅ 🏳️‍🌈 🏳️‍⚧️

embedify

✏️ TODO: embedify

footnote

✏️ TODO: footnote

pagetoc 📘

Přidává na generovanou stránku vpravo sidebar s navigací v aktuální kapitole, pokud na nej je horizontální místo ve viewportu.