Getting Started #

This guide creates a small but complete KawaPress site from an empty directory. By the end, you will have Markdown pages, a default documentation interface, a local development server, and static files ready to deploy.

Prerequisites #

You need:

• Node.js 22.12 or later;
• npm, pnpm, or Yarn;
• an editor with Markdown support.

Create a Project #

Create a directory and initialize its package.json:

mkdir my-kawapress-site
cd my-kawapress-site
npm init -y

mkdir my-kawapress-site
cd my-kawapress-site
pnpm init

mkdir my-kawapress-site
cd my-kawapress-site
yarn init -y

KawaPress treats the current working directory as the site root. Site configuration, Markdown pages, and build output are all resolved from this directory.

Install KawaPress #

A site using the built-in nagi (凪) preset only needs KawaPress:

npm install --save-dev kawapress

pnpm add --save-dev kawapress

yarn add --dev kawapress

KawaPress is only required while developing and building the site. The deployed output does not require a Node.js server.

Add Project Scripts #

Add these commands to the scripts field in package.json:

{
  "scripts": {
    "docs:dev": "kawapress dev",
    "docs:build": "kawapress build",
    "docs:preview": "kawapress preview"
  }
}

• docs:dev starts the development server.
• docs:build generates the static site.
• docs:preview serves the production build locally.

Configure the Site #

Create kawapress.config.ts in the project root:

import { nagi } from 'kawapress/nagi'

export default nagi({
  title: 'My Docs',
})

The nagi() preset installs the default documentation interface and its plugins. Its styles are included automatically, so the site does not need a separate theme CSS import.

Use UnoCSS Utilities #

nagi enables UnoCSS with presetWind4, presetIcons, and presetWebFonts. Wind4 utilities work directly in Markdown HTML:

<div class="rounded-xl bg-indigo-500/8 px-4 py-3 text-sm">
  UnoCSS generates this card's spacing, radius, and translucent background.
</div>

The Wind4 global reset is disabled, so it does not overwrite nagi or other plugin foundations. The Icons and Web Fonts presets are ready, but they load assets only after you configure a specific icon collection or font.

Add Your First Pages #

Create index.md in the project root:

---
layout: home
title: My Docs
---

# My Docs

Welcome to my first KawaPress site.

[Start reading](/guide/hello)

Then create guide/hello.md:

# Hello, KawaPress!

This is my first documentation page.

The project should now contain:

my-kawapress-site/
├─ guide/
│  └─ hello.md
├─ index.md
├─ kawapress.config.ts
└─ package.json

Markdown file paths become public routes:

• index.md maps to /.
• guide/hello.md maps to /guide/hello.

The home page explicitly selects layout: home. Other Markdown pages use the doc layout by default, which includes the Sidebar and page outline.

Start the Development Server #

Run:

npm run docs:dev

pnpm docs:dev

yarn docs:dev

The site is now available at http://localhost:5173. Open it in a browser and follow the link from the home page to the guide.

Markdown changes are applied through HMR. Initial requests still run through real server-side rendering, so development and production builds share the same SSR semantics.

Build and Preview #

Generate the static site:

npm run docs:build

pnpm docs:build

yarn docs:build

KawaPress writes the deployable output to dist. Preview that output locally with:

npm run docs:preview

pnpm docs:preview

yarn docs:preview

The preview server runs at http://localhost:4173 by default. After checking the result, deploy the dist directory to any static hosting service.

You Are Ready #

You now have a complete KawaPress site that:

• uses Markdown for pages;
• uses nagi for its documentation interface;
• provides HMR and real SSR during development;
• builds static files that do not require a Node.js server.

You can keep adding Markdown pages or move on to routing, Markdown extensions, multilingual sites, plugins, and themes. Each of those features builds on the same project structure.