Структура src/

Что такое исходный код и source

Исходный код (source code) — текст программы, который читает человек и который превращается в исполняемый бандл при сборке. В репозитории it-knowledge-base это в основном JavaScript, TypeScript, React, CSS и markdown в docs/.

Source (англ. "источник") в контексте фронтенда — каталог src/ с кастомным кодом поверх Docusaurus. Контент статей лежит в docs/; src/ отвечает за то, как контент выглядит, ведёт себя в браузере и связывается с внешними сервисами play.spirzen.ru и code.spirzen.ru.

Разделение близко к слоям приложения — данные (docs/, data/), представление (components/, theme/, css/), интеграции (constants/, embed).

Карта каталогов src/

src/
├── clientModules/     # Скрипты при загрузке каждой страницы
├── components/        # React — embeds, поиск, хабы, article chrome
├── constants/         # URL code/play, trusted origins
├── css/               # Глобальные стили и дизайн-система
├── data/              # JSON/JS — подборки, иконки, темы, индексы
├── pages/             # Лендинг / (homepage)
├── remark/            # Плагины markdown (wiki, lazy import)
├── theme/             # Swizzle-компоненты Docusaurus
├── utils/             # API палитр, PDF
├── types.d.ts
└── docusaurus-shims.d.ts

Отдельной папки hooks/ нет — хуки лежат в components/shared/ и рядом с фичами (useCollectionArticleLists.js, useDocSearchState.js).

Папка	Роль в одном предложении
`clientModules/`	JS вне React при загрузке страницы
`components/`	Переиспользуемые React-компоненты для MDX и theme
`constants/`	Константы URL и trusted origin
`css/`	Глобальный стиль и дизайн-система
`data/`	Статические списки маршрутов, иконок, индексов
`pages/`	Homepage — точка входа `/`
`remark/`	CommonJS-плагины на этапе сборки
`theme/`	Переопределение UI Docusaurus (swizzle)
`utils/`	Чистые функции — API палитр, PDF

Связанные артефакты вне src/ — static/doc-search-index.json (генерация скриптом), static/img/, корневые конфиги.

clientModules/

Подключаются в docusaurus.config.js → clientModules. Это клиентский модуль — обычный JS, выполняемый при старте бандла, вне дерева React.

Файл	Назначение
`itThemeStorageGuard.js`	Сброс битых ключей color mode в localStorage
`itDesignThemeInit.js`	Синхронизация `data-design` при SPA-навигации
`limitRoutePrefetch.js`	Ограничение prefetch тяжёлых маршрутов

itDesignThemeInit восстанавливает палитру из localStorage после клиентского перехода — SSR уже выставил data-design через inject в config, клиент подтверждает при каждой загрузке страницы.

limitRoutePrefetch подменяет window.docusaurus.prefetch — для префиксов /encyclopedia/, /lab/ и т.д. не тянуть заранее тяжёлые HTML-чанки.

components/

Самая большая папка (~50 файлов). React-компоненты импортируют из MDX (import X from '@site/src/components/...') или подключаются из swizzle-темы через lazyDemo.

Embeds

Компонент	Сервис	Механизм
`ExternalPlayEmbed.jsx`	play.spirzen.ru	iframe `/p/embed/<slug>/`
`ExternalCodeEmbed.jsx`	code.spirzen.ru	iframe `/e/embed/<slug>/`
`DeveloperExamPlay.jsx`	play (экзамены лаборатории)	Обёртка над play

postMessage от iframe передаёт высоту; принимают только trusted origin из constants/. Подробнее — Архитектура.

shared/ — инфраструктура демо

Файл	Роль
`lazyDemo.js`	Lazy import + Suspense
`lazyDemoInView.js`	Загрузка при появлении в viewport
`lazyExternalEmbed.js`	Отложенный embed
`EmbedClickGate.jsx`	Click-to-load перед iframe
`embedLoadQueue.js`	Очередь одновременных embed
`useEmbedViewport.js`	Стабильная высота iframe
`DemoShell.jsx`, `demoFallback.jsx`	Оболочка и скелетон
`deferredIdle.js`	`requestIdleCallback` для DOM-правок
`useBreakpoint.js`, `useCopyToClipboard.js`	Hooks

Article chrome

Блоки вокруг текста статьи, подключаются из theme/DocItem/Layout без правок MDX.

Компонент	Функция
`TechArticleHero.jsx`	Hero с иконкой технологии
`ArticlePdfExport.jsx`	Экспорт в PDF
`ArticleSeeAlso.jsx`	See-also — подборки
`ArticleRelated.jsx`	Related — связанные статьи
`RandomChecklistItem.jsx`	Случайный пункт чеклиста
`RandomQuestionFromArticle.jsx`	Вопрос из текста

Article chrome — обвязка doc-страницы (hero, TOC-панель, прогресс, см. также) вокруг тела markdown.

Навигация и хабы

Компонент	Роль
`UniverseMap.jsx`	Карта 9 разделов энциклопедии
`GettingStartedPaths.jsx`	Пути для новичков
`CollectionHub.jsx`	Хаб подборок
`LabTrainersHub.jsx`	Хаб тренажёров лаборатории
`HomepageHeroSearch/`	Поиск на homepage

Хаб — страница-агрегатор со списком ссылок на статьи темы.

DocSearch/ — провайдер поиска

DocSearchContext.jsx — React Context (провайдер состояния поиска). DocSearchModal, DocSearchBar, docSearchEngine.js читают static/doc-search-index.json. Кнопка Ctrl+K — в theme/NavbarItem/DocSearch.

Подробнее — Компоненты.

theme/ — swizzle и переопределение

Swizzle копирует компоненты @docusaurus/theme-classic в src/theme/; Docusaurus подхватывает их вместо стандартных. Это переопределение layout, navbar, sidebar, карточек.

Swizzle-компонент	Зачем
`Root/index.tsx`	Провайдер поиска + fallback-sidebar
`DocItem/Layout/index.tsx`	PDF, TOC-панель, hero, related, see-also, прогресс чтения
`DocRoot/Layout/index.tsx`	Оверлей sidebar, back-to-top
`DocSidebar/Desktop/Content`	Поиск по sidebar, resize ширины
`Navbar/Layout`, `ColorModeToggle`	DesignThemePicker + light/dark
`NavbarItem/DocSearch`	Кнопка поиска
`DocCard/index.tsx`	SVG/эмодзи технологий на карточках
`DocCategoryGeneratedIndexPage`	Оформление автоген-оглавлений

DOM-улучшения после рендера

articleMetaEnhancement.ts и articleSectionEnhancement.ts — кликабельность тегов, обёртка секций .doc-section вокруг h2. Запускаются из layout через scheduleIdleWork после отрисовки.

DocSidebarFallback

DocSidebarFallback/ — fallback для узкого desktop: оверлей бокового меню, если классический sidebar скрыт. Activator.tsx вешает кнопку "меню раздела".

SidebarResizeHandle.jsx + useSidebarAutoWidth.js — перетаскивание границы sidebar, ширина в localStorage. Работает на desktop.

ChapterProgress

ChapterProgress.tsx — полоска прогресса прокрутки статьи (процент видимого текста в viewport).

data/

Статические данные — JS-модули и JSON. Часть файлов генерируется скриптами перед сборкой.

Файл	Тип	Содержимое
`sidebarCollections.js`	JS	Маршруты подборок для homepage и `/about/collections`
`encyclopediaSections.js`	JS	9 разделов карты вселенной
`itDesigns.json`	JSON	Палитры оформления
`techIconRegistry.js`	JS	id технологии → SVG/эмодзи
`techIconPaths.js`	JS	Автоген SVG paths (`docs:tech-icon-paths`)
`techArticlePages.js`	JS	Префикс doc → tech id для hero
`collectionDocTitles.json`	JSON	id → заголовок (генерация скриптом)
`encyclopediaTermLinks.json`	JSON	Термин → URL
`wikiLinkIndex.json`	JSON	Индекс `[[wiki]]` (генерируется)
`docLegacyRedirects.json`	JSON	Редирект старых URL (генерируется)
`languagePrerequisitesTopics.json`	JSON	Темы для планов языков
`englishPlanVocabulary.json`	JSON	Словарь плана английского

css/ — стили и дизайн-система

Точка входа — custom.css (плюс it-design-code-overrides.css в config). Цепочка @import.

Файл	Роль
`it-design-themes.css`	Переменные для каждой `data-design`
`it-design-bridge.css`	Мост `--d-` → Infima `--ifm-`
`it-design-color-mode.css`	Light/dark внутри палитры
`article-docs-prime.css`	Типографика статей
`sidebar-explorer.css`, `sidebar-cosmic-explorer.css`	Оформление sidebar
`doc-search-theme.css`	Стили поиска
`navbar-layout.css`	Navbar
`site-chrome.css`	Общая хромированная оболочка сайта

Дизайн-система — набор палитр data-design + мост к Infima + эффекты (it-design-effects.css). API палитр в utils/itDesignTheme.ts. Подробнее — Темы и стили.

Глобальный стиль — CSS из customCss в config на весь сайт; *.module.css у компонентов действует локально.

remark/ — плагины markdown

CommonJS-модули, подключённые в docusaurus.config.js → remarkPlugins. Работают на этапе сборки, в браузере не выполняются.

Плагин	Назначение
`wikiLink.js`	`[[термин]]` → ссылка по `wikiLinkIndex.json`
`lazyMdxDemoImports.js`	Переписывает `import` тяжёлых компонентов на lazy import

Remark обходит AST markdown до компиляции MDX — часть пайплайна контента.

pages/ — homepage и лендинг

index.js — лендинг маршрута / (homepage). Hero, поиск, ленивые UniverseMap, GettingStartedPaths, RandomArticle.

Остальной контент — docs с routeBasePath: '/', поэтому URL /encyclopedia/intro идут из docs/, а корень / — из pages/.

constants/

Файл	Роль
`embedServiceUrl.js`	prod vs localhost для embed-URL
`codeExamples.js`	URL и postMessage origins для code.spirzen.ru
`playExamples.js`	То же для play.spirzen.ru

resolveEmbedServiceBaseUrl на localhost:3000 подменяет прод-URL на локальные порты — тест локальной связки embed без правки prod-конфига.

Trusted origin — whitelist доменов для postMessage (защита от поддельных сообщений о высоте iframe).

utils/ и shims

Файл	Назначение
`itDesignTheme.ts`	API палитр — `applyItDesign`, `readStoredItDesignId`
`exportArticlePdf.js`	html2canvas + jsPDF для кнопки в layout

docusaurus-shims.d.ts и types.d.ts — shim-типы для IDE (TypeScript), не runtime-код.

docs/ vs src/

	`docs/`	`src/`
Содержимое	Markdown, MDX, статьи	Код, стили, theme
Навигация	sidebars.js, `_category_.json`	Компоненты UI
Сборка	remark → MDX → React-страницы	Webpack-чанки, swizzle

Статья в docs/ — файл .md/.mdx с frontmatter. Глава — логическая часть учебного раздела (например, глава "Как устроена Вселенная IT"). Раздел — крупный блок энциклопедии (encyclopedia/, lab/, …). Секция — фрагмент внутри одной страницы (h2 + абзацы, обёртка .doc-section).

Поток зависимостей

Куда класть новый код

Задача	Папка
Виджет в одной статье	`components/` + import в MDX
Блок на всех статьях	`theme/DocItem/Layout`
Пункт navbar	`theme/Navbar*` или `NavbarItem/`
Статический список маршрутов	`data/*.js` или JSON
Глобальный стиль	`css/`
Синтаксис markdown	`remark/`
Скрипт при загрузке сайта	`clientModules/`
URL внешнего API	`constants/`

Глоссарий

Исходный код

Текст программы до сборки; в проекте — src/, docs/, scripts/, конфиги.

source / src

Каталог src/ — кастомный код Docusaurus поверх шаблона.

Код

Инструкции на JS/TS/CSS; см. выполнение кода.

Кастомный код

Всё в src/, чего нет в стандартном шаблоне Docusaurus — theme, компоненты, стили.

React-компоненты

Функции/классы, возвращающие JSX; основа UI. React — компоненты.

Переопределение

Замена стандартного компонента темы своей версией в src/theme/ (swizzle).

Стили

CSS в src/css/ и *.module.css у компонентов.

remark-плагины

Обработчики markdown при сборке; см. package.json и стек.

Клиентский модуль

Файл из clientModules/ — выполняется при загрузке бандла, вне React.

Контент

Текст и медиа статей в docs/; компоненты его оборачивают и дополняют.

Статья

Один документ в docs/ (.md/.mdx); id и slug.

Скрипт

JS-модуль — clientModules/, scripts/*.mjs (пайплайн), или inline в config.

Загрузка страницы

Первый HTTP-запрос HTML/JS или клиентский переход в SPA; clientModules срабатывают при старте бандла.

Компонент

Единица UI в React; файл в components/ или theme/.

Константа

Незменяемое значение — URL, ключ storage, список origins в constants/.

embed

Встраивание внешнего UI (iframe) — play, code, экзамены.

Хаб

Страница-агрегатор ссылок (CollectionHub, LabTrainersHub).

article chrome

Обвязка doc-страницы — hero, PDF, related, see-also, прогресс, TOC-панель.

trusted origin

Доверенный домен для postMessage от iframe.

Дизайн-система

Палитры data-design, CSS-переменные, мост Infima, picker в navbar.

docs

Плагин и папка docs/ — основной контент сайта.

lazy import

import() + React.lazy — отложенная загрузка чанка.

swizzle-компонент

Копия компонента @docusaurus/theme-classic в src/theme/.

shim

Заглушка типов (docusaurus-shims.d.ts) для IDE.

hooks

React-хуки (useState, useDoc, useEmbedViewport) в shared/ и DocSearch.

shared

components/shared/ — общая инфраструктура embed и lazy.

Ключи color mode

Записи localStorage с префиксом theme (light/dark Docusaurus).

localStorage

Хранилище браузера для темы, дизайна, ширины sidebar.

SPA

Single Page Application — навигация без полной перезагрузки. Docusaurus после первой загрузки.

Синхронизация

Согласование состояния при переходах — data-design, color mode, iframe theme query.

prefetch

Предзагрузка следующей страницы Docusaurus Link; ограничена для /encyclopedia/.

Маршрут

URL ↔ страница (/encyclopedia/intro, /). См. route.

Бандл

Собранный JS/CSS для браузера; src/ режется на чанки.

play.spirzen.ru

Сервис интерактива — тренажёры, /p/embed/<slug>/. См. Архитектура.

code.spirzen.ru

Сервис примеров кода — /e/embed/<slug>/, ExternalCodeEmbed.

iframe

HTML-элемент вложенной страницы; embed play/code.

Провайдер поиска

DocSearchProvider — Context для модального поиска.

fallback

Запасной UI — sidebar overlay, skeleton embed, эмодзи вместо SVG.

Боковое меню документации; swizzle в theme/DocSidebar/. См. sidebars.js.

hero

Верхний баннер страницы — TechArticleHero, homepage header.

Блок связанных статей — ArticleRelated.jsx.

see-also

Блок "См. также" / подборки — ArticleSeeAlso.jsx.

Прогресс чтения

ChapterProgress — индикатор прокрутки статьи.

Оверлей

Плавающий слой поверх контента — sidebar fallback на узком desktop.

back-to-top

Кнопка прокрутки вверх в DocRoot/Layout.

resize

Изменение ширины sidebar перетаскиванием (SidebarResizeHandle).

desktop

Широкий viewport; отдельные layout-решения от mobile/tablet.

pick

Выбор палитры — DesignThemePicker в navbar/sidebar.

Верхняя панель; swizzle Navbar/Layout, ColorModeToggle.

Кликабельность

Интерактивные теги и badge после articleMetaEnhancement.

Секция

Фрагмент статьи под h2 (обёртка .doc-section).

Раздел

Крупная ветка сайта или энциклопедии (1-basics, lab/).

Глава

Часть внутреннего учебного раздела (файлы 01-, 02- в "Как устроена Вселенная IT").

homepage

Главная / — src/pages/index.js.

Палитра оформления

Запись в itDesigns.json + CSS для data-design.

SVG

Векторная иконка технологии из techIconPaths.js.

Эмодзи

Запасной badge в techIconRegistry (fallback: '🐍').

Автоген

Автоматически сгенерированный файл (techIconPaths.js, wikiLinkIndex.json).

Префикс

Начало пути или id (5-01-, префикс doc для hero).

Редирект

Перенаправление старого URL — docLegacyRedirects.json, plugin redirects.

Индекс

JSON-каталог для поиска или wiki (doc-search-index, wikiLinkIndex).

Точка входа

Главный файл модуля — custom.css, pages/index.js, Root/index.tsx.

Переменные

CSS custom properties (--ifm-*, --d-*) в css/.

Типографика

Размеры шрифтов, межстрочный интервал статей — article-docs-prime.css.

Мост

it-design-bridge.css — сопоставление --d-* с Infima --ifm-*.

Infima

CSS-фреймворк темы Docusaurus. См. package.json и стек.

CommonJS

require/module.exports — remark, часть theme require('@theme/...').

Сборка

npm run build → build/. См. package.json и стек.

Лендинг

Маркетинговая главная / с hero и CTA.

prod

Продакшен — spirzen.ru, code/play на spirzen.ru; против localhost в constants.

postMessage

API браузера для сообщений между окном и iframe (высота embed).

Тест локальной связки

Разработка с локальными code/play на портах 4321/4322 через resolveEmbedServiceBaseUrl.

API

Программный интерфейс — applyItDesign, URL embed-сервисов, поисковый индекс.

API палитр

Функции itDesignTheme.ts — чтение/запись активного data-design.

Генерация скриптом

scripts/*.mjs пишут JSON в src/data/ или static/ перед build.

Глобальный стиль

CSS из customCss в config, действует на весь сайт.

Связь с другими главами

Архитектура — spirzen, code, play, assets, embed-паттерны.
TypeScript — .tsx в theme/, shims, itDesignTheme.ts.
Компоненты — детали embed, DocSearch, MDX.
Темы и стили — CSS-цепочка, палитры.
Данные и скрипты — генераторы индексов.
docusaurus.config.js — clientModules, customCss, remark.

Что такое исходный код и source​

Карта каталогов src/​

clientModules/​

components/​

Embeds​

shared/ — инфраструктура демо​

Article chrome​

Навигация и хабы​

DocSearch/ — провайдер поиска​

theme/ — swizzle и переопределение​

DOM-улучшения после рендера​

DocSidebarFallback​

Sidebar resize​

ChapterProgress​

data/​

css/ — стили и дизайн-система​

remark/ — плагины markdown​

pages/ — homepage и лендинг​

constants/​

utils/ и shims​

docs/ vs src/​

Поток зависимостей​

Куда класть новый код​

Глоссарий​

Исходный код​

source / src​

Код​

Кастомный код​

React-компоненты​

Переопределение​

Стили​

remark-плагины​

Клиентский модуль​

Контент​

Статья​

Скрипт​

Загрузка страницы​

Компонент​

Константа​

embed​

Хаб​

article chrome​

trusted origin​

Дизайн-система​

docs​

lazy import​

swizzle-компонент​

shim​

hooks​

shared​

Ключи color mode​

localStorage​

SPA​

Навигация​

Синхронизация​

prefetch​

Маршрут​

Бандл​

play.spirzen.ru​

code.spirzen.ru​

iframe​

Провайдер поиска​

fallback​

sidebar​

TOC​

hero​

related​

see-also​

Прогресс чтения​

Оверлей​

back-to-top​

resize​

desktop​

pick​

navbar​

Кликабельность​

Секция​

Раздел​

Глава​

homepage​