品質チェック#

Copy as MarkdownView Markdown

コードサンプルが腐ると、ドキュメントも腐ります。これらのオプトインチェックは Markdown 変換中に走るので、壊れたスニペットは読者に届く前にビルドを落とします。

チェックは静的です。変換中にドキュメントのコードは実行しません。docsTests はコードを実行しますが、CI から呼ぶ別の Vitest ハーネスの中だけです。

コードブロック lint#

ネイティブのスキャナはソース位置付きの診断を報告し、ファイルに実際にフェンスがあるときだけ走ります。

import { oxContent } from "@ox-content/vite-plugin";

export default {
  plugins: [
    oxContent({
      codeBlockLint: {
        requireLanguage: true,
        trailingSpaces: true,
        mode: "error",
      },
    }),
  ],
};

ラベルなしフェンスと末尾スペースがあるページでは、変換は次を報告します。

code-block-language at 3:1
  Code block is missing a language identifier.
code-block-trailing-spaces at 8:13
  Code block line has trailing whitespace.

mode: "warn"（既定）では診断をログしてビルドは続きます。mode: "error" では変換が throw し、ビルドは失敗します。

コードブロックの型チェック#

tsgo（ネイティブ TypeScript コンパイラ）で TypeScript フェンスを型チェックします。

oxContent({
  codeBlockTypecheck: {
    languages: ["ts", "tsx"],
    requireMeta: true,
    tsgoCommand: "tsgo",
    mode: "error",
  },
});

既定の requireMeta: true では、著者はフェンスごとにオプトインするので、意図して不完全なスニペットも残せます。

```ts typecheck
const value: string = "ok";
```

requireMeta: false にすると、すべての TypeScript フェンスを検査します。スニペットは一時ディレクトリに書き、tsgo --noEmit でコンパイルします。コンパイラエラーはソースフェンスを指すビルド診断になります。

tsgo は @typescript/native-preview に付きます。

vp install -D @typescript/native-preview

pnpm add -D @typescript/native-preview

bun add -D @typescript/native-preview

npm install -D @typescript/native-preview

yarn add -D @typescript/native-preview

Docs テスト#

実行可能なフェンスを取り出して Vitest で走らせます。Rust の doctest と同じ「ドキュメントがテストされる」流れです。取り出しはネイティブで、文書全体を JavaScript でパースしません。

import { runDocsTests } from "@ox-content/vite-plugin";

await runDocsTests({
  include: ["docs/content/**/*.md"],
  vitestCommand: "vitest",
  vitestArgs: ["run"],
});

フェンスがテストになるのは、meta に test、runnable、vitest、または docs-test があるときです。

```ts docs-test
import { expect } from "vitest";

const result = 1 + 1;
expect(result).toBe(2);
```

各フェンスは生成された Vitest の test(...) で包みます。source: "jsdoc" に切り替えると、Markdown ではなくソースコードの @example フェンスを走らせます。生成 API ドキュメント を動かすのと同じ抽出器です。ハーネスオプション（独自テストを宣言するフェンス向けの executionMode: "module" を含む）は Vitest Docs Tests を見てください。

HTML サニタイザ#

信頼できない、または混在したコンテンツを描画するとき、最終 HTML をサニタイズします。

oxContent({
  sanitize: {
    allowedUrlSchemes: ["http", "https", "mailto"],
  },
});

次の入力があるとき、

<p onclick="alert(1)">
  Hello
  <script>
    alert(2);
  </script>
  <a href="javascript:alert(3)">link</a>
</p>

サニタイザは次を出します。

<p>Hello <a>link</a></p>

script 要素、イベントハンドラ属性、安全でない URL スキームは、ネイティブの 1 パスで除きます。sanitize: true は、メディア要素（video、audio、source、track、picture）を含む、よくあるドキュメント HTML を残す安全な既定を使います。allowedTags、allowedAttributes、allowedUrlSchemes を渡すと、対応する組み込みリストを 置き換え ます。足し算ではありません。

パスはパイプラインのいちばん最後 — 埋め込み の展開のあと — に走るので、許可リストはページが実際に出すものすべてに効きます。

関連#

• コードブロック — これらの検査が守るフェンス向けのハイライト、注釈、取り込み。
• 型ホバー — twoslash フェンスのビルド時型オーバーレイ
• HTML Sanitizer の例