Приложение для ведения базы знаний¶

История создания¶

После того как я сделал скрипт для автоматизации создания разделов в базе знаний, ко мне пришла идея о создании полноценной утилиты для управления mkdocs и синхронизации файлов с GitHub.

Зачем я начал это делать?

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

Выбранный стек¶

Для реализации я выбрал уже привычный для себя стек разработки:

FastAPI
Vue.js
Nuxt UI

Мне очень понравилось работать с библиотекой компонентов Nuxt UI, потому что это позволяет очень быстро собирать макеты. Ощущается как почти нативная разработка. Я уже писал однажды проектик, где не использовал никаких библиотек, и это был неплохой опыт для обучения. Но сейчас я понимаю что существует огромное количество готовых решений, и большого смысла изобретать свой велосипед я не вижу. И вероятнее всего, это будут более функционально наполненные компоненты, чем те, которые я буду создавать долго и сам.

Функционал¶

Прогресс добавления фич¶

Добавление новых записей в базу знаний
Синхронизация с GitHub
Выгрузка бэкапа в zip архиве
Выбор ветки для коммита и пуша
Добавление картинок и гифок
Добавление / редактирование разделов из mkdocs.yml файла

Добавление новых записей в базу знаний¶

Превью добавления новых записей

Я создал эндпоинт на бэкенде, а затем собрал формочку для отправки новой записи в базу знаний.

Предусмотрена опция добавления как отдельного блока кода, так и просто записи, куда можно писать в свободной форме.

Модуль для конфигурации подсветки синтаксиса

Из интересного, я реализовал свой отдельный модуль конфигурации.

Это было сделано для того, чтобы через него по умолчанию задавать метки для подсветки синтаксиса внутри блоков с кодом.

# /.mkdocsutils/config.toml
docs_dir = "docs"

# Определить подсветку кода по умолчанию для раздела
[categories_codes]
Python = "python"
SQL = "sql"
Git = "git"
Bash = "bash"
Docker = "Dockerfile"

# Директории которые не попадают в GET запрос, и недоступны для того чтобы напрямую писать туда записи
[excluded_directories]
dirs = ["stylesheets", "assets"]

Но я специально оставил поле на формочке, если вдруг внутри блока нужно будет написать код с другим синтаксисом. Например внутри раздела Python нужно вставить команду запуска для bash, с соответствующей подсветкой синтаксиса.

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

Синхронизация с GitHub¶

Также в качестве удобной фичи, я сделал функцию которая буквально выполняет следующие команды:

git remote set-url origin https://x-access-token:${TOKEN}@github.com/${REPO_OWNER}/${REPO_NAME}.git
git status --porcelain docs # проверка на изменения чтобы не делать пустой коммит.
git add docs # добавляем в отслеживание только папочку docs, чтобы не коммитить лишнего через синхронизацию
git -c user.name=Docs Bot -c user.email=docs-bot@local commit --no-verify -m "docs: ${msg}"
git push -f origin HEAD:refs/heads/${target_branch}
git reset --soft HEAD~1

Эта комбинация команд делает коммит в соседнюю ветку, и сразу пушит все записи в удалённый репозиторий. При этом в коммите подписывается, что это автоматический коммит от бота.

Токен и остальные параметры берутся из .env файла

Ветку для пуша можно конфигурировать, но для себя я определил "bot/docs-auto-sync" ветку, чтобы не запускать GitHub Actions при добавлении каждой небольшой заметки, и делать merge вручную.

Такой подход с "git reset --soft HEAD~1" позволяет оставлять историю коммитов в main чистой

Далее я запаковал это в формочку на фронтенде.

Превью синхронизации

Тут мы можем задать сообщение для коммита. Возможно имеет смысл это даже автоматизировать это: вынести в конфигурацию, и включить опцию чтобы делать синхронизацию это при каждом добавлении новой записи (сообщение будет = заголовку). Но тогда история коммитов будет невероятно раздутой и захламлённой на мой взгляд, поэтому я предпочитаю это делать вручную. Но для других разработчиков можно ввести эту отдельную настройку для автоматической синхронизации.

Как это синхронизируется если сервис запущен в Docker?

Синхронизация контейнера и файловой системы на компьютере реализована прямо в docker compose:

    volumes:
  - ./docs:/app/docs
  - ./.git:/app/.git

Это позволяет пробрасывать файлы документации и git с локального компьютера.

Файловая система контейнера backend

Добавление изображений и GIF-файлов в assets¶

В дальнейшем Также добавлю возможность добавлять файлы картинок прямо через интерфейс. На бэкенде эта возможность уже есть.

Полезные удобные мелочи¶

Из удобств, я добавил смену светлой/тёмной темы, возможность сразу перейти в представление базы знаний на github.io, и небольшую кнопку для перехода в сам репозиторий с проектом.

По итогу очень часто пользуюсь этим в процессе ведения базы знаний.