Dokumentační systém

Manifest
Obsidian Setup

Architektura systému¶

Obecná myšlenka

flowchart LR
A(Obsah) --> B(Správa verzí)
C(Editační software) --> A
A --> D(Zpřístupnění online)

Podrobněji:

flowchart LR
A[Obsidian] <--> B{Soubory}
B <--> C(Github Desktop)
C <--> D{Github}
B <--> E(MkDocs)
D --> F(Github Pages)
G(Theme: MkDocs-Material) --> E
H(MkDocs-Publisher) --> E
E --> D

Komponenty podrobně¶

1. Markdown¶

Výhody:

• Snadno se učí a používá, což mi umožňuje soustředit se na obsah.
• Je nezávislý na platformě, takže mohu svou práci pokračovat na jakémkoli zařízení.
• Je ideální pro správu verzí, což mi umožňuje sledovat a spravovat změny.
• Je dlouhodobě udržitelný a není proprietární, což mi dává jistotu, že má práce zůstane dlouhodobě přístupná.

Markdown

2. Obsidian¶

• Mohu svá data ukládat lokálně a upravovat je offline, což mi dává flexibilitu a kontrolu.
• Mohu snadno propojovat soubory a vytvářet mezi nimi vazby, což mi pomáhá organizovat složité informace.
• Mohu soubory označovat štítky a snadno je spravovat, což mi poskytuje další rozměr organizace.
• Mohu svá data vizualizovat, což mi pomáhá rozpoznávat vzorce a vztahy.
• Mohu rozšířit funkčnost Obsidianu pomocí pluginů, což mi umožňuje přizpůsobit nástroj svým specifickým potřebám.

3. Git a Github¶

Výhody:

• Správa verzí: Každá změna je zdokumentována a lze ji kdykoli zpětně dohledat, což mi pomáhá předcházet chybám a udržovat si přehled.
• Spolupráce: Více lidí může na dokumentaci pracovat současně, což mi umožňuje integrovat zpětnou vazbu a příspěvky od ostatních.
• Záloha: Moje dokumentace je v bezpečí a je pravidelně zálohována, což mi dává jistotu, že má práce nebude ztracena.

4. Github Desktop¶

Výhody:

• Snadné použití, což mi usnadňuje práci s Gitem.
• Není nutná znalost příkazového řádku, což mi šetří čas a úsilí.
• Zjednodušuje můj pracovní postup, což mi umožňuje soustředit se na tvorbu obsahu.

5. MkDocs¶

Výhody:

• Snadné vytváření webových stránek, což mi umožňuje rychle a snadno publikovat svou dokumentaci.
• Rychlá aktualizace, což mi umožňuje vidět změny v reálném čase.
• Konzistentní rozložení, které zajišťuje profesionální a jednotný vzhled mé dokumentace.
• Offline náhled, který mi umožňuje zkontrolovat svou dokumentaci před jejím publikováním.

6. Github Pages¶

Výhody:

• Bezplatný hosting, což mi umožňuje publikovat svou dokumentaci bez dalších nákladů.
• Snadné publikování, což mi odstraňuje technické provedení publikování.
• Spolehlivost, což mi dává jistotu, že má dokumentace je kdykoli dostupná.

7. MkDocs-Material¶

Výhody:

• Moderní design, díky kterému má dokumentace vypadá profesionálně a aktuálně.
• Přizpůsobitelnost, což mi umožňuje přizpůsobit rozložení svým specifickým potřebám.
• Uživatelská přívětivost, což mi usnadňuje používání dokumentace.

8. MkDocs-Publisher¶

Výhody:

• Zjednodušená integrace s Obsidianem: Automatické přizpůsobení syntaxe Markdown v Obsidianu (Callouts, Wikilinks atd.).
• Rozšířená metadata: Integrace štítků a kategorií z frontmatteru Obsidianu.

Pracovní postup¶

1. Vytvářím a upravuji soubory Markdown pomocí textového editoru (volitelně Obsidian).
2. Soubory Markdown ukládám lokálně.
3. Přenesu své změny do Git repozitáře pomocí Github Desktop.
4. Automaticky nechám vygenerovat webovou stránku pomocí MkDocs.
5. Publikuji webovou stránku pomocí Github Pages.

Souborový systém¶

/docs/     (Zde jsou mé soubory Markdown)
/site/     (Zde se generuje webová stránka)
license    (Informace o licenci)
mkdocs.yml (Konfigurační soubor pro MkDocs)
readme.md  (Soubor s popisem repozitáře)

Alternativy pro tvorbu obsahu¶

1. Wordpress: Obsah lze vytvořit ve Wordpresu jako stránku.
2. Textový soubor, Word soubor: Obsah lze vytvořit jako textový soubor, Word soubor (nebo v jiných běžných formátech).

V těchto případech mohu obsah následně do systému začlenit.