Workspace Docs

Appearance

Site Integration

Унифицированный VitePress-сайт ​

workspace-docs/site — единый VitePress-сайт, собирающий документацию из нескольких doc-space: например builder, portal и autodoc.

Интеграция не читает исходники проектов напрямую. Сначала каждый проект экспортирует свой doc-space, затем общий prepare собирает готовые exports в один сайт и резолвит cross-space Doc Links.

Экспорт проекта ​

Каждый проект экспортирует документацию независимо через docs:export. На этом шаге autodoc берёт JSDoc-фрагменты, page templates и sidebar проекта, а результат кладёт в exportDir.

mermaid
flowchart TD
  S1["source.ts — @doc_id page.intro"]
  S2["source.vue — @doc_id page.widget"]
  S3["source.ts — @doc_id page.api"]
  P["page.ts — defineDocPage"]
  SB["sidebar.ts — defineDocSidebar"]
  S1 & S2 & S3 -->|фрагменты| E["autodoc export"]
  P -->|шаблон страницы| E
  SB -->|навигация| E
  E --> O[".autodoc/export
markdown + manifest.json"]
  1. Фрагменты — JSDoc Annotations извлекаются из JSDoc-блоков с @doc_id.
  2. Страницы — Page Definitions объявляются в page.ts и компонуют фрагменты.
  3. Экспорт — cli.export генерирует markdown, manifest и sidebar в exportDir.

Сборка единого сайта ​

site/scripts/prepare.ts собирает exports всех проектов в один VitePress-сайт.

mermaid
flowchart TD
  B["builder
.autodoc/export"]
  PRT["portal
.autodoc/export"]
  A["autodoc
.autodoc/export"]
  B & PRT & A --> PREP["site/scripts/prepare.ts"]
  PREP -->|markdown + resolved links| D["site/docs/{space}"]
  PREP -->|manifest'ы всех space| C["site/docs/.generated/catalog.json"]
  D & C --> VP["VitePress config"]
  VP --> S["Статический сайт"]
  1. Подготовка — находит локальный проект или клонирует его, затем вызывает docs:export.
  2. Каталог — собирает manifest.json каждого пространства и использует их для cross-space ссылок.
  3. Сайт — копирует markdown в site/docs/{space}/, генерирует общий catalog и отдаёт структуру VitePress.

DocSpaceManifest ​

DocSpaceManifest — индекс экспортированного doc-space. Он нужен не для чтения человеком, а для сборки общего сайта: site/scripts/prepare.ts читает manifest каждого проекта, строит общий catalog, резолвит cross-space ссылки и собирает sidebar.

В manifest попадают страницы, фрагменты, doc-ссылки и готовое к рендеру дерево sidebar.

Manifest ​

ExportedPageManifestEntry — сгенерированный индекс страницы, который используют VitePress, разрешение ссылок, source buttons и AI context.

Generated doc ids ​

docs-ids.ts содержит сгенерированные constants DocPages и DocFragments. Их можно импортировать в page templates и sidebars, чтобы получать autocomplete и TypeScript errors без ручного ведения registries.

ts
export const DocPages = { DigitalInput: "digital-input" } as const;
export const DocFragments = { DigitalInputSummary: "digital-input.summary" } as const;

Добавление нового пространства ​

Чтобы добавить новый doc-space на сайт:

  1. В проекте: создать docs.config.ts с defineDocSpace(), добавить скрипт docs:export
  2. В site/scripts/prepare.ts: добавить запись в массив spaces
  3. VitePress config автоматически подхватит новое пространство из catalog.json

Пример записи в prepare.ts:

ts
{
  space: "autodoc",
  title: "Autodoc",
  repoPath: path.join(workspaceRoot, "workspace-docs"),
  exportDir: ".autodoc/export/autodoc",
  command: "yarn",
  args: ["docs:export"],
}

Mentioned In ​