MKDocs

Статический генератор сайтов, который используется даже здесь. Отлично подходит для создания документации по проекту.

Установка и использование

1. Ставим последний python.
2. Обычный mkdocs никто не использует, поэтому мы будем ставить mkdocs-material. Ставиться он через pip pip install mkdocs-material.
3. Создаем проект командой mkdocs new <project_name>.
4. Переходим в каталог и настраиваем наш конфиг (mkdocs.yml):

   site_name: Здесь имя сайта
   
   theme:
     name: material
   

5. В каталог docs можем писать наши md файлы с документацией
6. Билдим командой mkdocs build
7. Если хотим смотреть во время изменений используем mkdocs serve. Команда запустит локальный сервер.

Мой сетап

Плагины

Я использую несколько кастомных плагинов, поэтому мой requirements.txt выглядит так:

mkdocs-material # нутыпонел
mkdocs-awesome-pages-plugin # кастомная навигация
pymdown-extensions # расширения для маркдауна

Содержимое можем сохранить в requirements.txt и установить командой pip install -r requirements.txt

Конфигурация

site_name: Записки kiriharu
site_author: kiriharu
site_url: !ENV [SITE_URL, 'https://notes.kiriha.ru'] # урл сайта, вроде как влияет на билд
theme:
  language: ru
  custom_dir: overrides
  name: material
  features:
    # Якори
    - navigation.tracking
    # Кнопка "Вверх"
    - navigation.top
    # Поиск
    - search.suggest
    # Подсветка результатов поиска
    - search.highlight
  palette:
  # Light mode - светлая тема
  - media: '(prefers-color-scheme: light)'
    scheme: default
    primary: indigo
    accent: deep purple
    toggle:
      icon: material/toggle-switch-off-outline
      name: Темная тема

  # Dark mode - темная тема
  - media: '(prefers-color-scheme: dark)'
    scheme: slate
    primary: indigo
    accent: deep purple
    toggle:
      icon: material/toggle-switch
      name: Светлая

plugins:
  # плагин на навигацию в страницах
  - awesome-pages
  # внезапно, поиск
  - search:
      lang:
        - en
        - ru
  # теги постов
  - tags:
      tags_file: tags.md

markdown_extensions:
  - toc:
      permalink: true
      # используем кастомное решение для slug
      slugify: !!python/name:pymdownx.slugs.uslugify
  # предостережния, спойлеры и т.д.
  - admonition
  - pymdownx.magiclink 
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - pymdownx.details # Detailed блоки

# аналитика для Matomo
extra:
  analytics:
    provider: matomo
    url: !ENV MATOMO_URL
    site_id: !ENV MATOMO_SITE_ID

Аналитика

Для аналитики я использую Matomo. Конфигурация указана выше. Для встраивания скрипта я использую override шаблон по пути overrides/partials/integrations/analytics/matomo.html, выглядит он следующим образом:

Код

<script>
    var url = "{{ config.extra.analytics.url }}" 
    var siteID = "{{ config.extra.analytics.site_id }}" 
    var _paq = window._paq = window._paq || [];
    _paq.push(['trackPageView']);
    _paq.push(['enableLinkTracking']);
    (function() {
        var u=url;
        _paq.push(['setTrackerUrl', u+'matomo.php']);
        _paq.push(['setSiteId', siteID]);
        var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
        g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
    })();
</script>

Деплой

Деплоится это дело при каждом пуше в мастер при помощи Github Actions. Вот deploy.yml:

name: Build and deploy Doka

on:
  push:
   branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:

      - name: Checkout to current branch
        uses: actions/checkout@v3

      - name: Setup python
        uses: actions/setup-python@v4
        with:
          python-version: 3.x

      - name: Install requirements
        run: pip install -r requirements.txt

      - name: Build mkdocs
        run: python -m mkdocs build -d dist
        env:
          MATOMO_URL: ${{ secrets.MATOMO_URL }}
          MATOMO_SITE_ID: ${{ secrets.MATOMO_SITE_ID }}

      - name: Generate artifact
        uses: actions/upload-artifact@v3
        with:
          name: dist
          path: dist
          retention-days: 1

  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:

      - name: Download dist artifact
        uses: actions/download-artifact@v3
        with:
          name: dist
          path: dist

      - name: rsync deployments
        uses: burnett01/rsync-deployments@5.2.1
        with:
          switches: -avzr --delete
          path: "dist"
          remote_path: ${{ secrets.DEPLOY_PATH }}
          remote_host: ${{ secrets.DEPLOY_HOST }}
          remote_port: ${{ secrets.DEPLOY_PORT }}
          remote_user: ${{ secrets.DEPLOY_USER }}
          remote_key: ${{ secrets.DEPLOY_KEY }}

На сервере стоит nginx, который отдает статику с следующим конфигом:

server {
    server_name notes.kiriha.ru;
    location / {
        root /srv/www/dist;
        index index.html;
        try_files $uri $uri/ /index.html;
     }
     error_page 400 /404.html;

    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/notes.kiriha.ru/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/notes.kiriha.ru/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
}

Сертификаты дает certbot.