Перейти к основному содержимому

Данные и скрипты

Что такое данные, скрипт и контент​

Данные — структурированная информация, с которой работает сайт помимо текста статей. В it-knowledge-base это JSON-файлы, JS-каталоги маршрутов, индексы для поиска и wiki, карты редиректов. См. типы данных и формат JSON в энциклопедии.

Контент — тексты и разметка в docs/ (~3000 .md/.mdx). Данные живут рядом — в src/data/, static/, генерируются скриптами из scripts/ на Node.js.

Скрипт — программа на Node (.mjs в scripts/), которая обходит docs/, парсит frontmatter, пишет артефакты перед npm start / npm run build. Это слой автоматизации поверх Git-репозитория.

Поток данных отделяет авторский контент от машиночитаемых справочников, которые питают поиск, wiki, подборки и enhancement.

Два типа данных​

ТипПримерыКто меняет
РучныеsidebarCollections.js, itDesigns.json, encyclopediaTermLinks.jsonАвтор в PR
ГенерируемыеwikiLinkIndex.json, doc-search-index.json, collectionDocTitles.json, docLegacyRedirects.jsonnpm run docs:*
ФайлВ gitЛокальность
wikiLinkIndex.jsonв .gitignoreкаждый dev генерирует при docs:wiki-links
docLegacyRedirects.jsonв .gitignoreпри docs:redirects
static/doc-search-index.jsonобычно в репозиторииобновляется при docs:search-index
collectionDocTitles.jsonв репозиториипри docs:collection-titles (только build)

Без генерации dev-режим (npm start) всё равно стартует, но wiki-поиск и редиректы могут быть пустыми или устаревшими.

dev/build и npm-скрипты​

Командаdocs:* перед DocusaurusНазначение
npm startwiki-links → search-index → redirectsDev-режим, hot reload
npm run build+ collection-titlesСборка prod в build/

Полный список docs:* — в package.json и стек. Скрипты в scripts/*.mjs по умолчанию в .gitignore, в репозитории остаются только whitelisted (build-wiki, search-index, redirects, collection-titles, fix-imports…).

src/data/ — справочник​

sidebarCollections.js — JS-каталог подборок​

Массив SIDEBAR_COLLECTIONS — тематические маршруты (emoji, label, список doc id). Питает следующие блоки.

  • GettingStartedPaths на homepage и /about/collections
  • CollectionHub, useCollectionArticleLists
  • блоки "В подборках" в статьях (через enhancement и данные)

encyclopediaSections.js​

Девять крупных разделов для UniverseMap.

techIconRegistry.js + techIconPaths.js​

Сопоставление tech id (python, docker…) с SVG Simple Icons или emoji. techIconPaths.js — автоген (docs:tech-icon-paths).

techArticlePages.js​

Связывает префикс пути статьи (папка энциклопедии) с tech id — для TechArticleHero и DocCard.

collectionDocTitles.json​

docId → заголовок для длинных списков в CollectionHub (генерация скриптом docs:collection-titles).

encyclopediaTermLinks.json — обогащение​

Ручной словарь "термин → URL" для обогащения ссылок; подмешивается в build-wiki-link-index.mjs после глоссария и уникальных title.

wikiLinkIndex.json — JSON-индекс wiki​

{
  "terms": {
    "python": {
      "href": "/encyclopedia/5-languages/5-02-python/intro",
      "kind": "encyclopedia",
      "label": "Python — о разделе"
    }
  }
}

Строится build-wiki-link-index.mjs из ## заголовков глоссария, уникальных title статей энциклопедии и encyclopediaTermLinks.json. Поле kind — glossary | encyclopedia | explicit | external (для CSS-класса ссылки).

docLegacyRedirects.json​

Карта "канонический путь → массив старых путей" для @docusaurus/plugin-client-redirects. Учитывает историю путей, slug из frontmatter, старые кириллические сегменты.

Запуск — npm run docs:wiki-links (обязателен перед dev/build).

  1. Обход docs/glossary/ — каждый ## заголовок → ключ через normalizeKey (locale ru, регистронезависимость).
  2. Обход docs/encyclopedia/ — title из frontmatter; в индекс попадают только уникальные title (дубликаты пропускаются).
  3. Слияние с encyclopediaTermLinks.json (ручные записи имеют приоритет там, где заданы).
  4. Запись src/data/wikiLinkIndex.json.

Канонический URL — resolveDocHref в scripts/lib/docUrl.mjs (как Docusaurus: slug или путь от docs/).

remark/wikiLink.js — remark-плагин​

Remark-плагин CommonJS на этапе сборки. Синтаксис только явный.

См. [[Python]] и [[SQL|язык запросов]].
Прямой путь: [[/glossary/intro|глоссарий]].
Внешнее: [[https://example.com|пример]].
ШагДействие
1Регэксп WIKI_LINK_RE находит [[...]] вне code/link/jsx
2Термин ищется в wikiLinkIndex.json (регистр нормализуется, toLocaleLowerCase('ru'))
3Путь с / — явная ссылка; http — внешняя ссылка
4Выход — HTML <a class="wiki-link wiki-link--encyclopedia" href="...">

Плагин читает индекс с диска при каждой компиляции MDX — поэтому перед dev нужен свежий docs:wiki-links.

remark/lazyMdxDemoImports.js — lazy demo и AST​

Автор пишет обычный import.


import ExternalPlayEmbed from '@site/src/components/ExternalPlayEmbed';

На этапе сборки remark обходит AST (узлы mdxjsEsm) и переписывает строку import.


import __itLazyExternalEmbed from '@site/src/components/shared/lazyExternalEmbed';

const ExternalPlayEmbed = __itLazyExternalEmbed(
  () => import('@site/src/components/ExternalPlayEmbed'),
  { kind: 'play' }
);

Для остальных @site/src/components/* (кроме shared/).


import __itLazyDemoInView from '@site/src/components/shared/lazyDemoInView';

const Foo = __itLazyDemoInView(() => import('@site/src/components/Foo'));
Обёртка из sharedКогда
lazyExternalEmbedExternalPlayEmbed, ExternalCodeEmbed — iframe, отдельный chunk
lazyDemoInViewОстальные компоненты — chunk при попадании в viewport (IntersectionObserver)

import в runtime — динамический import() возвращает Promise модуля; webpack выделяет async-chunk.

build-doc-search-index.mjs — поиск​

Создаёт static/doc-search-index.json — компактный JSON-индекс для клиентского движка docSearchEngine.js.

Поле записиИсточник
uURL (маршрут)
ttitle
ddescription, усечённая до ~220 символов
sраздел из _category_.json
aтеги / аудитория из frontmatter

Запуск — npm run docs:search-index (встроен в start/build).

build-doc-redirects.mjs — редирект​

Сравнивает канонические slug и историю путей (имена папок, кириллица, /docs/ префикс) → docLegacyRedirects.json. Ручные карты в docusaurus.config.js (slugRedirects) дополняют автоматические.

Запуск — npm run docs:redirects.

enhancement — DOM-обогащение статей​

Отдельно от remark — клиентские модули в src/theme/DocItem/Layout/.

МодульРоль
articleMetaEnhancement.tsarticle tags, кликабельные badge
articleSectionEnhancement.tsОбёртка секций .doc-section вокруг h2

Enhancement — пост-обработка уже отрисованного HTML (клиент), без изменения markdown в репозитории.

Другие скрипты docs:*​

npm scriptНазначение
docs:collection-titlesЗаголовки для подборок
docs:tocdocs/toc.md, общее содержание
docs:demo-registryРеестр демо в info/
docs:collection-crosslinksПерекрёстные ссылки в подборках
docs:context-crosslinksКонтекст ↔ энциклопедия
docs:fix-mdx-importsimport после frontmatter
docs:fix-frontmatter-blankПустая строка после ---
docs:check-article-structureВалидация структуры статей
docs:normalize-tagsНормализация тегов
docs:tech-icon-pathsSVG paths из simple-icons
docs:descriptions / docs:refine-descriptionsМассовая правка description

Массовые правки тысяч файлов — через скрипты docs:* из терминала.

Frontmatter и сборка MDX​

Правила репозитория (docs-markdown-frontmatter.mdc).

  • Пустая строка после закрывающего ---
  • title/description со спецсимволами — в кавычках
  • import в MDX — после frontmatter с пустой строкой

Нарушение ломает парсинг MDX при docusaurus build. Валидация — docs:check-article-structure, починка — docs:fix-*.

Поток данных при сборке​

Клиент и сервер — скрипты и remark работают на сервере сборки (Node); поиск и enhancement — в клиенте (браузер после загрузки бандла).

Добавление нового источника данных​

  1. Файл в src/data/ (JSON или .js с ESM export).
  2. import в компонент — import x from '@site/src/data/x.json' (корень резолвится через @site).
  3. Большой файл только на одной странице — dynamic import().
  4. Данные выводятся из docs/ — новый scripts/my-index.mjs + docs:my-index в package.json.

Глоссарий​

Данные​

Структурированная информация (JSON, JS-константы), дополняющая markdown-контент.

Скрипт​

Node-программа в scripts/*.mjs, запускаемая через npm run docs:*.

Контент​

Тексты и MDX в docs/ — статьи энциклопедии, лаборатории, about.

JSON​

Формат обмена данными; статья JSON.

Индекс​

Каталог для быстрого поиска — wiki terms, doc-search, redirects.

JSON-индекс​

Файл JSON со списком записей для поиска или wiki.

JS-каталог​

JS-модуль с экспортируемым массивом или объектом (sidebarCollections.js).

Маршрут​

URL страницы (/encyclopedia/...); doc id в подборках — путь без docs/.

remark-плагин​

Обработчик markdown AST при компиляции MDX.

Node​

Среда выполнения скриптов сборки. Node.js.

Артефакт​

Файл, созданный скриптом (wikiLinkIndex.json, doc-search-index.json).

Сборка​

npm run build — скрипты + docusaurus build → build/.

start​

npm start — docs:* (без collection-titles) + dev-сервер.

build​

npm run build — полный пайплайн включая collection-titles.

Типы данных​

Категории значений в JSON/JS (строка, объект, массив). Типы.

gitignore​

Правила Git — какие артефакты не коммитить (wikiLinkIndex.json).

Git​

Система версий репозитория. Основы Git.

Локальность​

Генерация на машине разработчика; индекс wiki/redirects не обязан быть в remote.

dev-режим​

docusaurus start с hot reload и предварительными docs:*.

wiki-поиск​

Разрешение [[термин]] по wikiLinkIndex.json в remark.

Редирект​

Перенаправление старого URL на канонический.

Массив​

JSON/JS структура [a, b, c] — списки doc id в подборках.

Тематический маршрут​

Подборка статей с label и emoji (SIDEBAR_COLLECTIONS).

enhancement​

Клиентское DOM-обогащение после рендера статьи.

Подборка​

Кураторский список статей по теме (Старт в IT, DevOps…).

homepage​

Главная / — потребляет подборки и секции.

SVG​

Векторные иконки в techIconPaths.js.

Префикс пути статьи​

Начало пути doc id (encyclopedia/5-languages/5-02-python/) → tech id.

tech id​

Ключ технологии в реестре (python, docker).

Список​

Упорядоченная последовательность id или заголовков.

Обогащение​

Добавление ссылок/метаданных — term links, crosslink-скрипты, enhancement.

kind​

Тип wiki-записи — glossary, encyclopedia, explicit, external.

Заголовок​

title в frontmatter или ## в глоссарии — ключ wiki-индекса.

Регэксп​

Регулярное выражение — поиск [[...]] в wikiLink и import в lazyMdx.

Регистр​

Верхний/нижний регистр символов; нормализация ключей wiki.

Регистронезависимость​

[[Python]] и [[python]] находят один термин (toLocaleLowerCase('ru')).

locale​

Локаль 'ru' для корректного lowerCase кириллицы.

Явная ссылка​

[[/path|подпись]] или encyclopedia/... без поиска в индексе.

Корень​

Корень репозитория; @site → src/.

Путь​

Файловый путь в docs/ или URL slug.

Внешний источник​

Данные вне docs/ — simple-icons, play/code сервисы.

Внешняя ссылка​

[[https://...]] — HTTP URL.

HTTP​

Протокол загрузки статики и поискового индекса.

dev/build​

Два режима npm — разработка vs продакшен-сборка.

import​

Подключение модуля; статический в MDX, динамический import() в lazy-обёртках. Модули JS.

AST​

Abstract Syntax Tree — дерево разбора markdown/MDX для remark.

shared​

src/components/shared/ — lazyDemo, lazyDemoInView, lazyExternalEmbed.

lazy demo​

Отложенная загрузка демо-компонентов через remark + import().

chunk​

Отдельный JS-файл бандла, подгружаемый async.

viewport​

Видимая область окна; IntersectionObserver в lazyDemoInView.

Обход​

Рекурсивный проход по папке docs/ в скриптах.

Парсинг​

Разбор файла — gray-matter, remark, регэксп wiki.

description​

Поле frontmatter; попадает в поисковый индекс (усечённое).

Клиентский движок​

docSearchEngine.js — поиск по JSON в браузере.

Клиент​

Браузер пользователя — поиск, enhancement, React.

Сервер​

Node при сборке; статический хостинг для prod HTML/JSON.

История путей​

Старые slug и имена папок для редиректов.

Валидация​

Проверка структуры статей (docs:check-article-structure).

Строка​

Тип данных; также строка исходника MDX/import в AST.

Массовые правки​

Пакетное изменение тысяч md/mdx через docs:fix-*, docs:normalize-tags.

frontmatter​

YAML в начале .md/.mdx — title, description, slug, tags.

Поток данных​

Цепочка docs → scripts → JSON → remark/webpack → клиент.

Секция​

Логический блок статьи под h2 (enhancement .doc-section).

Подборка​

См. тематический маршрут.

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

Автоматическое создание JSON из обхода docs/.

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

Полезные статьи энциклопедии​

Последнее обновление
Содержание