Install Kanari Docs

This guide explains how to run kanari-docs_v2 for Markdown and MDX documentation with search, dark mode, and multiple content spaces.

Prerequisites

Install these tools before you begin:

• Git
• Node.js LTS
• Bun for package installation and the development server

Download the Project

Clone the repository and enter the Docs directory:

git clone https://github.com/kanari-network/kanari-sdk.git
cd kanari-sdk/kanari-docs_v2

Install Dependencies

bun install

Start the Development Server

bun run dev

Then open http://localhost:3000 in your browser.

Write a New Article

The main documentation lives in content/docs, and this installation guide lives in content/installation.

Create an .mdx file with frontmatter:

---
title: Article title
description: A short description
updated: 2026-06-01
---

# Article title

Start writing your content here.

The page displays its last updated date automatically from the latest Git commit for the .mdx file. Add the optional updated field when you want to publish a specific date.

Add a Documentation Space

Create a folder with any name, such as content/handbook, and add meta.json:

{
  "space": {
    "description": "Additional guides",
    "href": "/handbook",
    "icon": "file",
    "title": "Kanari Handbook"
  },
  "pages": ["index"]
}

Then add content/handbook/index.mdx. The framework creates the /handbook route and adds the title to the dropdown automatically without TypeScript changes.

To create another entry that reuses existing content, add source:

{
  "space": {
    "description": "Additional guides",
    "href": "/handbook",
    "icon": "file",
    "source": "docs",
    "title": "Kanari Handbook"
  }
}

Build for Production

Use Node.js for the production build:

npm run build
npm run start

Configure the Sidebar

Use pages in meta.json to control the sidebar without changing TypeScript:

{
  "pages": [
    "index",
    "---Guides---",
    "...",
    "!draft",
    "external:[GitHub](https://github.com/kanari-network/kanari-sdk)"
  ]
}

• ... includes remaining pages and folders automatically.
• !draft excludes a page or folder from the remaining items.
• ---Guides--- adds a separator.
• [Label](url) adds a link.
• external:[Label](url) opens an external link in a new tab.

Folder-level meta.json also supports collapsible sidebar groups:

{
  "title": "Guides",
  "collapsible": true,
  "defaultOpen": true,
  "pages": ["...", "!draft"]
}

Customize the Theme

Edit content/theme.json to customize the palette for the entire website without changing CSS or TypeScript:

{
  "light": {
    "lime": "#ff4d4f",
    "purple": "#ffc9c9",
    "purpleStrong": "#c62828",
    "cream": "#f7f4eb",
    "deepGreen": "#111b18",
    "warmWhite": "#f7f4eb",
    "line": "rgba(17, 27, 24, 0.18)",
    "ink": "#111b18",
    "muted": "rgba(17, 27, 24, 0.66)",
    "onAccent": "#111b18",
    "paper": "#fffdf7",
    "sectionSurface": "#ffc9c9"
  },
  "dark": {
    "lime": "#ff6b6d",
    "purple": "#5c2526",
    "purpleStrong": "#ff9a9b",
    "cream": "#170d0d",
    "deepGreen": "#111b18",
    "warmWhite": "#f7f4eb",
    "line": "rgba(255, 255, 255, 0.16)",
    "ink": "#fff4f4",
    "muted": "rgba(255, 244, 244, 0.68)",
    "onAccent": "#111b18",
    "paper": "#251515",
    "sectionSurface": "#202b27"
  }
}

• light controls light mode.
• dark controls dark mode.
• lime controls buttons, active navigation, and highlights.
• purple controls purple-style surfaces.
• purpleStrong controls strong accent text.
• cream controls the page background.
• deepGreen controls dark buttons and cards.
• warmWhite controls text displayed on dark surfaces.
• line controls lines and card outlines.
• paper controls cards and overlays.
• ink controls primary text.
• muted controls secondary text.
• onAccent controls text displayed on accent-colored surfaces.
• sectionSurface controls large contrasting sections.

Legacy aliases still work: accent maps to lime, accentStrong to purpleStrong, background to cream, border to line, secondary to purple, invertedSurface to deepGreen, and invertedText to warmWhite.

Every field is optional. An empty {} file uses the built-in Kanari preset from content/theme-default.json, and any value in content/theme.json overrides only that token.

Transparent card backgrounds, hover states, overlays, glows, code surfaces, and mobile menus are derived from these tokens automatically. You do not need to edit CSS to keep the whole interface in the same palette.

To override colors for a single documentation space, add an optional theme object inside space in that folder's meta.json.

Next Steps

• Add .mdx articles to your content folder.
• Control sidebar ordering with meta.json.
• Use the search palette to find headings and text blocks.
• Review light mode and dark mode before deployment.