MkDocs [Wiki]

Tato stránka je pouze pro čtení. Můžete si pouze prohlédnout zdrojový kód, ale ne ho měnit. Zeptejte se správce, pokud si myslíte, že něco není v pořádku.
====== MkDocs ======

Dokumentátor jsem zvolil, protože je docela jednoduchý na obsluhu a dokumentaci je možné psát v Markdownu.

Použil jsem MkDocs s rozšířením Material for MkDocs.

Instalace pomocí Dockeru:

<code bash>
docker pull squidfunk/mkdocs-material
</code>

Založení adresáře se základním souborem:

<code bash>
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
</code>

Spuštění development prostředí:

<code bash>
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
</code>

Sestavení dokumentace do HTML:

<code bash>
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material build
</code>

===== Konfiguračního soubor mkdocs.yml =====

Při generování buildu jsem měl problémy, že odkazy v menu odkazovaly na složky a ne na konkrétní HTML stránky. Problém je podepsaný [[https://stackoverflow.com/questions/48063231/mkdocs-hyperlink-not-working-in-static-pages|zde]]. 

Řešení bylo přidat do konfiguračního souboru *mkdocs.yml* tuto direktivu:

<code>
use_directory_urls: false
</code>

Takže konfigurační soubor vypadá například takto:

<code yml>
site_name: FinTailor
nav:
  - Instalace: index.md
  - Poinstalační kroky: after-install.md
  - Databázový model: dbmodel.md
  - Databáze: database.md
  - Vkládání nového leadu: new-lead.md
  - Konfigurační soubory:
      - docker-compose.yml: docker-compose.yml.md

use_directory_urls: false
</code>




===== Mermaid pro MkDocs =====

Pro kreslení grafů je potřeba přidat plugin pro Mermaid. Vycházel jsem z [[https://squidfunk.github.io/mkdocs-material/reference/diagrams/|dokumentace]].

Editoval jsem soubor **mkdocs.yml** a přidal plugin Mermaid:

<code>
site_name: My Documentation
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
</code>

Pak už stačí přidat kód pro graf Mermaid.

<code>
``` mermaid
graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];
```
</code>


Pro zkoušení možností grafů Mermaid lze použít i [[https://mermaid.live/|Mermaid Live editor]]. Užitečná může být [[https://mermaid.js.org/intro/|dokumentace pro kreslení grafů v Mermaidu]].  

Pro další zkoumání může posloužit ještě tento zdroj: https://mkdocs-mermaid2.readthedocs.io/en/latest/

===== Další zdroje =====

  * https://squidfunk.github.io/mkdocs-material/plugins/search/
  * https://www.mkdocs.org/getting-started/#getting-started-with-mkdocs
  * https://squidfunk.github.io/mkdocs-material/creating-your-site/#building-your-site-unix-powershell