Proč reStructuredText a ne Markdown

To je asi otázka, která napadne všechny, kteří programují nebo něco píší, ať dokumentaci, či jiné dokumenty.

Markdown i reStructuredText jsou odlehčené značkovací jazyky. Markdown je určen pro zápis textu pro co nejsnazší převod do HTML a jejho největším zastáncem je GitHub. Nemá jednotnou syntaxi.

reStructuredText je oproti tomu určen pro tvorbu dokumentace a složitějších textů. Z tohoto formátu lze generovat jak HTML, tak PDF, ePuB a mnohé další. reStructuredText také vizuálně více vypadá jako výsledně formátovaný text, čímž usnadňuje jeho čtení. Je více spjat s Pythonem, neboť je součástí nástrojů pro tvorbu technické dokumentace Pythonu. V roce 2011 byl vybrán jako zdrojový formát pro projekt Gutenberg, ze kterého jsou generovány e-knihy.

Takže proč spíš než masivně rozšířený Markdown jsem si vybral reStructuredText? A proč ne txt2tags nebo jiné odlehčené značkovací jazyky jako AsciiDoc nebo Textile?

1. AsiiDoc jsem před lety zkoušel a jeho syntaxe není tak zažitelná, nepracovalo se mi v něm moc dobře
2. Markdown je sice velmi profláknutý, ale zvládá jen to základní
3. reStructuredText je hlavním jazykem sphinx-doc, generátoru techn. dokumentace v Pythonu, se kterým jsem již několikrát pracoval a pomocí nějž jsem v roce 2014 vyrobil v práci základní dokumentační stránky pro nově nastoupivší zaměstnance do mnou vedeného oddělení. A ve sphix-doc lze tvořit ePub knihy, což využívám, když chci něco sepsaného transformovat do své elektronické čtečky.
4. Z porovnání použitelnosti vyšel jako nejuniverzálnější (např. na wiki).
5. Nedělám obvykle to, co všichni ostatní, tedy další důvod nepoužívat Markdown :)

Proč Pelican

Místo Wordpressu jsem hledal jiné nástroje, které by nebylo třeba neustále aktualizovat a řešit tak možné bezpečnostní díry, kterých jsem si s Wordpressem 2.x a 3.x užil dost. (A které mne naučili, že jít s hlavním proudem má také své podstatné nevýhody.)

Na jiné ze subdomén adpro.cz jsem provozoval dokuwiki, ale to jsem byl stále svázán ve formátu textu s konkrétním nástrojem. Nebylo to špatné, ale raději něco jiného.

Začal jsem koukat po generátorech statických stránek. Jejich smyslem je ze vstupních souborů vytvořit za pomocí šablon zpravidla webové stránky. Díky různým šablonovacím technologiím různě složitě díky nástrojům a frameworkům, které potřebují k běhu, i různě rychle. Koukal jsem na některé z nich:

• Jekyll - jeden z nejoblíbenějších, běžících na Ruby,
• Hugo - jeden z neoblíbenějších, běžících na Go,
• Hexo - jeden z nejoblíbenějších, běžících na Node.js,
• Pelican - velmi oblíbený, běžící na Pythonu.

Koukl jsem i na mnohé další běžících na Pythonu, uvedených na stránce FullStackPython jako Lektor, MkDocs, Nikola, Hyde a Cactus.

Většina uvedených nejoblíbenějších generátorů používá jako zdroj Markdown a reST nepoužívají nebo se musí složitě doinstalovat. Generátory založené na Pythonu mají reST de facto v základu, tudíž byly vhodnější volbou, aby nebylo nutné se učit více novým věcem najednou. Po projití několika stránek jsem vyhodnotil, že vyzkouším Pelican.

Po kratším testování jsem přijal Pelican jako vhodný, byť ne ideální nástroj. Jeho dokumentace není stoprocentní a výběr témat šablon oproti hlavním konkurentům není tak široká, ale díky šablonovacímu jazyku Jinja2 lze šablony upravit k obrazu svému.

Proč Skeleton a ne Bootstrap

Když jsem došel k názoru, že je nutné upravit některou ze šablon (a vyšel jsem ze základní simple šablony), chtěl jsem zajistit responzivitu, aby byl blog dobře čitelný i na mobilech. Klasikou je Bootstrap, ale zároveň je to poměrně velký kanón na cílové použití. Snaha byla najít něco lehčího. Přehled odlehčených alternativ je například zde. Výběr nakonec padl na Skeleton. Skeleton je velmi lehký a jeho kód je velmi malý. Styl lze upravit podle svého, což je na blogu vidět.