KatX DocsKit

Reusable Next.js documentation and API Explorer kit for KatX projects. Ships runtime components + a CLI to scaffold a docs app into any repo.

Quick Start

npx @katx-vn/katx-docskit init --target website --name "My Project"
cd website
npm install
npm run docs:dev

What You Get

• Sidebar with docs topics + API endpoints
• OpenAPI-driven API reference pages
• Interactive API Explorer with cURL generation
• Markdown/MDX guide pages with syntax highlighting and Mermaid diagrams
• Changelog page
• Full-text sidebar search
• Tailwind v4 theme with shadcn-style tokens

Project Structure

After scaffolding, your docs app looks like:

website/
  katx-docs.config.ts   # Main configuration
  public/openapi.json   # Your OpenAPI spec
  src/app/              # Next.js pages (pre-wired)
  ../docs/              # Markdown docs (sibling directory)
    index.md            # Home page content
    getting-started.md  # Guide pages

Configuration

Edit katx-docs.config.ts:

import { defineKatxDocsConfig } from "@katx-vn/katx-docskit";

export default defineKatxDocsConfig({
  productName: "My API",
  description: "API documentation.",
  docsDir: "../docs",
  openapiPath: "public/openapi.json",
  environments: [
    { label: "Local", url: "http://localhost:8000" },
    { label: "Production", url: "https://api.example.com" },
  ],
  // Optional: WebSocket endpoint
  websocket: {
    path: "/ws/stream/{session_id}",
    summary: "Streaming conversation",
    parameters: [
      { name: "session_id", in: "path", required: true, schema: { type: "string" } },
    ],
  },
});

Config Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | productName | string | required | Product name in header and metadata | | description | string | "API and engineering documentation." | Meta description | | logo | string | "/images/logo.svg" | Logo image path | | favicon | string | "/images/favicon.svg" | Favicon path | | docsDir | string | "../docs" | Path to markdown docs directory | | openapiPath | string | "public/openapi.json" | Path to OpenAPI spec | | environments | array | Local only | API environments for Explorer | | nav | array | Docs, Explorer, Changelog | Top navigation items | | feedbackEmail | string | - | Shows feedback link in sidebar | | websocket | object | - | Opt-in WebSocket endpoint in API docs |

CLI

katx-docskit init [options]

Options:
  --target <dir>   Target directory (default: "website")
  --name <name>    Project name for config and package.json
  --force          Overwrite if target exists
  --version, -v    Show version
  --help, -h       Show help

Writing Docs

Place .md or .mdx files in your docsDir (default: ../docs/):

---
sidebar_label: Getting Started
sidebar_position: 2
---

# Getting Started

Your content here. Supports **GFM**, code blocks, and Mermaid diagrams.

docs/index.md is required and serves as the home page content.

Components

Import components directly for custom pages:

import { AppShell, MarkdownContent, ApiExplorer } from "@katx-vn/katx-docskit";
import "@katx-vn/katx-docskit/styles.css";

Requirements

• Next.js >= 16
• React >= 19
• Tailwind CSS v4

License

MIT