Documentatiesysteem

Manifest
Obsidian Setup

Systeemarchitectuur¶

Het algemene idee

flowchart LR
A(Inhoud) --> B(Versiebeheer)
C(Bewerkingssoftware) --> A
A --> D(Online toegankelijk maken)

In detail:

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

Componenten in detail¶

1. Markdown¶

Voordelen:

• Het is eenvoudig te leren en te gebruiken, waardoor ik me kan concentreren op de inhoud.
• Het is platformonafhankelijk, zodat ik mijn werk op elk apparaat kan voortzetten.
• Het is ideaal voor versiebeheer, waardoor ik wijzigingen kan bijhouden en beheren.
• Het is toekomstbestendig en niet-propriëtair, wat me de zekerheid geeft dat mijn werk toegankelijk blijft op de lange termijn.

Markdown

2. Obsidian¶

• Ik kan mijn gegevens lokaal opslaan en offline bewerken, wat me flexibiliteit en controle geeft.
• Ik kan eenvoudig bestanden linken en met elkaar verbinden, wat me helpt complexe informatie te organiseren.
• Ik kan bestanden van tags voorzien en eenvoudig beheren, wat me een extra dimensie van organisatie biedt.
• Ik kan mijn gegevens grafisch weergeven, wat me helpt patronen en verbanden te herkennen.
• Ik kan de functionaliteit van Obsidian uitbreiden met plugins, waardoor ik de tool kan aanpassen aan mijn specifieke behoeften.

3. Git en Github¶

Voordelen:

• Versiebeheer: Elke wijziging wordt gedocumenteerd en kan op elk moment worden teruggezien, wat me helpt fouten te voorkomen en het overzicht te bewaren.
• Samenwerking: Meerdere personen kunnen tegelijkertijd aan de documentatie werken, waardoor ik feedback en bijdragen van anderen kan integreren.
• Back-up: Mijn documentatie is veilig en wordt regelmatig geback-upt, wat me de zekerheid geeft dat mijn werk niet verloren gaat.

4. Github Desktop¶

Voordelen:

• Eenvoudige bediening, wat het gebruik van Git voor mij vergemakkelijkt.
• Geen kennis van de commandoregel nodig, wat me tijd en moeite bespaart.
• Vereenvoudigt mijn workflow, waardoor ik me kan concentreren op het creëren van inhoud.

5. MkDocs¶

Voordelen:

• Eenvoudige websitecreatie, waardoor ik mijn documentatie snel en eenvoudig kan publiceren.
• Snelle updates, waardoor ik wijzigingen in realtime kan zien.
• Consistente lay-out, wat zorgt voor een professionele en uniforme weergave van mijn documentatie.
• Offline preview, waardoor ik mijn documentatie kan controleren voordat ik deze publiceer.

6. Github Pages¶

Voordelen:

• Gratis hosting, waardoor ik mijn documentatie zonder extra kosten kan publiceren.
• Eenvoudige publicatie, wat de technische implementatie van de publicatie voor mij uit handen neemt.
• Betrouwbaar, wat me de zekerheid geeft dat mijn documentatie te allen tijde beschikbaar is.

7. MkDocs-Material¶

Voordelen:

• Modern design, waardoor mijn documentatie er professioneel en eigentijds uitziet.
• Aanpasbaar, waardoor ik de lay-out kan aanpassen aan mijn specifieke behoeften.
• Gebruiksvriendelijk, wat het gebruik van de documentatie voor mij vergemakkelijkt.

8. MkDocs-Publisher¶

Voordelen:

• Vereenvoudigde Obsidian-integratie: Automatische aanpassing van Obsidians Markdown-syntax (Callouts, Wikilinks etc.)
• Uitgebreide metadata: Integratie van tags en categorieën uit Obsidian-frontmatter.

Workflow¶

1. Ik maak en bewerk Markdown-bestanden met een teksteditor (optioneel Obsidian).
2. Ik sla de Markdown-bestanden lokaal op.
3. Ik upload mijn wijzigingen naar de Git-repository met Github Desktop.
4. Ik laat de website automatisch genereren met MkDocs.
5. Ik publiceer de website met Github Pages.

Bestandsstructuur¶

/docs/     (Hier staan mijn Markdown-bestanden)
/site/     (Hier wordt de website gegenereerd)
license    (Licentie-informatie)
mkdocs.yml (Configuratiebestand voor MkDocs)
readme.md  (Bestand ter beschrijving van de repository)

Alternatieven voor het creëren van inhoud¶

1. Wordpress: Inhoud kan in Wordpress als een pagina worden aangemaakt.
2. Tekstbestand, Word-bestand: Inhoud kan worden aangemaakt als tekstbestand, Word-bestand (of in andere typische formaten).

In deze gevallen kan ik de inhoud vervolgens in het systeem verwerken.