設定リファレンス

makit.config.ts はサイト全体に作用する設定です。すべて任意ですが、title だけは必須です。値を省略した場合は既定値が使われます。

import { defineConfig } from "@natsuneko-laboratory/makit";

export default defineConfig({
  title: "My Documentation",
  description: "プロジェクトのドキュメント",
  lang: "ja-JP",
  siteUrl: "https://docs.example.com",
  sourceDir: "docs",
  publicDir: "public",
  outDir: "dist",
  basePath: "/manual",
});

基本パス

表示、テーマ、スタイル

export default defineConfig({
  title: "My Documentation",
  header: {
    logo: "/logo.svg",
    logoDark: "/logo-dark.svg",
    title: "My Docs",
    links: [{ label: "GitHub", href: "https://github.com/example/docs", external: true }],
  },
  footer: {
    copyright: "© 2026 Example",
    links: [{ label: "Status", href: "https://status.example.com", external: true }],
  },
  theme: {
    colorScheme: "system",
    accentColor: "violet",
    radius: "medium",
    breadcrumbs: { enabled: true, showHome: true, showCurrentPage: true },
    codeTheme: { light: "github-light", dark: "github-dark" },
    extends: "@acme/makit-theme-corporate",
    components: { Header: "./theme/header.tsx", PrevNextLinks: false },
    dir: "theme",
  },
  styles: ["styles/custom.css"],
});

コンポーネント名の一覧はテーマのカスタマイズ、テーマの作り方はテーマパッケージリファレンスを参照してください。

Markdown

export default defineConfig({
  title: "My Documentation",
  markdown: {
    gfm: true,
    headingIds: true,
    externalLinks: { target: "_blank", rel: "noopener noreferrer" },
    code: { copyButton: true, lineNumbers: false },
    shiki: {
      themes: { light: "github-light", dark: "github-dark" },
      languages: ["ts", "tsx", "bash"],
      unknownLanguage: "warning",
    },
    tableOfContents: { minDepth: 2, maxDepth: 3 },
  },
});

shiki.languages の各要素には、バンドル済み言語名・生の文法オブジェクト・それを返すローダーのいずれかを指定できます（Shiki の langs オプションが受け付けるものすべて）。

shiki: {
  languages: [
    "ts",
    async () => (await import("./my-lang.tmLanguage.json", { with: { type: "json" } })).default,
  ],
},

フェンスコードブロックでは、その文法の name を言語名として指定します（例: ```my-lang）。

構文と表示の対応はMarkdown 構文を参照してください。

多言語

export default defineConfig({
  title: "My Documentation",
  sourceDir: "docs",
  i18n: {
    defaultLocale: "en-US",
    locales: [
      { locale: "en-US", label: "English" },
      { locale: "ja-JP", label: "日本語", sourceDir: "docs/ja-jp" },
    ],
    fallback: { enabled: true, behavior: "render", showNotice: true },
    collectionFallback: { behavior: "render" },
    root: { behavior: "detect" },
    localeSwitcher: { missingPage: "fallback" },
    messages: { "ja-JP": { home: "ホーム", fallbackNotice: "翻訳を表示できません。" } },
  },
});

defaultLocale と locales は必須です。sourceDir を省略した locale は <sourceDir>/<小文字の locale>（例: docs/ja-jp）を読みます。URL でも locale は小文字になります。

root.behavior は、locale を含まない URL にも適用されます。ページが /en-us/getting-started と /ja-jp/getting-started にある場合、/getting-started は / と同じ振り分けページになります。detect は最後に閲覧した locale、次いでブラウザ言語で判定し、default は root.locale（省略時は defaultLocale）へ、select は選択画面を表示します。そのページを持たない locale は候補から外れ、先頭が locale 接頭辞の URL は従来どおり 404 です。振り分けページ自体はサイトマップと検索インデックスに含まれません。

コンテンツとナビゲーション

export default defineConfig({
  title: "Portal",
  collections: { mode: "discover" },
  home: { layout: "portal", featuredCollections: ["api"] },
  navigation: {
    pagination: { enabled: true, crossSection: false },
    auto: { numericPrefixes: true, routeGroups: "url", unorderedPosition: "last" },
    global: [{ items: [{ title: "API", collection: "api" }] }],
  },
});

ページ、カテゴリ、Collection、手動ナビゲーションの詳細はメタデータ APIを参照してください。

SEO と生成物

本番限定の分析ツール

本番限定の分析ツールに、すべての analytics 設定とプロバイダーごとの導入方法をまとめています。

Changelog

changelog は、GitHub Releases から本文を生成するページ（changelog を持つページ）の既定値です。取得結果は .makit/cache/changelog/ に cacheTtl 秒キャッシュされ、同じリポジトリを指すページとロケールで共有されます。取得に失敗した場合はキャッシュへフォールバックし、changelog-fetch-failed 警告を出してビルドは継続します。すべてのオプションは Changelog ページを参照してください。

ビルド、開発、検証

Markdown の先頭に置く front matter は、title、description、order のようなページ単位のフラットな値を .meta.ts の代わりに指定できます。ネストした値やオブジェクトの配列は対象外で、同じページの .meta.ts と non-empty の front matter は併用できません。例と使い分けはコンテンツの整理を参照してください。

デプロイ、リダイレクト、ヘッダー

export default defineConfig({
  title: "My Documentation",
  deployment: {
    configFile: { mode: "generated" },
    redirects: true,
    headers: true,
    cleanUrls: true,
    customDomain: "docs.example.com",
  },
  redirects: [{ from: "/old/", to: "/new/", status: 308 }],
  headers: [
    { path: "/assets/*", headers: { "Cache-Control": "public, max-age=31536000, immutable" } },
  ],
});