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

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

MkDocs-плагины — Python-классы, подключаемые через events жизненного цикла сборки. Могут модифицировать контент страниц, навигацию, конфиг и итоговый 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 spec"""

    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)
                # Создаём virtual файл без записи на диск
                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 дней.