Кейс · Сайт

Сверло: генератор документации на Node.js

Генератор статических сайтов документации, написанный с нуля на Node.js без зависимостей: собственный Markdown-парсер, подсветка кода и офлайн-поиск. Демо-сайт про вымышленную библиотеку «Сверло» собран из 43 страниц на двух языках (RU и EN) и двух версиях (v1 и v2). Пет-проект.

  • Node.js
  • JavaScript (ESM)
  • zero dependencies
  • Markdown
  • Cloudflare Pages
  • GitHub Actions
Открыть живой сайт ewsirdev-docs.pages.devКод по запросу в Telegram

01 · Как выглядит

Скриншоты

Скриншот проекта «Сверло: генератор документации на Node.js» на экране 1280 пикселей
Десктоп, 1280 px
Скриншот проекта «Сверло: генератор документации на Node.js» на экране телефона, 390 пикселей
Телефон, 390 px

02 · О проекте

Что это и зачем

«Сверло» (docs-engine) — генератор статических сайтов документации на Node.js (ESM) без единой зависимости и демо-сайт, который он собирает: документация вымышленной библиотеки для разбора логов. Библиотеки не существует, сайт честно помечен как демо; настоящий здесь генератор. Пет-проект.

Markdown разбирается собственным парсером, код подсвечивается собственным токенизатором, а индекс поиска строится при сборке и тем же файлом ищет в браузере. Сайт читается полностью без JavaScript: скрипт добавляет только поиск, тему и кнопки копирования.

Ограничения

Содержимое про «Сверло» вымышленное, числа производительности в нём помечены как целевые.

В Markdown нет блоков кода с отступом, ссылок-ссылок и HTML-вставок. Подсветка это регулярный токенизатор без разбора грамматики: на вложенных шаблонных строках и regex-литералах возможны неточности.

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

Нужен Node.js 22+ (проверено на 24). Браузерная проверка (поиск, тема, язык, axe) выполнялась вручную по CDP и в CI не входит.

Что внутри

  • Markdown: заголовки с {#id}, вложенные списки и задачи, таблицы с выравниванием, блоки кода, сноски, врезки ::: note; front matter и include-директивы только из каталога site/includes
  • Подсветка js/ts, json, bash, yaml, log, diff и http: токены всегда склеиваются обратно в исходный текст
  • Версии документации (v1, v2) и два языка (ru, en) с hreflang; переключатели сохраняют страницу, если у неё есть пара
  • Поиск на клиенте без библиотек: индекс при сборке, русский и английский стемминг, префиксы, ранжирование, подсветка, работает офлайн через service worker
  • Навигация из дерева файлов, хлебные крошки, оглавление, «назад/дальше»; тёмная и светлая темы, RSS из журнала изменений
  • sitemap.xml с xhtml:link, robots.txt, llms.txt, security.txt, JSON-LD TechArticle и BreadcrumbList, канонические адреса
  • 131 тест: парсер, подсветка (без потери символов), навигация, поиск, санитизация (XSS-нагрузки), golden-структура страниц; в CI проверка битых ссылок и якорей, hreflang и безопасности CSP
  • Живая версия собрана командой npm run build и выложена на Cloudflare Pages (прямая загрузка dist)

03 · Как запустить

Запуск одной командой

git clone <репозиторий по запросу> docs-engine
cd docs-engine
npm test
npm run build   # dist/ со статическим сайтом

04 · Код

Репозиторий приватный

Исходники лежат в приватном репозитории. Напишите в Telegram, открою доступ.

Запросить код