Как я построил AI-базу знаний на Astro и Starlight: от Markdown до ИИ-консультанта за 7 дней

TL;DR

• Создание персонального карьерного менеджера на Astro + Starlight + Markdown

• Подключение редакторов AI-агентов (OpenCode/Claude Code) — они скачивают и вычитывают исходные материалы, пишут статьи в вики, делают перелинковку и ведут лог

• Возможность хранения на GitHub Pages — бесплатно, мгновенная загрузка

• Примеры: wpcraft.ru/kb/, ddpa.ru/kb/, и персональный карьерный менеджер

• Код одного из проектов: https://github.com/wpcraft-ru/kb-wordpress

Введение: зачем мне понадобилась AI-база знаний

Я веб-разработчик. Более 14 лет с WordPress, WooCommerce, Laravel. Десятки проектов, фриланс бирж, различные профиля в соц сетях, разбросанные отзывы и документация.

Данные разбросаны по документам Google Docs, заметкам в телефоне и маке, черновики в Notion, чатам в Telegram, разрозненные данные в профилях бирж и соц сетей.

Потребовалось вспомнить, как настраивал DKIM на почтовом сервере три года назад? 20 минут поиска по папкам.

Новый клиент спрашивает про интеграцию МойСклад и WooCommerce? Объясняю в пятый раз, попутно поднимая образ старого проекта.

Документация устаревает быстрее, чем руки доходят до ее составления и структуризации.

Я, как и многие, уже давно активно работаю с AI-инструментами: GitHub Copilot, Claude Code и другими. Почему бы не использовать ИИ не только для написания кода, но и как библиотекаря и менеджера накопленных знаний и документации? Пусть читать мои черновики, структурировать их, находит противоречия, скачивает, создает и добавляет в wiki актуальные данные, а заодно управляет данными профилей на различных площадках.

В это же время Андрей Карпатый опубликовал архитектуру LLM Knowledge Base, где AI сам ведёт wiki: читает PDF и статьи, пишет связанные страницы, расставляет перекрёстные ссылки, находит противоречия. Тема вызвала ажиотаж в твиттере и мне тоже понравилась — все хотят освободиться от нудной ручной работы.

Идея Карпатого показалась мне интересной, но она заточена под глубокий рисёрч — там присутствуют множество источников по одной теме, связи между ними и поиск противоречий. Это скорее инструмент учёного-исследователя, а не веб-разработчика. Мне был нужен инструмент, который за вечер превратит разрозненные заметки и сохраненные закладки в работающую wiki, поможет отслеживать вакансии на рынке, обновлять резюме, хранить кейсы и отзывы с различных площадок и на их основании писать офферы.

Так появилась идея создания LLM Wiki — базы знаний, где контент хранится в виде Markdown-файлов, а AI-агенты выступают редакторами. Принцип, что у Карпатого, но с фокусом на практическое применение: от персонального карьерного менеджера до публичной документации продукта или технологии.

Зачем вообще эти ваши базы знаний? Небольшое отступление.

Перед тем как перейти к описанию процесса немного теории. База знаний — это не только модное слово и «папка с файлами», а способ накапливать и структурировать данные и перестать отвечать на один и тот же вопрос по разному не изобретая велосипед каждый понедельник.

Вот где она реально спасает и дает профит:

Внутренние процессы. Это «мозг» команды. Когда уходит ключевой сотрудник, он не уносит всё в голове, процессы не нужно перестраивать — они задокументированы, преемник входит в курс за пару дней.

Клиентский сервис. Клиенты не любят ждать ответа оператора. Они могут найти ответ за пару минут в поиске. Обычно хорошо собранная и структурированная база знаний закрывает до 80% типовых вопросов. Менеджеры поддержки смотрят в один и тот же актуальный документ, а не выдают клиенту три противоречивые версии. Есть возможность посмотреть дату изменения документа.

Техническая документация. Описание API, архитектуры, причин и способов решения инцидентов. Чтобы через полгода команда не гадала что имел в виду автор этого странного комментария в коде. Коллекция конфигов, сниппетов, которые можно переиспользовать, а не писать заново.

Личная база (Second Brain). Даже для одного человека это способ разгрузить голову. Понравившиеся вакансии, идеи проектов, референсы, отзывы или кейсы из практики. Вместо гугления по новой или открытия кучи страниц — открываешь свою заметку.

Суть простая: база знаний нужна там, где стоимость потери информации выше, чем затраты на её ведение. Если в команде больше двух человек или проект длится дольше месяца — это не роскошь, а средство выживания.

Теперь, когда определились зачем, расскажу почему готовые решения не подходят.

Почему не Notion или Google Docs

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

Закрытый формат. Контент хранится в проприетарной системе. Конечно везде есть экспорт. Но попробуйте выгрузить 200 страниц из Notion и сохранить структуру со всеми перелинковками и форматированием — это почти нереально. Я пробовал. Пару раз. Больше не хочу.

Слабая версионность. Google Docs показывает историю правок, но это не git blame. Нельзя посмотреть, кто и когда изменил конкретную строку, нельзя откатить одно изменение, не затронув остальные. Для кода мы давно привыкли использовать git, а для текстовых знаний — почему-то нет.

Зависимость от вендора. API меняются, а цены всё чаще растут. Ваша база знаний уже не ваша, она арендована. Сменится ценовая политика — и вам либо придется платить больше, либо мигрировать. Мигрировать 200 страниц я уже пробовал (см. пункт 1).

AI-воркфлоу отсутствует как класс. Да, в Notion появился AI. Но он не умеет читать папку с исходниками и создавать 10 связанных страниц с перелинковкой и логом. Он не проверит всю wiki на противоречия. Это чат-бот в боковой панели, не более.

Поиск. Когда страниц больше сотни, облачный поиск начинает подтормаживать. А локальный поиск по статическому сайту работает мгновенно.

На какие критерии я ориентировался:

• Контент — просто файлы

• front собирается автоматически

• AI умеет читать исходники и добавлять новые данные

• Быстрый поиск

• Хостинг бесплатный

Такой стек нашёлся.

Как это устроено

В основе идея: Markdown-файлы — единый источник истины. Из них собирается статический сайт. AI-агенты работают с теми же файлами: читают, создают, правят.

Чем мой подход отличается от wiki Карпатого:

LLM AI Карпатого сама решает какие темы развивать и что писать. Это мощно для глубокого ресёрча, но требует доверия к AI и готовности принять его решения. Я к такому пока не готов, если честно.

В моём подходе AI — редактор с чёткими правилами. Файл AGENTS.md задаёт структуру, формат и границы. AI не решает что должно быть в wiki — он помогает оформить то, что я уже знаю и отобрал в исходниках.

AI-агенты│▼┌────────────────────────────────────┐│ Git-репозиторий                    ││ ├── raw/ (исходники)               ││ ├── src/content/ (wiki-страницы)   ││ └── AGENTS.md (схема для AI)       │└────────────────────────────────────┘│▼┌─────────────────────────────────┐│ Astro + Starlight               ││ (сборка статического сайта)     │└─────────────────────────────────┘│▼┌─────────────────────────────────┐│ GitHub Pages                    ││ (хостинг)                       │└─────────────────────────────────┘

Основные скилы AI-редактора:

• Ingest — читает исходник (статью, PDF, заметку) и создаёт связанные страницы с перелинковкой

• Query — поиск ответа по страницам wiki, с возможностью сохранения результата в FAQ

• Lint — проверка здоровья базы: битые ссылки, противоречия, устаревшая информация, страницы-сироты

• Update — обновляет существующие страницы с кросс-проверкой связанных материалов

Всё это описывается в AGENTS.md — «конституции» wiki (структура директорий, формат страниц, правила размещения, язык контента).

Шаг 1: Инициализация проекта

Создаем Astro-проект на шаблоне Starlight:

mkdir my-knowledge-base && cd my-knowledge-basenpm create astro@latest -- --template starlight

Starlight — официальный фреймворк Astro для создания документации. Из коробки даёт: навигацию (sidebar), хлебные крошки, тёмную тему, поиск, MDX-поддержку.

После инициализации получаем:

my-knowledge-base/├── src/content/docs/  # здесь будут страницы wiki├── astro.config.mjs   # конфигурация сайта├── public/            # статика (favicon и т.д.)└── package.json

Создаём две дополнительные директории:

mkdir -p raw/articles  # исходники (статьи, PDF, заметки)mkdir -p raw/assets    # скриншоты, изображения

Настраиваем astro.config.mjs:

import { defineConfig } from "astro/config";import starlight from "@astrojs/starlight";export default defineConfig({  site: "https://your-username.github.io",  base: "/my-knowledge-base",  integrations: [    starlight({      title: "Карьерный консультант",      description: "Персональный карьерный консультант",      locales: { root: { label: "Русский", lang: "ru" } },      sidebar: [        {          label: "Основы",          collapsed: false,          items: [{ autogenerate: { directory: "basics" } }],        },        {          label: "Плагины",          collapsed: true,          items: [{ autogenerate: { directory: "plugins" } }],        },        // ... остальные разделы      ],    }),  ],});

items: [{ autogenerate: { directory: 'some-dir' } }] — в версии Starlight 0.39 автоматически сгенерированные ссылки можно размещать рядом с любыми другими типами ссылок — добавленные страницы автоматически появляются в сайдбаре.

Шаг 2: AGENTS.md — «конституция» wiki

Создаём AGENTS.md в корне проекта:

## AGENTS.md — Схема и правила для LLM-агентов### Структура проекта- raw/ — неизменяемые исходники (READ ONLY для AI)- src/content/docs/ — wiki-страницы (AI пишет сюда)- AGENTS.md — этот файл### Правила оформления страницКаждая страница начинается с frontmatter:---title: "Заголовок страницы"description: "Краткое описание"sidebar:  order: 1---### Операции AI-редактора#### Ingest1. Прочитать исходник из raw/2. Создать 5-15 связанных страниц в нужной категории3. Добавить перекрёстные ссылки4. Обновить index.md и log.md#### Lint1. Проверить все внутренние ссылки2. Найти противоречия между страницами3. Найти страницы-сироты (без входящих ссылок)4. Записать отчёт в log.md#### Query1. Искать ответ строго по страницам wiki2. Указывать источник (файл и строку)3. Если ответа нет — честно сообщить

Этот файл, как README.md для контрибьюторов, только для AI. Он объясняет куда писать, в каком формате, какие операции доступны. С ним AI работает как дисциплинированный редактор.

Шаг 3: AI-агенты в работе

Теперь самое интересное. У меня настроен Claude Code (или OpenCode — работает с любым агентом) с навыками (skills) для работы с wiki.

Пример: ingest статьи про WordPress-плагины.

У меня есть ссылки на официальную документацию и ещё несколько на good practice от сторонних авторов + свои наработки. Я сохраняю их как raw/wordpress-plugin-development-official.md, raw/wordpress-plugin-development-best-practice.md и т.д. Говорю AI:

«/wiki-ingest давай проработаем raw/ в wiki. Разбери по категориям: основы, хуки, безопасность, примеры.»

AI читает файлы и создаёт структуру:

src/content/docs/plugins/├── index.md              # каталог плагинов├── plugin-development.md # основы разработки├── hooks-actions.md      # хуки и экшены├── hooks-filters.md      # хуки и фильтры├── plugin-security.md    # безопасность плагинов├── plugin-i18n.md        # интернационализация└── plugin-examples.md    # примеры плагинов

AI также обновляет index.md — каталог всех страниц и log.md — запись о добавлении.

Пример: lint — проверка здоровья wiki.

Раз в неделю я запускаю:

«Проверь wiki на проблемы.»

AI проходит по всем страницам и находит:

• 3 битые ссылки (страницы переименованы, ссылки не обновлены)

• 2 противоречия (в одной статье написано «используйте wp_enqueue_scripts», в другой — «используйте init»)

• 1 страницу-сироту (есть страница, на которую никто не ссылается)

Всё это записывается в log.md. Я просматриваю отчёт и при необходимости применяю правки.

Шаг 4: Деплой на GitHub Pages

Настраиваем GitHub Actions для автоматической сборки и деплоя. .github/workflows/deploy.yml:

name: Deploy to GitHub Pageson:  push:    branches: [main]jobs:  build-and-deploy:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - uses: actions/setup-node@v4        with:          node-version: 20      - run: npm ci      - run: npm run build      - uses: peaceiris/actions-gh-pages@v3        with:          github_token: ${{ secrets.GITHUB_TOKEN }}          publish_dir: ./dist

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

Для поиска использую Pagefind — он индексирует статический сайт на этапе сборки и даёт мгновенный поиск без внешних сервисов, а ещё работает без танцев с бубном из коробки со Starlight.

Реальные сценарии: три живых примера

1. Карьерный менеджер с анализом рынка и конкурентов

Этот проект — и есть AI-база знаний. Но не про WordPress, а про мою карьеру. Расскажу как устроено.

Проблема: я активно ищу работу и проекты. Нужно держать в актуальном состоянии резюме на hh.ru, LinkedIn, Upwork. Отслеживать рынок: какие навыки в спросе, какие зарплаты, какие тренды. Готовить сопроводительные письма и офферы под конкретные вакансии, на русском и английском — вручную это часы работы.

Решение: база знаний, где AI делает всю рутину.

Структура:

├── raw/                              # исходники (неизменяемые)│   └── 2026/│       ├── 0506/cv-snapshots/        # копии резюме с платформ│       ├── 0905/vacancies/           # понравившиеся вакансии│       └── 1205/vacancies/           # новые вакансии├── src/content/docs/│   ├── cv/ru/                        # резюме на русском│   ├── cv/en/                        # резюме на английском│   ├── market/                       # анализ рынка│   ├── plan/                         # план развития│   ├── cases/                        # портфолио кейсов│   └── process/                      # шаблоны и чеклисты└── AGENTS.md                         # схема для AI

Как это работает на практике:

Я нахожу интересную вакансию — например, Team Lead в финтех-компании. Сохраняю описание в raw/2026/0905/vacancies/rukovoditel-gruppy-razrabotki.md. Говорю AI:

«Проанализируй эту вакансию и обнови анализ рынка.»

AI читает вакансию и обновляет:

• market/demand-analysis.md — добавляет требования в сводку по технологиям

• market/skills-heatmap.md — отмечает востребованные навыки (Team Lead, AI-инструменты, high-load)

• plan/skills-upgrade.md — если в вакансии есть навык, которого у меня нет — добавляет в план прокачки

Потом говорю:

«Сгенерируй cover letter под эту вакансию, используя моё резюме и анализ рынка.»

AI берёт данные из cv/ru/hh-ru.md, сопоставляет с требованиями вакансии и создаёт персонализированное сопроводительное письмо.

Результат: вместо ручного обновления резюме раз в полгода — живая система. AI отслеживает рынок, подсвечивает что учить, что добавить в CV, генерирует cover letter. Время на подготовку отклика сократилось с 2-3 часов до 15 минут.

2. Публичная база знаний WordPress

wpcraft.ru/kb/ — 50+ страниц по WordPress-разработке на русском. AI переработал десятки статей и заметок в структурированную wiki с перелинковкой и поиском.

3. База знаний для техподдержки

ddpa.ru/kb/ — AI-консультант по полезным сервисам и приложениям. Поиск сервисов и инструментов по ключевым словам.

Что получилось в итоге

За 7 дней я получил работающую систему. Не прототип, не концепцию — систему, которой пользуюсь каждый день.

Цифры:

• 50+ страниц в публичной базе знаний WordPress

• 30+ страниц в карьерном менеджере

• 3 разных сценария использования на одном стеке

• Время на обновление CV: с нескольких часов до минут

Техника:

• Мгновенный поиск (Pagefind)

• Хостинг бесплатный (GitHub Pages)

AI-воркфлоу, ради которого всё затевалось:

• Ingest: загрузил сырые материалы → получил несколько связанных страниц

• Lint: запустил проверку → получил отчёт о проблемах с материалами в базе

• Query: задал вопрос → получил ответ с источником и сохранил в FAQ

Работает не идеально — иногда промахивается с категорией или создаёт избыточные страницы, но 80% работы делает сам, остальное — человеческая редактура.

Что дальше

Из ближайшего:

• CI/CD для контента. Автотесты на битые ссылки и орфографию в пайплайне. Чтобы при пуше сразу видеть, что сломалось.

• Мультиязычность. Starlight поддерживает из коробки, надо просто настроить. Английская версия для Upwork и LinkedIn уже в процессе.

Из идей на подумать:

• Документация продукта в том же репозитории, что и код. Чтобы документация жила рядом с исходниками и обновлялась вместе с релизами.

• Онбординг новых сотрудников: AI-консультант, который отвечает на вопросы новичков по внутренней базе.

• Внутренний портал компании: стандарты, FAQ, гайды и документация — всё в одном месте с поиском.

Главное, что я понял за эту неделю:

AI-база знаний — это не про «заменить человека». Это про то, чтобы перестать тратить время на структурирование заметок, обновление CV и написание cover letter. AI берёт на себя рутину. Я проверяю результат и принимаю решения.

Если вы тоже тонете в заметках и устали от ручного управления знаниями — попробуйте этот стек. Настройка занимает вечер. Дальше AI работает сам.

Ссылки:

• База знаний WordPress: wpcraft.ru/kb/

• База знаний техподдержки: ddpa.ru/kb/

А вы пробовали строить AI-базы знаний для своих задач? Что получилось, что нет? Делитесь в комментариях — интересно сравнить подходы.