Systém dokumentácie

Manifest
Obsidian Setup

Architektúra systému¶

Všeobecná myšlienka

flowchart LR
A(Obsah) --> B(Správa verzií)
C(Softvér na úpravu) --> A
A --> D(Sprístupniť online)

Podrobnejšie:

flowchart LR
A[Obsidian] <--> B{Súbory}
B <--> C(Github Desktop)
C <--> D{Github}
B <--> E(MkDocs)
D --> F(Github Pages)
G(Téma: MkDocs-Material) --> E
H(MkDocs-Publisher) --> E
E --> D

Komponenty podrobnejšie¶

1. Markdown¶

Výhody:

• Ľahko sa učí a používa, čo mi umožňuje sústrediť sa na obsah.
• Je nezávislý od platformy, takže svoju prácu môžem pokračovať na akomkoľvek zariadení.
• Je ideálny na správu verzií, čo mi umožňuje sledovať a spravovať zmeny.
• Je odolný voči budúcnosti a nie je proprietárny, čo mi dáva istotu, že moja práca zostane dlhodobo prístupná.

Markdown

2. Obsidian¶

• Svoje údaje môžem ukladať lokálne a upravovať ich offline, čo mi dáva flexibilitu a kontrolu.
• Súbory môžem ľahko prepojiť a navzájom prepojiť, čo mi pomáha organizovať zložité informácie.
• Súbory môžem označiť značkami a ľahko ich spravovať, čo mi poskytuje ďalšiu dimenziu organizácie.
• Svoje údaje môžem vizualizovať, čo mi pomáha rozpoznávať vzory a vzťahy.
• Funkcionalitu Obsidianu môžem rozšíriť pomocou pluginov, čo mi umožňuje prispôsobiť si nástroj mojim špecifickým potrebám.

3. Git a Github¶

Výhody:

• Správa verzií: Každá zmena je zdokumentovaná a dá sa kedykoľvek spätne dohľadať, čo mi pomáha predchádzať chybám a udržať si prehľad.
• Spolupráca: Viacero ľudí môže na dokumentácii pracovať súčasne, čo mi dáva možnosť integrovať spätnú väzbu a príspevky od ostatných.
• Zálohovanie: Moja dokumentácia je v bezpečí a pravidelne sa zálohuje, čo mi dáva istotu, že moja práca nebude stratená.

4. Github Desktop¶

Výhody:

• Jednoduché použitie, čo mi uľahčuje používanie Gitu.
• Nie sú potrebné žiadne znalosti príkazového riadka, čo mi šetrí čas a námahu.
• Zjednodušuje môj pracovný postup, čo mi umožňuje sústrediť sa na tvorbu obsahu.

5. MkDocs¶

Výhody:

• Jednoduché vytváranie webových stránok, čo mi umožňuje rýchlo a ľahko publikovať moju dokumentáciu.
• Rýchla aktualizácia, čo mi umožňuje vidieť zmeny v reálnom čase.
• Konzistentné rozloženie, ktoré zabezpečuje profesionálne a jednotné zobrazenie mojej dokumentácie.
• Offline náhľad, ktorý mi umožňuje skontrolovať moju dokumentáciu pred jej publikovaním.

6. Github Pages¶

Výhody:

• Bezplatné hostovanie, čo mi umožňuje publikovať moju dokumentáciu bez dodatočných nákladov.
• Jednoduché publikovanie, čo mi odbremeňuje technickú realizáciu publikovania.
• Spoľahlivé, čo mi dáva istotu, že moja dokumentácia je kedykoľvek dostupná.

7. MkDocs-Material¶

Výhody:

• Moderný dizajn, vďaka ktorému moja dokumentácia vyzerá profesionálne a aktuálne.
• Prispôsobiteľné, čo mi umožňuje prispôsobiť rozloženie mojim špecifickým potrebám.
• Užívateľsky prívetivé, čo mi uľahčuje používanie dokumentácie.

8. MkDocs-Publisher¶

Výhody:

• Zjednodušená integrácia s Obsidianom: Automatické prispôsobenie syntaxe Markdownu Obsidianu (Callouts, Wikilinks atď.).
• Rozšírené metaúdaje: Integrácia značiek a kategórií z frontmatteru Obsidianu.

Pracovný postup¶

1. Vytváram a upravujem súbory Markdown pomocou textového editora (voliteľne Obsidian).
2. Súbory Markdown ukladám lokálne.
3. Svoje zmeny prenášam do Git repozitára pomocou Github Desktop.
4. Automaticky nechám vygenerovať webovú stránku pomocou MkDocs.
5. Webovú stránku publikujem pomocou Github Pages.

Súborový systém¶

/docs/     (Tu sú moje súbory Markdown)
/site/     (Tu sa generuje webová stránka)
license    (Informácie o licencii)
mkdocs.yml (Konfiguračný súbor pre MkDocs)
readme.md  (Súbor s popisom repozitára)

Alternatívy na tvorbu obsahu¶

1. Wordpress: Obsah je možné vytvoriť vo Wordpresse ako stránku.
2. Textový súbor, Word dokument: Obsah je možné vytvoriť ako textový súbor, Word dokument (alebo v iných bežných formátoch).

V týchto prípadoch môžem obsah následne vložiť do systému.