Розробка кастомних плагінів MkDocs

Розроблення користувацьких плагінів MkDocs

Плагіни MkDocs — це класи Python, підключені через события життєвого циклу збірки. Вони можуть змінювати вміст сторінок, навігацію, конфігурацію та підсумковий вивід HTML.

Структура плагіна

# my_mkdocs_plugin/__init__.py
from mkdocs.plugins import BasePlugin
from mkdocs.config import config_options
from mkdocs.config.base import Config

class MyPluginConfig(Config):
    api_url = config_options.Type(str, default='')
    cache_timeout = config_options.Type(int, default=3600)
    enabled = config_options.Type(bool, default=True)


class MyMkDocsPlugin(BasePlugin[MyPluginConfig]):

    def on_config(self, config):
        """Викликається після завантаження mkdocs.yml"""
        if not self.config.enabled:
            return config
        # Можна змінювати глобальну конфігурацію
        config['extra']['my_plugin_version'] = '1.0.0'
        return config

    def on_page_markdown(self, markdown, page, config, files):
        """Змінення Markdown до конвертування в HTML"""
        # Замінюємо користувацькі теги
        markdown = markdown.replace('{{VERSION}}', self._get_version())
        return markdown

    def on_page_content(self, html, page, config, files):
        """Змінення готового HTML сторінки"""
        # Додаємо користувацький банер на конкретні сторінки
        if page.meta.get('deprecated'):
            banner = '<div class="deprecated-notice">⚠️ Застарілий розділ</div>'
            html = banner + html
        return html

    def on_page_context(self, context, page, config, nav):
        """Додавання змінних у контекст шаблона"""
        context['api_status'] = self._get_api_status()
        return context

    def on_files(self, files, config):
        """Додавання/видалення файлів зі збірки"""
        return files

    def on_nav(self, nav, config, files):
        """Змінення навігації"""
        return nav

    def on_post_build(self, config):
        """Після завершення збірки"""
        self._notify_build_complete()

    def _get_version(self):
        import requests
        resp = requests.get(f"{self.config.api_url}/version", timeout=5)
        return resp.json().get('version', 'unknown')

Реєстрація через entry_points

# pyproject.toml
[project.entry-points."mkdocs.plugins"]
my-plugin = "my_mkdocs_plugin:MyMkDocsPlugin"

# mkdocs.yml
plugins:
  - my-plugin:
      api_url: https://api.myproject.com
      cache_timeout: 7200

Плагін для генерування сторінок API

class ApiDocsPlugin(BasePlugin):
    """Генерує сторінки документації зі специфікації OpenAPI"""

    def on_files(self, files, config):
        import yaml
        import requests
        from mkdocs.structure.files import File

        spec = requests.get(self.config.openapi_url).json()

        for path, methods in spec['paths'].items():
            for method, operation in methods.items():
                content = self._generate_endpoint_page(path, method, operation, spec)
                # Створюємо віртуальний файл без запису на диск
                file = File.generated(
                    config,
                    f"api/{self._path_to_slug(path)}-{method}.md",
                    content=content,
                )
                files.append(file)

        return files

    def _generate_endpoint_page(self, path, method, operation, spec):
        return f"""# {operation.get('summary', path)}

**{method.upper()}** `{path}`

{operation.get('description', '')}

## Parameters

{self._render_parameters(operation.get('parameters', []))}

## Responses

{self._render_responses(operation.get('responses', {}))}
"""

Розроблення плагіна для генерування сторінок із зовнішнього джерела займає 2–5 днів.