Přepis materiálů do Markdownu a stránky přes MkDocs

[ghost]

Co takhle na to jít trošku jednodušeji a rychleji, než se s tím zbytečně dlouho mazat (HTML aj.), tj.:

• přepsat materiály z PyLadies do Markdownu, případně jiného formátu
• vygenerovat stránky přes MkDocs, případně přes jiný generátor
• klidně nechat defaultní theme

Jednak by se to možná dalo stihnout do LinuxDays, druhak by odpadla starost o navigační strukturu a třeťak bychom se mohli dále věnovat dalším bodíkům v #40 - Akademie vedle v repu "zapojse".

Sice to není moc Pythonový způsob, ale mnohé by se tím vyřešilo. Já bych si nějaký ten čas na to našel, pokud by to bylo odsouhlaseno.

[frenzymadness]

Podle mě je tam HTML z určitého důvodu. Například hned jedna z prvních lekcí o příkazové řádce je napsána moc hezky ve dvou sloupcích pro Win/Linux a vypadá to pěkně a přehledně. Další věc, u které nevím, jak bych ji v MD provedl, je to obarvování textu, kterého je tam opravdu hodně.

Zrovna se na té migraci chystám pracovat, takže pak dám vědět, jak moc pracné to je a zda to i za současného stavu stihneme bez problémů do LinuxDays.

[encukou]

Přesně tak, přepisování celých materiálů do jiného formátu mi nepřijde jako jednoduchý a rychlý krok. Aktuální plán je o něco rychlejší:

• Nechat text materiálů jak je, případně ho trochu vyčistit
• Vygenerovat stránky přes Elsu :)
• Nechat existující theme

To co je jednoduché na nástrojích jako mkDocs jsou začátky – nemusíš nic složitě nastavovat, prostě píšeš. Převést na to existující projekty je složitější. Navíc Jinja+HTML a Elsa fungují dobře :)

Co ale Markdownu nemůžu upřít je že se dobře píše a edituje. Najdeš-li materiály které se dají jednoduše převést (klidně jenom zčásti), klidně to udělej – zapojit Markdown do aktuálních stránek by neměl být problém.

[ghost]

Dobrá dobrá. Já jen, že mě to tak napadlo včera.

[honzajavorek]

Když už, tak Sphinx a rst. Mám rád Markdown, ale na dokumentaci tohoto rozsahu se nehodí, protože tam nejsou sémantické věci (už jen blbé "note" a "warning" citelně chybí při delším návodu v markdownu).

Do Sphinxu by navíc snad šlo nějak dopsat značky na dva sloupce apod. (btw zrovna dva sloupce jde asi vyřešit tabulkou? 90s strikes back), o čemž si můžeš v md nechat jen snít. Mám v mkdocs dokumentaci k Dreddu a je to rychlé a jednoduché pro start, ale jak povyrosteš, jsou s tím jen omezení a potíže, takže to chci mít ve Sphinxu jak jen to půjde.

[encukou]

V Jinje můžeš udělat něco jako:

{% filter markdown %}
    Tady píšu *čistý* markdown!
{% endfilter %}
<div class="fancy-columns">
    A tady to pořádně <blink>zvýrazním</blink>!
</div>

Je fakt že jsem něco takového použil jen párkrát, na souvislejší texty, ale zatím se mi to docela líbilo. 80%/20%.

[ghost]

Na to note, warning atd. budu chystat vlastní theme do MkDocs pro Doksit, bo tohle taky píšu do docstringů a chci, aby se to pěkne vystylovalo.

[encukou]

Na tom se doporučuju domluvit s autorem mkDocs :) Ale sem to, obávám se, nepatří, dokud to nebude v nějakém jakž takž standardním dialektu Markdownu.

[ghost]

Kapišto. Jinak já bych už tuto issue uzavřel (vše probráno), co vy na to?

[encukou]

Jo, otázka byla snad zodpovězena :) Diskutovat se dá i když je zavřeno.