Workspace Docs

Appearance

Page Definitions

Что такое page.ts ​

Page definition — это файл страницы в docs/pages/**/page.ts. Его content — это то, что увидит пользователь на сайте: там можно писать markdown напрямую или включать фрагменты из @description по doc id через includeDoc().

Authored-страницы ищутся в pagesRoot из doc space config. Autodoc рекурсивно берёт файлы page.ts, page.tsx, page.js и page.mjs, импортирует default export и получает из него DocPageSource.

Контракт страницы ​

DocPageSource — контракт page. Page identity и title живут рядом с page template, а структура sidebar живёт в defineDocSidebar.

ts
export interface DocPageSource {
  id: string;
  title: string;
  output?: string;
  content: DocTemplateValue[];
  sourceRef?: SourceRef;
}

defineDocPage() объявляет page документации. Page identity, title, output path и content живут в самом page-файле.

Из чего собирается content ​

content может смешивать обычный markdown-текст и template-узлы: section(), includeDoc(), linkList() и другие helpers.

Подробно про helpers: Template API.

Как page.ts становится markdown ​

Компоновка страницы превращает page template в markdown: рендерит template-строки, sections, includeDoc-узлы и custom nodes, затем добавляет заголовок страницы и backlinks.

Doc-ссылки внутри страницы участвуют в индексе ссылок и backlinks: как работают backlinks.

Узел includeDoc() резолвится во время рендера страницы: exporter берёт docId из template-node, ищет фрагмент в собранной map и вставляет его markdown-body в текущую страницу.

Исходник этой страницы ​

Эта страница сгенерирована из этого page.ts:

ts
export default defineDocPage({
  id: "page-definitions",
  title: "Page Definitions",
  content: md`
${section(
  "Что такое page.ts",
  md`
Page definition — это файл страницы в \`docs/pages/**/page.ts\`. Его
\`content\` — это то, что увидит пользователь на сайте: там можно писать
markdown напрямую или включать фрагменты из \`@description\` по doc id через
{@link_doc template-api.include-doc|includeDoc()}.

${includeDoc("page-definitions.page-discovery")}
`,
)}

${section(
  "Контракт страницы",
  md`
${includeDoc("page-definitions.doc-page-source")}

<<< @/generated-snippets/types.ts#doc-page-source

${includeDoc("page-definitions.define-doc-page")}
`,
)}

${section(
  "Из чего собирается content",
  md`
\`content\` может смешивать обычный markdown-текст и template-узлы:
\`section()\`, \`includeDoc()\`, \`linkList()\` и другие helpers.

Подробно про helpers: {@link_doc template-api}.
`,
)}

${section(
  "Как page.ts становится markdown",
  md`
${includeDoc("page-definitions.page-composition")}

Doc-ссылки внутри страницы участвуют в индексе ссылок и backlinks:
{@link_doc doc-links.backlinks|как работают backlinks}.

${includeDoc("page-definitions.include-doc-render")}
`,
)}

${section(
  "Исходник этой страницы",
  md`
Эта страница сгенерирована из этого \`page.ts\`:

<<< @/generated-snippets/docs/pages/page-definitions/page.ts#page-definitions-source
`,
)}
`,
});

Mentioned In ​