Core concepts

Makit is centered on Markdown files, with TypeScript metadata added only where it is useful.

Markdown is for content

Write headings, paragraphs, lists, and code blocks—the content readers see—in Markdown. To add a page, simply create an .md file.

# Configuration

Configure Makit in `makit.config.ts`.

TypeScript is for structure

To explicitly set a page title or ID, place a {page-name}.meta.ts file next to it.

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

export default definePageMetadata({
  id: "configuration",
  title: "Configuration",
});

TypeScript gives you editor completion and type checking, without maintaining a separate YAML structure file.

Code-block annotations

Enable markdown.code.lineNumbers in makit.config.ts to show line numbers for every code block. To enable them for one block, add lineNumbers after its filename.

```typescript src/config.ts lineNumbers
export const enabled = true;
```

Add an annotation at the end of a line to highlight it or render it as a Git-style diff. The annotation itself is not shown.

```typescript
const changed = true; // [!code highlight]
const added = true; // [!code ++]
const removed = false; // [!code --]
```

GitHub-style alerts

Use GitHub's alert syntax to call attention to important content. Makit supports NOTE, TIP, IMPORTANT, WARNING, and CAUTION; each has a distinct, accessible visual treatment.

> [!IMPORTANT]
> Read the [security guide](/security-guides) before installing or using this add-on.

Site hierarchy

Think of a site as the following hierarchy:

Site
└── Collection
    └── Section
        └── Group
            └── Page

You do not need every level. A small site can work with pages directly under the site root.

URLs and sidebars are independent

Filename prefixes such as 01- and 02- primarily control display order. They are not included in URLs.

docs/02-guides/01-installation.md

The file above becomes:

/guides/installation/

You can reorganize the display order without changing URLs or page IDs.

A directory wrapped in parentheses, such as (marketing), goes further and is left out of the URL entirely, while still forming its own section in the sidebar by default:

docs/(marketing)/about.md

/about/

See Content structure for how to also drop the sidebar grouping.

The theme renders, Makit resolves

Makit turns your content into page data — titles, HTML, navigation trees, breadcrumbs — and hands it to a set of React components that render it. That set is Makit's built-in theme.

Each component in it is a named slot, so a project can swap out just the header, or the whole page shell, without touching content or configuration structure:

theme/header.tsx     → replaces the Header component
theme/docs-page.tsx  → replaces the whole page shell

Resolving content and rendering it stay separate: routing, navigation, and validation behave the same no matter which components draw the page, and the output stays fully static. See Theming.