Tento tutoriál tě seznámí s tím, jak psát vlastní články na tento blog
1. Nauč se, co je to Markdown, YAML a GIT
Celý tento blog je založený na nahrávání článků na GIT, konkrétně Bitbucket.
Jak si můžete všimnout již v tomto článku, který zrovna čtete, nebo README, je tento blog kompletně psaný v jazyce Markdown, který GIT využívá, jako bezpečnou alternativu k HTML.
Výhoda je ta, že oproti HTML zde nehrozí XSS útok, jelikož HTML kód je v rámci tohoto blogu zcela ignorován.
Konkrétní implementace Markdownu, která se používá na tomto blogu je githubflavored a její syntaxe je k nalezení zde.
Dále se pro zapsání meta informací o článcích a kategoriích používá soubor ve formátu YAML. Nauč se jej taky.
No a nakonec potřebuješ vědět, co to vlastně vůbec GIT je. Koukni se tedy na nějaké popisy a návody, jak se dělá a co je to COMMIT, PUSH, PULL a další základní příkazy. Zbytek si ukážeme v návodu.
Nyní znáš vše, co je potřeba k naučení se Markdown, YAML a GITu. Tak do toho a pak se vrhni na bod 2.
2. Založ si účet na Bitbucketu a forkni repo
Jdi na bitbucket.org a založ si účet. Jakmile bude hotovo, přejdi na stránku s repozitářem.
V pravo nahoře uvidíme 3 tečky a když je rozklikneme, bude zde tlačítko 'Fork this repository'. Na to klikneme.
Následně uvidíme formulář, kam se k nám na náš GIT má repozitář forknout a vyplníme údaje.
A máš hotovo. Repozitář je forknutý. Přejdeme na krok 3.
3. Proveď změny.
Ať už použiješ online editaci, nebo stažení(klonování) repozitáře, musíš nyní provést změny.
První, co budeš pořtebovat znát je adresářová struktura. V blogu je každý článek uveden v nějaké kategorii, čemuž je i uzpůsobena adresářová struktura.
Zde tedy ve zkratce popíšu, jak adresářová struktura vypadá:
_posts # složka, ve které budou uložené všechny články
<category> # složka nesoucí název kategorie
<article> # složka s názvem konekrétního článku
cs.md # soubor s českým překladem obsahu článku
en.md # soubor s anglickým překladem článku
meta.yaml # soubor s meta informacemi o konkrétním článku a autorovi
meta.yaml # soubor s meta informacemi o dané kategorii
assets # jak již název napovídá jde o složku se soubory jako jsou obrázky a gify.
avatars # složka obsahující miniaturu avatara každého autora - ano, musíš sem svou fotku nahrát
images # složka obsahující obrázky
<category> # složka obsahující obrázky dané kategorie (například thumbnail)
<article> # složka obsahující obrázky použité v daném článku
README.md # Soubor s obecným popisem repozitáře. Taky zde jsou informace o autorech, tak nezapomeň se sem přidat
Měj na paměti, že název složky <category> a <article> se bude propisovat do URL adresy, takže je nutné, aby názvy těchto složek byly ve tvaru, kterému URL rozumí. Tedy musí dodržovat snake_case konvenci a pouze bez diakritiky.
Pokud tedy existuje například složka 'tutorials', což je složka s kategorií, tak její URL adresa bude https://blog.tondajehlar.cz/tutorials. Pokud v dané složce bude existovat navíc ještě složka 'how_to_contributte', tak se jedná o článek přístupný na adrese https://blog.tondajehlar.cz/tutorials/how_to_contributte.
No a nakonec je toto příklad nesprávně použité citace. 😃 Ale hodí se mi do článku tak co.
Každá kategorie i každý článek MUSÍ obsahovat meta.yaml soubor, který musí být patřičně vyplněn. Jako ukázku si zkopíruj soubory z tohoto článku. Pozor, meta soubor pro článek je jiný, než meta soubor pro kategorii.
Při psaní článků je povinné psát články jak v českém, tak anglickém jazyce. Anglická verze stránek sice zatím neběží, ale během pár měsíců ji spustím, což bude znamenat, že všechny články musejí být přeloženy. V případě, že přeloženy nebudou, tak nebudou schváleny.
Pro vložení emotikon používejte Unicode standard. Ostatní typy kódování nemusí fungovat.
Po napsání dokonalého článku ještě přidej svůj avatar do patřičné složky a přidej do README.md odkaz na své stránky se svým avatarem, pokud tam již nejsi.
4. Nahraj změny na git a proveď Pull request
Změny commitni a následně pushni do svého forknutého repozitáře.
Pokud jsi z nějakých důvodů udělal více, než jeden commit, tak prosím, aby jsi všechny commity squashnul do jednoho, pomocí interactive rebase.
Jakmile máme pushnuto, tak přejdeme na bitbucket do našeho forknutého repozitáře. V levém menu uvidíme položku Pull requests.
Na tu klikneme a otevře se nám nová stránka. Na této stránce v pravo nahoře bude tlačítko Create pull request, na které klikneme.
Otevře se nám další okno, kde uvidíme, z jakého repozitáře (našeho forknutého), do jakého chceme udělat daný Pull request (tento originál). Bude tam taktéž výběr, jaký Branch chceme použít jako zdrojový a jaký jako cílový. Pokud jsi nevytvářel separátní branch, nechej výchozí master.
Dále máme pár polí, které je nutno vyplnit. Do kolonky title prosím vyplň název přidaného článku s prefixem Added, případně Edited
Do kolonky description vyplňte údaje podle předvyplněného textu.
Nakonec zbytek kolonek vyplňte podle potřeby, avšak v kolonce Reviewers ponechte minimálně mě.
Následně stiskneme tlačítko Create pull request
Toto vytvoří samotný pull request, který již já a ostatní, které označíte za reviewers uvidíme a přijde nám upozornění.
V případě, že bude článek v pořádku, tak jej schválím a udělám tzv. merge, což článek automaticky publikuje. Pokud tedy nejsi
se článkem spokojen a nechceš jej publikovat, pull request nevytvářej.
Může se stát, že na článku budou nedokonalosti, jako například chybějící překlad apod. Pokud tak nastane, obdržíš k pull requestu
upozornění, že byl přidán komentář, nebo issue. Tyto nalezneš opět v sekci pull requests v určitém pull requestu.
Po přepracování změn prosím opět proveď squash a pushni do repozitáře. Toto automaticky updatuje pull request, takže není nadále třeba nic dělat. Prostě jen počkáš na další požadované změny, nebo rovnou dojde k publikování.
5. Aktualizace a způsob vyjadřování
Potřebujeme zmínit, že pro lidi, kteří neradi čtou by měl být článek nahrán i v audioverzi a to ideálně jako video na YouTube.
To provedeš tak, že video buď nahraješ na tvůj kanál, nebo mi jej pošleš a já jej nahraji na svůj. Video ovšem není povinné.
Následně potřebuješ vyextrahovat odkaz na video a jeho titulek, aby jsi jej mohl přidat do meta.yaml souboru u daného videa.
To uděláš tak, že do odkazu na video v daném jazyce klikneš pravým tlačítkem, zvolíš volbu Zkopírovat kód pro vložení na stránky
a vyextrahuješ URL videa a title z iframe tagu.
V šabloně pak video vložíš pomocí speciálního tagu {{video}} na samostatném řádku, kterému rozumí jen tento blog.
Taktéž by měl být článek stručný, ale měl by obsahovat všechny potřebné informace. Pokud tedy bude potřeba aby byl článek hodně dlouhý z důvodů podrobného vysvětlování dané problematiky, tak prosím o napsání více článků na sebe navazujících.
Panuje zde konvence, že v článku si tykáme, případně mykáme. Jsme jedna velká komunita přátel, tak není třeba vykat. Jsme kolegové, partneři, kamarádi. Ne obchodní společníci, nebo nadřízení a podřízení, abychom si museli vykat. Také ale platí, že nebude tolerováno žádné podněcování nenávisti ani vulgrání výrazy, či urážky. Buďme konstruktivní. Všichni jsme lidi.
Nyní už znáš všechno, co je potřeba, aby jsi mohl napsat pořádný článek. Tak na co ještě čekáš? V informacích je síla. Použij ji tedy aby jsi změnil svět a sdílej je tu pro lepší budoucnost.
Já jdu nasazovat houbám kloboučky čus.