Przejdź do głównej zawartości

MkDocs

MkDocs to prosty generator statycznych stron przeznaczony do tworzenia dokumentacji w oparciu o pliki Markdown (.md).
Wygenerowana strona działa w pełni offline, również po otwarciu bezpośrednio z dysku (file://), bez potrzeby uruchamiania serwera WWW.

Dzięki temu MkDocs świetnie nadaje się do dokumentacji lokalnej, archiwalnej oraz do zastosowań awaryjnych.

Do czego służy MkDocs​

MkDocs sprawdza się szczególnie wtedy, gdy:

  • dokumentacja ma być prosta i czytelna,
  • treści są pisane w Markdown,
  • strona ma działać lokalnie (np. z pendrive’a),
  • nie jest potrzebny backend ani aplikacja SPA,
  • liczy się stabilność i przewidywalność działania.

Każda strona jest generowana jako osobny plik HTML, a nawigacja opiera się na zwykłych linkach, a nie na routerze JavaScript.

Instalacja MkDocs​

MkDocs jest aplikacją Pythona. Najwygodniej zainstalować go przez pipx lub pip.

Instalacja przez pipx (zalecana)​

pipx install mkdocs
pipx inject mkdocs mkdocs-material

Instalacja przez pip (dla użytkownika)​

python3 -m pip install --user mkdocs mkdocs-material

Po instalacji można sprawdzić wersję:

mkdocs --version

Utworzenie nowego projektu​

mkdocs new moja_dokumentacja
cd moja_dokumentacja

Powstanie struktura:

moja_dokumentacja/
├── mkdocs.yml
└── docs/
    └── index.md

Pliki Markdown umieszczane są w katalogu docs/.

Podstawowa konfiguracja​

Minimalny plik mkdocs.yml może wyglądać tak:

site_name: Moja dokumentacja

theme:
  name: material
  language: pl

use_directory_urls: false

Ustawienie use_directory_urls: false powoduje generowanie plików:

strona.html

zamiast:

strona/index.html

Jest to zalecane ustawienie dla pracy w trybie offline (file://).

Nawigacja (menu)​

Menu strony definiuje się w pliku mkdocs.yml:

nav:
  - Start: index.md
  - Dokumenty: dokumenty.md
  - Zdrowie: zdrowie.md
  - Status: status.md

Kolejność pozycji w menu odpowiada kolejności wpisów w pliku konfiguracyjnym.

Budowanie strony​

Aby wygenerować statyczną stronę HTML:

mkdocs build

Gotowa strona znajdzie się w katalogu:

site/

Zawartość tego katalogu można:

  • skopiować na pendrive,
  • zarchiwizować,
  • otworzyć bezpośrednio przez plik index.html.

Podgląd lokalny (opcjonalnie)​

Do podglądu zmian podczas pracy można użyć wbudowanego serwera:

mkdocs serve

Strona będzie dostępna pod adresem:

http://127.0.0.1:8000

Nie jest to wymagane do działania strony offline.

Tryb offline (file://)​

MkDocs generuje czysty HTML, dlatego:

  • strona działa po otwarciu pliku index.html,
  • nie wymaga serwera WWW,
  • nie wymaga dostępu do internetu,
  • nawigacja działa lokalnie.

To kluczowa różnica w porównaniu do generatorów opartych o React lub Vue.

Podsumowanie​

MkDocs to:

  • prosty i stabilny generator dokumentacji,
  • idealne narzędzie do pracy offline,
  • Markdown jako jedyne źródło treści,
  • łatwa konfiguracja i utrzymanie.

Dzięki temu świetnie nadaje się do dokumentów technicznych, instrukcji, baz wiedzy oraz dokumentacji awaryjnej.