MkDocs Obsidian Deployment

Этот проект предоставляет готовое решение для автоматического развертывания документации из Obsidian vault в веб-сайт с помощью MkDocs. Решение использует Docker для простого развертывания и обслуживания.

Описание

Проект позволяет автоматически конвертировать структуру каталогов и Markdown-файлы из Obsidian в полноценный веб-сайт документации с помощью MkDocs. Основные возможности:

• Автоматическая генерация навигации на основе структуры каталогов
• Поддержка вложенных каталогов и подразделов
• Автоматическое создание оглавления
• Современный Material дизайн
• Легкое развертывание через Docker
• Автоматическое обновление при изменении исходных файлов

Требования

• Docker
• Docker Compose
• Obsidian vault с markdown файлами

Вот несколько шагов, которые вы можете предпринять:

1. Обновите Docker Compose: Рекомендуется обновить Docker Compose до более новой версии. Вы можете сделать это, следуя инструкциям на официальной странице установки Docker Compose. Например, для Linux вы можете использовать следующие команды:

   sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/bin/docker-compose
   sudo chmod +x /usr/bin/docker-compose
   

   После этого проверьте версию снова:

   
    docker-compose --version
   

Структура проекта

project_root/
├── Dockerfile              # Конфигурация Docker образа
├── docker-compose.yml      # Конфигурация Docker Compose
├── entrypoint.sh          # Скрипт инициализации контейнера
├── get_indexmd.py         # Скрипт генерации index.md
├── get_mkd.py            # Скрипт генерации mkdocs.yml
├── requirements.txt       # Python зависимости
└── source/               # Каталог для ваших markdown файлов

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

1. Подготовка проекта

1. Клонируйте репозиторий:

git clone [URL репозитория]
cd [имя каталога]

1. Создайте каталог source в корне проекта:

mkdir source

2. Подготовка документации

1. Откройте ваш Obsidian vault
2. Выберите каталог с документацией, которую хотите опубликовать
3. Скопируйте содержимое этого каталога в каталог source вашего проекта

3. Настройка

При необходимости отредактируйте следующие файлы:

• get_mkd.py: измените значение site_name для установки названия вашего сайта
• docker-compose.yml: если нужно изменить порт (по умолчанию 80)

4. Запуск

1. Соберите и запустите контейнер:

docker-compose up -d --build

1. Проверьте работу сайта:

• Откройте в браузере http://localhost (если запускаете локально)
• Или http://ваш_ip (если запускаете на сервере)

5. Обновление документации

1. Внесите изменения в файлы в каталоге source
2. Изменения будут автоматически отражены на сайте

6. Остановка сервера

docker-compose down

Структура сгенерированного сайта

• Навигация создается автоматически на основе структуры каталогов
• Названия разделов берутся из имен каталогов
• Файл index.md создается автоматически и содержит оглавление
• Поддерживается вложенность каталогов любой глубины

Особенности работы с Obsidian

1. Поддерживаются все стандартные элементы markdown
2. Внутренние ссылки Obsidian ([[]]) необходимо заменить на стандартные markdown ссылки
3. Изображения должны использовать относительные пути
4. Рекомендуется использовать уникальные имена файлов во всех каталогах

Возможные проблемы и их решение

Сайт не открывается

• Проверьте, что порт 80 не занят другими приложениями
• Убедитесь, что Docker демон запущен
• Проверьте логи: docker-compose logs

Не отображается навигация

• Убедитесь, что в каталоге source есть файлы
• Проверьте права доступа к файлам
• Проверьте логи на наличие ошибок

Проблемы с кодировкой

• Убедитесь, что все файлы сохранены в UTF-8
• Проверьте наличие специальных символов в именах файлов

Дополнительная настройка

Изменение темы

В файле get_mkd.py можно изменить тему, и имя сайта site_name, добавив дополнительные параметры в конфигурацию:

"theme": {
    "name": "material",
    "palette": {
        "primary": "indigo",
        "accent": "indigo"
    }
}

Изменение порта

Сейчас мы работаем на 80-м порту. В файле docker-compose.yml измените строку:

ports:
  - "новый_порт:8000"

Безопасность

1. Не включайте конфиденциальные данные в документацию
2. Используйте HTTPS при развертывании в продакшн
3. Настройте файервол на сервере
4. Регулярно обновляйте зависимости

Поддержка

При возникновении проблем: 1. Проверьте логи: docker-compose logs 2. Убедитесь, что все файлы на месте 3. Проверьте права доступа к файлам 4. Создайте issue в репозитории проекта

Лицензия

[GPL-3.0]

Авторы

[Сахно Р.А. / itdid / ramanzes]

что ещё можно добавить

сервис бесплатный домена и а также проброс ngrok и подобное из локальной сети в интернет. сборка всё на смартфоне. а также установка тудаже почтового сервера.