Configuration reference

makit.config.ts controls the whole site. Only title is required; omitted options use the defaults shown below.

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

export default defineConfig({
  title: "My Documentation",
  description: "Documentation for my project.",
  lang: "en-US",
  siteUrl: "https://docs.example.com",
  sourceDir: "docs",
  publicDir: "public",
  outDir: "dist",
  basePath: "/manual",
});

Core paths

Display and theme

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",
},
header: { logo: "/logo.svg", logoDark: "/logo-dark.svg", title: "My Docs", links: [] },
footer: { copyright: "© 2026 Example", links: [] },
styles: ["styles/custom.css"],

header.links and footer.links use { label, href, external? }. colorScheme is light, dark, or system (default); radius is none, small, medium (default), or large. Breadcrumb fields default to true, and codeTheme defaults to GitHub light/dark themes.

extends, components, and dir replace the built-in components:

See the theming guide for the component list and the theme package reference for building a theme.

Markdown

markdown: {
  gfm: true,
  headingIds: true,
  allowDangerousHtml: false,
  externalLinks: { target: "_blank", rel: "noopener noreferrer" },
  code: { copyButton: true, lineNumbers: false },
  shiki: { themes: { light: "github-light", dark: "github-dark" }, languages: ["ts"], unknownLanguage: "warning" },
  tableOfContents: { minDepth: 2, maxDepth: 3 },
},

Each entry in shiki.languages can be a bundled language name, a raw grammar object, or a loader returning one — anything Shiki's langs option accepts:

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

A fenced block then opts in with its grammar's name, e.g. ```my-lang.

See Markdown syntax for source and rendering examples.

Localization and navigation

i18n requires defaultLocale and locales. A locale has locale, plus optional label, lang, dir, and sourceDir; an omitted source directory is <sourceDir>/<lowercase locale>.

i18n: {
  defaultLocale: "en-US",
  locales: [{ locale: "en-US", label: "English" }, { locale: "ja-JP", label: "日本語" }],
  fallback: { enabled: true, behavior: "render", showNotice: true },
  collectionFallback: { behavior: "render" },
  root: { behavior: "detect" },
  localeSwitcher: { missingPage: "fallback" },
  messages: { "ja-JP": { home: "ホーム" } },
},

Fallback behavior is render, redirect, or not-found; a missing collection can also be hidden. Root behavior is default, detect, or select; a missing-page locale switcher may use fallback, locale-root, or disabled.

root.behavior also governs paths that carry no locale at all. A link to /getting-started on a site whose pages live at /en-us/getting-started and /ja-jp/getting-started is answered with the same language gateway / uses: detect sends the visitor to the locale they last read in, or to the closest match for their browser languages; default goes to root.locale (or defaultLocale); select offers the choice. Locales that do not have the page are left out, a path already starting with a locale prefix is still a 404, and the gateway pages themselves are excluded from the sitemap and site search.

collections accepts explicit collection metadata or { mode: "discover" }. home chooses a page or portal layout. navigation controls automatic/manual navigation, global links, fallback pages, pagination, numeric filename prefixes, and route groups. navigation.auto.numericPrefixes defaults to true, and unprefixed items default to last. A directory wrapped in parentheses, such as (marketing), is never included in the URL; navigation.auto.routeGroups controls how it affects the sidebar — "url" (default) keeps it as its own section, "flatten" removes that section and promotes its pages into the parent level, and false disables route groups entirely. See Content structure for an example.

SEO, build, and validation

Production analytics

See Production analytics for all analytics options and provider-specific setup.

changelog only matters for pages that set a changelog of their own. Release lists are cached under .makit/cache/changelog/ for cacheTtl seconds (3600 by default) and shared across pages and locales; a failed fetch falls back to that cache and reports changelog-fetch-failed rather than stopping the build. See Changelog pages for every option.

By default, lightweight YAML front matter may replace .meta.ts for flat page values such as title, description, or order. It does not support nested values or arrays of objects, and it cannot be combined with non-empty front matter and a .meta.ts file for the same page. See Content structure for an example and selection guidance.

Deployment

deployment configures an Adapter, config-file ownership (generated, merge, or manual), redirects, headers, clean URLs, custom domains, generated CI, and adapter previews. Site-level redirects entries use { from, to, status } with 301, 302, 307, or 308; headers entries use { path, headers }. See the Adapter reference for provider-specific options.