Hub

Hub — гибридная open-source платформа Opensophy для документации, публикации контента и демонстрации UI-компонентов. Проект объединяет статический сайт на Astro, расширенный Markdown-движок, навигацию на основе файловой структуры, поиск, интерактивные таблицы и библиотеку React-компонентов с живыми примерами — без отдельной CMS.

Демонстрация форматирования — GitHub репозиторий

Возможности платформы

Сортировка, мультиселект фильтры, поиск с подсветкой совпадений, скрытие колонок, fullscreen-режим, drag-to-scroll и HTML-контент в ячейках — всё из Markdown.

Карточки, колонки, степпер, диаграммы, алерты и многое другое в чистом Markdown — без MDX и плагинов. Работает из коробки.

Интерактивный playground прямо в документации. Настраивайте scale, rotation, blur, gradient и скорость анимации для любого компонента в реальном времени.

Лаконичный и современный дизайн с поддержкой тёмной и светлой темы, плавными переходами и mobile-first навигацией через bottom bar.

Папки в Docs/ — это и есть навигация на сайте. Никакой настройки роутинга: сайдбар и breadcrumbs генерируются автоматически.

Сложные Markdown-блоки пишутся в разы короче. Изображения, алерты и компоненты — без лишнего кода.

Для чего нужен Hub

вести документацию проекта — архитектура, инструкции, гайды, справочники, changelog-страницы;
публиковать образовательные материалы — статьи по разработке, Linux, безопасности, DevSecOps и инструментам;
поддерживать UI-библиотеку — хранить компоненты, конфиги, демо и описание использования;
создавать сайт без CMS — всё управляется файлами, Git и сборочными скриптами;
объединять лендинг и документацию — главная страница может быть визуальным React-лендингом или обычным welcome.md;
ускорять работу с таблицами и кодом — таблицы получают фильтры, сортировку, поиск, полноэкранный режим и копирование.

Архитектура

Hub построен как Astro-приложение с React-островами. Astro отвечает за маршруты, сборку и статическую генерацию, React — за интерактивные части: навигацию, темы, документацию, таблицы, лендинг, панель администратора и UI-превью.

Слой	Где находится	За что отвечает
Приложение	`src/app/`	Astro layout, главная страница, 404 и динамический маршрут документации.
Документы	`Docs/`	Markdown-контент, структура разделов, категории и статьи.
Генерация	`scripts/`	Сканирование Docs, сборка manifest, sitemap и подготовка данных для сайта.
Документация	`src/features/docs/`	Отображение статьи, hero, оглавление, прогресс скролла и Ask AI-кнопка.
Навигация	`src/features/navigation/`	Сайдбар, разделы, поиск, мобильная навигация и панель оглавления.
UI-компоненты	`src/features/ui-components/`	Registry, loader, конфиги, компоненты и интерактивный viewer.
Таблицы	`src/features/table/`	Фильтрация, сортировка, скрытие колонок, поиск, копирование и fullscreen.
Общие элементы	`src/shared/`	Компоненты, контексты темы, стили, токены и вспомогательные библиотеки.
Публичные данные	`public/data/`	Конфиг сайта и сгенерированный manifest документации.

Основная идея

Контент пишется как обычные .md файлы, но Hub добавляет несколько уровней поверх Markdown:

Frontmatter — метаданные страницы: title, description, date, author, tags, icon, lang и robots.
Система имён файлов — папки и файлы вида [N], [C], [A] задают разделы, категории, иконки и URL.
Генерация manifest.json — скрипт собирает все документы в единый индекс для навигации и поиска.
React-рендеринг документа — страница отображается через DocContent с темой, hero-блоком, оглавлением и расширениями.
Расширенный Markdown — карточки, колонки, шаги, алерты, детали, KaTeX, изображения и интерактивные таблицы.

Как работает документация

Файл размещается в Docs/ и получает имя по схеме [A][icon]Название{slug}.md.

npm run generate запускает генерацию manifest и sitemap на основе файловой структуры и frontmatter.

Динамический маршрут src/app/pages/[...slug].astro находит документ по slug и передаёт его в React-компонент документации.

DocContent показывает hero, дату, автора, время чтения, оглавление, теги, Markdown-расширения и интерактивные блоки.

Навигация и структура URL

Файловая структура напрямую определяет навигацию и URL:

Docs/
└── [N][book]Документация Hub{hub}/
    ├── [A][boxes]Hub{general}.md
    ├── [A][album]Полное руководство по форматированию Markdown в Hub{markdown-guide}.md
    └── [A][layout-grid]Руководство по добавлению новых UI компонентов{component-guide}.md

[N] создаёт верхнеуровневый раздел в навигации;
[book] задаёт иконку раздела;
Документация Hub — человекочитаемое название;
{hub} — URL-префикс раздела;
[A] обозначает статью;
{general} задаёт итоговый slug страницы: /hub/general/.

Главная страница

Лендинг

Когда useLanding: true, главная страница показывает React-лендинг Opensophy: hero-секцию, WebGL-визуал, блок о проекте, карточки направлений и экосистему Opensophy.

welcome.md

Когда useLanding: false, главная страница рендерит Docs/welcome.md как обычную Markdown-страницу со всеми расширениями Hub.

Переключение хранится в public/data/site-config.json.

UI-библиотека

Компонент добавляется как папка с React-файлом и config.json. Registry автоматически находит конфиги через import.meta.glob, loader подгружает компонент и исходники для просмотра.

src/features/ui-components/
└── my-component/
    ├── my-component.tsx
    └── config.json

config.json описывает название, категорию, props, controls, теги, автора и версию. После этого компонент доступен в документации и в интерактивном viewer с настройками.

Технологический стек

Astro — маршруты, layout, статическая генерация и островная архитектура;
React — интерактивные компоненты и сложные интерфейсные состояния;
TypeScript — типизация компонентов, конфигов и внутренних API;
Framer Motion / GSAP / Three / OGL — анимации и визуальные эффекты;
Marked и KaTeX — обработка Markdown и формул;
Lucide React — иконки для интерфейса и навигации;
Recharts — графики внутри контентных блоков;
Tailwind CSS и design tokens — базовые стили и консистентная тема.

Быстрый старт

npm install
npm run generate
npm run dev

После запуска:

Добавьте новую статью в Docs/.
Заполните frontmatter.
Выберите иконку и slug в имени файла.
Запустите npm run generate.
Откройте страницу в браузере.

При необходимости добавьте UI-компонент в src/features/ui-components/.

Создай свой Hub

Проект полностью open-source — берите, адаптируйте, публикуйте свой контент.

Перед использованием ознакомьтесь с README и лицензией: github.com/opensophy-projects/hub