Docs-as-Code Portfolio

Руководство по устранению неполадок

В этом руководстве собраны типичные проблемы, которые могут возникнуть при работе с документацией, и способы их решения.

Порт 8000 занят

Симптом: при запуске mkdocs serve появляется ошибка о том, что порт занят.

Решение: используйте другой порт:

mkdocs serve -a 0.0.0.0:8080

Ошибка ModuleNotFoundError

Симптом: при сборке не находится модуль mkdocs или mkdocs_material.

Решение: убедитесь, что виртуальное окружение активировано и зависимости установлены:

pip install -r requirements.txt

Диаграммы Mermaid не отображаются

Симптом: вместо диаграмм отображается исходный текст.

Решение: проверьте, что в mkdocs.yml подключён плагин pymdownx.superfences с поддержкой Mermaid:

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

Битые ссылки в документации

Симптом: некоторые внутренние ссылки ведут на несуществующие страницы.

Решение: проверьте относительные пути. Например, из docs/guides/installation.md ссылка на корневой README выглядит так:

[README](../../README.md)

Запустите проверку ссылок:

./scripts/check-links.sh

Линтер выдаёт предупреждения

Симптом: markdownlint сообщает об ошибках стиля.

Решение: запустите линтер и исправьте замечания по стайлгайду:

./scripts/lint-docs.sh

Docker-сборка падает

Симптом: при docker build возникает ошибка.

Решение:

  1. Убедитесь, что Docker установлен и запущен: docker --version.
  2. Очистите кэш и пересоберите: docker build --no-cache -t docs-portfolio .
  3. Проверьте доступность сети для загрузки зависимостей.

Сайт не обновляется после публикации

Симптом: изменения видны в репозитории, но опубликованный сайт устарел.

Решение: SourceCraft Sites обновляет сайт автоматически в течение нескольких минут после изменения основной ветки. Подождите и обновите страницу (Ctrl+F5).

Что дальше?