Getting Started

Installation

Install Clearify as a dev dependency:

npm install @marlinjai/clearify --save-dev

Scaffold your project

The fastest way to get started:

npx clearify init

This creates:

• docs/public/index.md — your home page
• docs/public/getting-started.md — a starter guide
• docs/internal/index.md — internal docs section (use --no-internal to skip)
• clearify.config.ts — project configuration with sections
• CHANGELOG.md — a Keep a Changelog formatted changelog

Start the dev server

npx clearify dev

Open http://localhost:4747 to see your docs. The server hot-reloads on every file change.

Custom port

Override the port with --port or in your config:

npx clearify dev --port 9999

Adding pages

Create .md or .mdx files in the docs/public/ folder. Each file becomes a page. Subfolders become navigation groups.

docs/
├── public/                 # User-facing docs
│   ├── index.md            # Home page (/)
│   ├── getting-started.md  # /getting-started
│   └── guides/
│       ├── installation.md # /guides/installation
│       └── configuration.md
└── internal/               # Design docs, roadmaps (draft)
    └── index.md

Frontmatter

Control page metadata with YAML frontmatter:

---
title: My Page Title
description: A brief description
order: 1
---

• title — page title (defaults to filename)
• description — meta description for search
• order — sort position in sidebar (lower = higher)

Configuration

Create a clearify.config.ts in your project root:

import { defineConfig } from '@marlinjai/clearify';

export default defineConfig({
  name: 'My Project',
  sections: [
    { label: 'Docs', docsDir: './docs/public' },
    { label: 'Internal', docsDir: './docs/internal', basePath: '/internal', draft: true },
  ],
  theme: {
    primaryColor: '#3B82F6',
    mode: 'auto',
  },
});

Options

Building for production

npx clearify build

Outputs a static site to docs-dist/ with a sitemap.xml. Deploy anywhere that serves static files.