Skip to content

MkDocs

Instalacja

Założenia konfiguracyjne:

  • MkDocs uruchamiamy w kontenerze mkdocs na obrazie squidfunk/mkdocs-material.
  • Plik Docker Compose przechowujemy w/srv/docker/compose/mkdocs
  • Projekt MkDocs (mkdocs.yml + katalog docs/) przechowujemy w /srv/docker/projects/docs

Tworzenie katalogów

Tworzymy katalog dla Compose:

sudo mkdir -p /srv/docker/compose/mkdocs
sudo chown -R "$USER:$USER" /srv/docker/compose/mkdocs

Tworzymy katalog projektu MkDocs:

sudo mkdir -p /srv/docker/projects/mkdocs/docs
sudo chown -R "$USER:$USER" /srv/docker/projects/mkdocs

Dostęp do sieci Docker

Wymagany dostęp do sieci proxy

Aby udostępnić aplikację publicznie, wymaga ona dostępu do zewnętrznej sieci Docker proxy.

Tworzenie sieci Docker

Konfiguracja Docker Compose

Przechodzimy do katalogu Compose:

cd /srv/docker/compose/mkdocs

Tworzymy i edytujemy plik compose.yaml:

micro compose.yaml

W pliku umieszczamy:

compose.yaml
services:
  mkdocs-docs:
    image: squidfunk/mkdocs-material
    container_name: mkdocs-docs
    working_dir: /docs
    volumes:
      - /srv/docker/projects/mkdocs/docs:/docs
    command: ["serve", "-a", "0.0.0.0:8000"]
    restart: unless-stopped
    networks:
      - proxy

networks:
  proxy:
    external: true

Zapisujemy plik i wychodzimy z edytora.

Konfiguracja MkDocs

Tworzymy i edytujemy plik mkdocs.yml w katalogu projektu:

micro /srv/docker/projects/mkdocs/docs/mkdocs.yml

W pliku umieszczamy:

mkdocs.yaml
site_name: Help Docs
theme:
  name: material
  palette:
    - scheme: default
      toggle:
        icon: material/brightness-7
        name: Przełącz na tryb ciemny
    - scheme: slate
      toggle:
        icon: material/brightness-4
        name: Przełącz na tryb jasny
  features:
    - content.code.copy
markdown_extensions:
  - attr_list
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences

nav:
  - Start: index.md
  - Page: page.md
  - Parent 01:
      - Child 01: parent-01/childpage-01.md
      - Child 02: parent-01/childpage-02.md
  - Parent 02:
      - Child 01: parent-02/childpage-01.md
      - Child 02: parent-02/childpage-02.md

Zapisujemy plik i wychodzimy z edytora.

Przykładowy index.md

Tworzymy i edytujemy plik w folderze /docs projektu docs:

micro /srv/docker/projects/mkdocs/docs/docs/index.md

W pliku umieszczamy:

index.md
# Welcome to MkDocs

For full documentation visit [mkdocs.org](https://www.mkdocs.org).

## Commands

* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs -h` - Print help message and exit.

## Project layout

    mkdocs.yml    # The configuration file.
    docs/
        index.md  # The documentation homepage.
        ...       # Other markdown pages, images and other files.

Tworzenie struktury plików

Tworzymy katalogi i minimalne pliki zgodne z nav:

cd /srv/docker/projects/mkdocs/docs
mkdir -p docs/parent-01 docs/parent-02

touch docs/page.md
touch docs/parent-01/childpage-01.md docs/parent-01/childpage-02.md
touch docs/parent-02/childpage-01.md docs/parent-02/childpage-02.md

Uruchomienie kontenera

Przechodzimy do katalogu Compose i uruchamiamy kontener:

cd /srv/docker/compose/mkdocs
docker compose up -d

Sprawdzamy, czy kontener działa:

docker ps | grep mkdocs

Konfiguracja reverse proxy

Dodajemy wpis do Caddyfile:

Caddyfile
mkdocs.fulc.ro {
  reverse_proxy mkdocs-docs:8000
}

Przeładowujemy Caddy:

docker exec -it caddy caddy reload --config /etc/caddy/Caddyfile

Logi

Podglądamy logi kontenera:

docker logs -f mkdocs