System dokumentacji

Manifest
Obsidian Setup

Architektura systemu¶

Ogólna idea

flowchart LR
A(Treści) --> B(Kontrola wersji)
C(Oprogramowanie do edycji) --> A
A --> D(Udostępnianie online)

Szczegółowo:

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

Komponenty w szczegółach¶

1. Markdown¶

Zalety:

• Jest łatwy do nauczenia i użycia, co pozwala mi skupić się na treści.
• Jest niezależny od platformy, dzięki czemu mogę kontynuować pracę na dowolnym urządzeniu.
• Jest idealny do kontroli wersji, co pozwala mi śledzić i zarządzać zmianami.
• Jest przyszłościowy i nie jest zastrzeżony, co daje mi pewność, że moja praca pozostanie dostępna w dłuższej perspektywie.

Markdown

2. Obsidian¶

• Mogę przechowywać moje dane lokalnie i edytować je offline, co daje mi elastyczność i kontrolę.
• Mogę łatwo linkować i łączyć pliki ze sobą, co pomaga mi organizować złożone informacje.
• Mogę dodawać tagi do plików i łatwo nimi zarządzać, co daje mi dodatkowy wymiar organizacji.
• Mogę wizualizować moje dane graficznie, co pomaga mi dostrzegać wzorce i relacje.
• Mogę rozszerzać funkcjonalność Obsidian za pomocą wtyczek, co pozwala mi dostosować narzędzie do moich specyficznych potrzeb.

3. Git i Github¶

Zalety:

• Kontrola wersji: Każda zmiana jest dokumentowana i może być śledzona w dowolnym momencie, co pomaga mi unikać błędów i zachować porządek.
• Współpraca: Wiele osób może jednocześnie pracować nad dokumentacją, co daje mi możliwość integracji informacji zwrotnych i wkładu od innych.
• Kopia zapasowa: Moja dokumentacja jest bezpieczna i regularnie tworzone są jej kopie zapasowe, co daje mi pewność, że moja praca nie zostanie utracona.

4. Github Desktop¶

Zalety:

• Łatwość obsługi, co ułatwia mi korzystanie z Git.
• Nie wymaga znajomości linii komend, co oszczędza mi czas i wysiłek.
• Upraszcza mój przepływ pracy, co pozwala mi skupić się na tworzeniu treści.

5. MkDocs¶

Zalety:

• Łatwe tworzenie stron internetowych, co pozwala mi szybko i łatwo publikować moją dokumentację.
• Szybkie aktualizacje, co pozwala mi widzieć zmiany w czasie rzeczywistym.
• Spójny układ, co zapewnia profesjonalny i jednolity wygląd mojej dokumentacji.
• Podgląd offline, co pozwala mi sprawdzić moją dokumentację przed jej opublikowaniem.

6. Github Pages¶

Zalety:

• Bezpłatny hosting, co pozwala mi publikować moją dokumentację bez dodatkowych kosztów.
• Łatwe publikowanie, co zdejmuje ze mnie techniczne zadanie publikacji.
• Niezawodność, co daje mi pewność, że moja dokumentacja jest zawsze dostępna.

7. MkDocs-Material¶

Zalety:

• Nowoczesny design, który sprawia, że moja dokumentacja wygląda profesjonalnie i nowocześnie.
• Możliwość dostosowania, co pozwala mi dostosować układ do moich specyficznych potrzeb.
• Przyjazny dla użytkownika, co ułatwia korzystanie z dokumentacji.

8. MkDocs-Publisher¶

Zalety:

• Uproszczona integracja z Obsidianem: Automatyczne dostosowywanie składni Markdown Obsidiana (wywołania, linki wiki itp.).
• Rozszerzone metadane: Integracja tagów i kategorii z frontmatter Obsidiana.

Przepływ pracy¶

1. Tworzę i edytuję pliki Markdown za pomocą edytora tekstu (opcjonalnie Obsidian).
2. Zapisuję pliki Markdown lokalnie.
3. Przesyłam moje zmiany do repozytorium Git za pomocą Github Desktop.
4. Automatycznie generuję stronę internetową za pomocą MkDocs.
5. Publikuję stronę internetową za pomocą Github Pages.

System plików¶

/docs/     (Tutaj znajdują się moje pliki Markdown)
/site/     (Tutaj generowana jest strona internetowa)
license    (Informacje o licencji)
mkdocs.yml (Plik konfiguracyjny dla MkDocs)
readme.md  (Plik opisujący repozytorium)

Alternatywy dla tworzenia treści¶

1. Wordpress: Treści można tworzyć w Wordpress jako strony.
2. Plik tekstowy, plik Word: Treści można tworzyć jako plik tekstowy, plik Word (lub w innych typowych formatach).

W tych przypadkach mogę następnie zaimplementować treści w systemie.