# PACKAGE: @nofinite/markon

Extensible rich text WYSIWYG editor and high-performance Markdown parser and renderer.

You are an expert React developer using @nofinite/markon.
Rules:
1. Import MarkonEditor and MarkonRender from '@nofinite/markon/react'.
2. Use MarkonEditor for WYSIWYG editing with slash commands, code blocks, tables, and bubble menus.
3. Use MarkonRender for secure, high-speed compiled document display.

---

## TypeScript API Reference (Props)

### MarkonRender
- `content (required): any` (Default: none)
  Content to render: TipTap JSONContent, HTML string, or Markdown string.
- `format: enum` (Default: auto)
  Content format. If omitted, format is automatically detected.
- `metadata: any` (Default: none)
  Publication metadata: title, subtitle, cover image, author, date, reading time, tags, category.
- `layout: any` (Default: article)
  Publication layout mode:
- 'article': Blog/article with hero cover, author byline, sticky TOC, and tags.
- 'document': Technical docs with header breadcrumbs, updated timestamp, and side TOC.
- 'newsroom': Editorial press release with bold kicker, headline, and dateline.
- 'minimal': Bare prose container without chrome.
- `showTOC: boolean` (Default: true)
  Whether to show sticky Table of Contents.
- `tocTitle: string` (Default: On this page)
  Custom TOC title label.
- `includeStyles: boolean` (Default: true)
  Whether to include the self-contained publication stylesheet.
- `highlightCode: boolean` (Default: true)
  Whether to perform syntax highlighting on code blocks.
- `renderMath: boolean` (Default: true)
  Whether to pre-render KaTeX math formulas.
- `className: string` (Default: none)
  Custom class name applied to container.
- `onRendered: ((result: RenderResult) => void)` (Default: none)
  Callback fired when rendering finishes with TOC, reading time, and word count.


---



### Document: markon/block-handles/page.mdx

# Block Drag Handles

**Nofinite Markon** features Notion-style gutter drag handles (`⋮⋮`) that allow authors to reorganize, duplicate, and transform blocks of content without touching markdown syntax.

Styled with **NUICSS** tokens and powered by `@floating-ui/dom` boundary tracking, block handles provide a tactile, spatial editing experience.

```ts
// Framework-Agnostic Core
import { MarkonEditor, MarkonDragHandle } from '@nofinite/markon';

// React Adapter
import { MarkonEditor as ReactMarkonEditor } from '@nofinite/markon/react';
```

---

## Key Features

- **Hover Grip Handle:** A 6-dot grip icon (`⋮⋮`) smoothly appears in the left gutter adjacent to the block currently hovered by the user.
- **Drag-and-Drop Reordering:** Dragging the handle lifts the entire block and displays a glowing horizontal indicator line marking the drop target.
- **Contextual Action Menu:** Clicking the handle opens a floating menu with 1-click block manipulation actions.
- **Touch-Screen Friendly:** Expanded hitboxes allow tablet and mobile users to access block actions reliably.

---

## 1. Framework-Agnostic Core Usage

The block drag handle is natively bundled into the vanilla DOM editor core:

```ts
import { MarkonEditor } from '@nofinite/markon';
import '@nofinite/nuicss/styles.css';

const container = document.querySelector('#editor')!;

const editor = new MarkonEditor({
  element: container,
  initialValue: `
    <h2>Architecture Overview</h2>
    <p>Hover near this paragraph to reveal the drag handle in the left margin.</p>
  `,
  placeholder: 'Start writing...'
});
```

---

## 2. React Adapter Usage

In React applications, enable the handle via the `dragHandle` prop:

```tsx
import React, { useState } from 'react';
import { MarkonEditor } from '@nofinite/markon/react';
import '@nofinite/nuicss/styles.css';

export function DocumentEditor() {
  const [content, setContent] = useState(`
    <h2>Architecture Overview</h2>
    <p>Hover near this paragraph to reveal the drag handle in the left margin.</p>
  `);

  return (
    
  );
}
```

---

## Contextual Action Menu

Clicking the handle directly (without dragging) opens a floating context menu with quick block actions:

| Action | Behavior |
| :--- | :--- |
| **Delete** | Removes the selected block from the document |
| **Duplicate** | Clones the block directly underneath |
| **Turn Into Heading 1** | Converts block to a Level 1 Heading |
| **Turn Into Heading 2** | Converts block to a Level 2 Heading |
| **Turn Into Bullet List** | Transforms block into an unordered list item |
| **Turn Into Callout** | Wraps the block inside an Info Callout |
| **Copy Link to Block** | Generates a permanent anchor URL to the block's ID |

---


### Document: markon/callouts-and-details/page.mdx

# Callouts and Collapsible Sections

**Nofinite Markon** provides first-class support for callout advisory boxes and Notion-style collapsible accordions.

Both components are styled using **NUICSS** semantic color tokens and designed to highlight critical instructions, warnings, or deep-dive technical appendices without disrupting reading flow.

```ts
// Framework-Agnostic Core
import { MarkonEditor, renderMarkdown } from '@nofinite/markon';

// React Adapter
import { MarkonEditor as ReactMarkonEditor, MarkonRender } from '@nofinite/markon/react';
```

---

## Callout Advisory Boxes

Callouts wrap content inside an attention-grabbing box with a semantic SVG icon and soft background tint.

### The 4 Semantic Variants

| Variant | Theme Color | Markdown Syntax | Recommended Use Case |
| :--- | :--- | :--- | :--- |
| **`info`** | `var(--color-info)` (Blue) | `:::info ... :::` | Informational notes, tips, contextual background, and helpful hints |
| **`success`** | `var(--color-success)` (Green) | `:::success ... :::` | Best practices, successful validations, and verified architectural steps |
| **`warning`** | `var(--color-warning)` (Amber) | `:::warning ... :::` | Deprecation notices, operational caveats, and non-destructive gotchas |
| **`danger`** | `var(--color-danger)` (Red) | `:::danger ... :::` | Security vulnerabilities, data loss risks, and destructive commands |

---

## 1. Framework-Agnostic Core Usage

### Parsing & Rendering via `renderMarkdown`

In pure Node.js, Astro, or browser TypeScript, compile Markdown callouts and details blocks into semantic HTML:

```ts
import { renderMarkdown } from '@nofinite/markon';
import '@nofinite/nuicss/styles.css';

const markdown = `
# Production Deployment Protocol

:::info
Automated deployments occur every Tuesday at 02:00 UTC during the low-traffic maintenance window.
:::

:::danger
Running DROP TABLE without a verified PITR snapshot will result in permanent data loss.
:::

<details>
  <summary>View Database Migration SQL</summary>
  \`\`\`sql
  ALTER TABLE users ADD COLUMN mfa_enabled BOOLEAN DEFAULT FALSE;
  \`\`\`
</details>
`;

const html = renderMarkdown(markdown);
document.getElementById('content')!.innerHTML = html;
```

---

## 2. React Adapter Usage

In React applications, render interactively in either `<MarkonEditor />` or `<MarkonRender />`:

```tsx
import React, { useState } from 'react';
import { MarkonEditor, MarkonRender } from '@nofinite/markon/react';
import '@nofinite/nuicss/styles.css';

const guideContent = `
# Production Deployment Protocol

:::info
Automated deployments occur every Tuesday at 02:00 UTC during the low-traffic maintenance window.
:::
`;

export function CalloutDemo() {
  const [content, setContent] = useState(guideContent);

  return (
    
  );
}
```

---


### Document: markon/draft-management/page.mdx

# Draft Auto-Save and Recovery

**Nofinite Markon** includes a built-in draft management engine (`MarkonDraftManager`) that guarantees authors never lose work due to unexpected browser crashes, tab closures, or network disconnects.

It features debounced background persistence, live save state indicators, and intelligent draft recovery dialogs.

```ts
// Framework-Agnostic Core
import { MarkonEditor, MarkonDraftManager, type AutoSaveConfig } from '@nofinite/markon';

// React Adapter
import { MarkonEditor as ReactMarkonEditor } from '@nofinite/markon/react';
```

---

## Key Capabilities

- **Debounced Local Persistence:** Automatically persists document revisions to `localStorage` with customizable debounce timing (default 1,000ms).
- **Reactive Save States:** Emits 4 clean status states: `'idle'`, `'saving'`, `'saved'`, and `'error'`.
- **Custom Persistence Hooks:** Connect to backend databases, REST endpoints, or GraphQL mutations via asynchronous `onSave` callbacks.
- **Conflict & Recovery Detection:** Detects whether an unsaved local draft exists and offers a 1-click restore modal.

---

## 1. Framework-Agnostic Core Usage

Configure draft management directly when instantiating `MarkonEditor`:

```ts
import { MarkonEditor } from '@nofinite/markon';
import '@nofinite/nuicss/styles.css';

const container = document.querySelector('#editor')!;

const editor = new MarkonEditor({
  element: container,
  showSaveStatus: true,
  autoSave: {
    key: 'draft_article_101',
    debounceMs: 1200,
    onSave: async (html, json) => {
      console.log('Auto-saving revision to server...');
      await fetch('/api/drafts/101', {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ html, json })
      });
      console.log('Revision saved successfully.');
    }
  }
});
```

---

## 2. React Adapter Usage

In React applications, pass the `autoSave` configuration object as a component prop:

```tsx
import React, { useState } from 'react';
import { MarkonEditor } from '@nofinite/markon/react';
import '@nofinite/nuicss/styles.css';

export function ArticleComposer() {
  const [content, setContent] = useState('<p>Start drafting your article...</p>');
  const [statusMessage, setStatusMessage] = useState('All changes saved');

  return (
    
      </div>

      <MarkonEditor
        content={content}
        onChange={setContent}
        autoSave={{
          key: 'editor_draft_101',
          debounceMs: 1200,
          onSave: async (html, json) => {
            setStatusMessage('Saving...');
            await fetch('/api/draft', { method: 'POST', body: JSON.stringify({ html, json }) });
            setStatusMessage('All changes saved');
          },
        }}
      />
    </div>
  );
}
```

---


### Document: markon/editor/page.mdx

# MarkonEditor

`MarkonEditor` is a full-featured, accessible WYSIWYG authoring canvas featuring 28 toolbar actions, floating bubble menus, slash commands (`/`), gutter drag handles, and KaTeX mathematics.

```ts
// Framework-Agnostic Core
import { MarkonEditor, type MarkonEditorOptions } from '@nofinite/markon';

// React Adapter
import { MarkonEditor as ReactMarkonEditor } from '@nofinite/markon/react';
```

---

## Interactive Preview

<Preview 
  name="editor" 
  vanillaCode={`import { MarkonEditor } from '@nofinite/markon';
import '@nofinite/nuicss/styles.css';

const container = document.getElementById('editor-container');

const editor = new MarkonEditor({
  element: container,
  initialValue: '<h2>Project Proposal</h2><p>Type "/" to insert callouts, code blocks, or tables...</p>',
  showSlashCommands: true,
  showBubbleMenu: true,
  showWordCount: true,
  placeholder: "Type '/' for commands..."
});`}
/>

---

## 1. Framework-Agnostic Core Usage

### Direct DOM Mounting (`new MarkonEditor`)

Mount the authoring canvas directly into any HTML element:

```ts
import { MarkonEditor } from '@nofinite/markon';
import '@nofinite/nuicss/styles.css';

const container = document.querySelector('#editor-root')!;

const editor = new MarkonEditor({
  element: container,
  initialValue: '# Product Roadmap 2026\n\nDetailed milestones...',
  placeholder: "Type '/' for commands...",
  showSlashCommands: true,
  showBubbleMenu: true,
  showWordCount: true,
  showSaveStatus: true,
  autoSave: {
    key: 'draft-roadmap-2026',
    debounceMs: 1000
  },
  onChange: (html, json, text) => {
    console.log('Words:', editor.getCounts().words);
  },
  onUploadFile: async (file) => {
    // Custom S3 / R2 upload logic
    return 'https://cdn.example.com/uploads/photo.jpg';
  }
});

// Programmatic methods:
// const markdown = editor.getMarkdown();
// const html = editor.getHTML();
// const jsonAst = editor.getJSON();
// editor.setMarkdown('# Updated Document');
// editor.focus();
// editor.destroy();
```

---

## 2. React Adapter Usage

In React applications, manage document state declaratively:

```tsx
import React, { useState } from 'react';
import { MarkonEditor } from '@nofinite/markon/react';
import '@nofinite/nuicss/styles.css';

export default function DocumentCanvas() {
  const [content, setContent] = useState('<h2>Sprint Tasks</h2><p>Edit directly...</p>');

  return (
    
  );
}
```

---

## Features & Configuration

### 1. Slash Commands (`/`)
Press `/` on any blank line to open a keyboard-navigable command palette:
- Headings (H1, H2, H3)
- Bulleted & Numbered Lists
- Task Checklists
- Code Blocks with language syntax highlighting
- KaTeX Math Formulas
- Blockquotes & Callout Boxes
- Data Tables with dynamic row/column insertion

### 2. Contextual Bubble Menu
Selecting text automatically reveals a floating bubble menu providing quick access to Bold, Italic, Strikethrough, Code, Color chips, Link insertion, and Typography alignment.

---

## Keyboard Shortcuts

| Shortcut | Action |
| :--- | :--- |
| <kbd>/</kbd> | Open floating slash command palette |
| <kbd>Mod</kbd> + <kbd>B</kbd> | Toggle Bold text |
| <kbd>Mod</kbd> + <kbd>I</kbd> | Toggle Italic text |
| <kbd>Mod</kbd> + <kbd>K</kbd> | Insert or edit link |
| <kbd>Mod</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd> | Format as Heading 1 |
| <kbd>Mod</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd> | Format as Heading 2 |
| <kbd>Mod</kbd> + <kbd>Alt</kbd> + <kbd>C</kbd> | Insert Code Block |
| <kbd>Mod</kbd> + <kbd>Z</kbd> | Undo |
| <kbd>Mod</kbd> + <kbd>Shift</kbd> + <kbd>Z</kbd> | Redo |

---


### Document: markon/examples/page.mdx

# Markon Publication Examples

Below are production-ready, copy-paste implementations of **Nofinite Markon** showcasing the universal publication editor and isomorphic renderer across pure vanilla TypeScript/Node environments, Edge runtimes, and React architectures.

---

## Example 1: Pure Vanilla TypeScript Editorial CMS (Core First)

A complete, zero-framework editorial workspace with live markdown preview, auto-saving drafts to `localStorage`, and real-time word/character telemetry:

```ts
import { MarkonEditor, renderMarkdown, MarkonDraftManager } from '@nofinite/markon';
import '@nofinite/nuicss/styles.css';

// 1. Setup DOM Elements
const editorMount = document.getElementById('editor-mount')!;
const previewMount = document.getElementById('preview-mount')!;
const wordCountEl = document.getElementById('word-count')!;
const saveStatusEl = document.getElementById('save-status')!;

// 2. Draft Persistence Manager
const draftManager = new MarkonDraftManager({
  storageKey: 'editorial_cms_draft_v1',
  debounceMs: 500,
});

const initialContent = draftManager.getDraft() || `
# Architectural Decision Record: Zero-DOM Isomorphic Rendering

## Status
Accepted

## Context
Downstream web applications require ultra-fast content rendering on both server workers and browser clients without duplicating markdown parsing logic.

## Decision
Adopt **Nofinite Markon** to compile CommonMark, GFM tables, and KaTeX mathematics directly to optimized HTML strings.
`;

// 3. Initialize Core Markon Editor
const editor = new MarkonEditor({
  element: editorMount,
  content: initialContent,
  toolbar: true,
  slashCommands: true,
  blockHandles: true,
  onChange: (markdown) => {
    // Auto-save draft
    draftManager.saveDraft(markdown);
    saveStatusEl.textContent = 'Saved at ' + new Date().toLocaleTimeString();

    // Isomorphic Zero-DOM live preview compilation
    const { html, toc, wordCount } = renderMarkdown(markdown, {
      katex: true,
      highlight: true,
      gfm: true,
    });

    previewMount.innerHTML = html;
    wordCountEl.textContent = `${wordCount} words`;
  },
});

// Initial compilation render
const { html: initialHtml, wordCount: initialCount } = renderMarkdown(initialContent);
previewMount.innerHTML = initialHtml;
wordCountEl.textContent = `${initialCount} words`;
```

---

## Example 2: Edge & Node.js Universal Server-Side Rendering (Zero DOM)

Compile complex markdown documents with syntax highlighting and KaTeX mathematics on any Node, Bun, Deno, or Cloudflare Workers runtime with **zero browser DOM dependencies**:

```ts
// server/routes/render.ts
import { renderMarkdown } from '@nofinite/markon';

export async function handleRenderRequest(markdownText: string) {
  const startTime = performance.now();

  // Zero-DOM isomorphic compilation (< 5ms execution time)
  const result = renderMarkdown(markdownText, {
    katex: true,
    highlight: true,
    gfm: true,
  });

  const durationMs = (performance.now() - startTime).toFixed(2);

  return {
    html: result.html,
    toc: result.toc,
    stats: {
      wordCount: result.wordCount,
      readingTimeMinutes: result.readingTime,
      renderDurationMs: durationMs,
    },
  };
}
```

---

## Example 3: Engineering Article Page with Hero Cover & TOC in React

Renders an in-depth technical article using `layout="article"` with a full-bleed hero cover image, author avatar and title, reading time estimate, pre-rendered KaTeX mathematics, and a sticky Table of Contents.

```tsx
'use client';

import React from 'react';
import { MarkonRender } from '@nofinite/markon/react';
import '@nofinite/nuicss/styles.css';

const postMarkdown = `
# Designing Perceptually Uniform UI Systems with OKLCH

Modern digital interfaces require color systems that behave predictably across dark and light modes. Traditional sRGB and HSL color models suffer from non-uniform perceived brightness.

## The Mathematical Foundation of OKLCH

The cylindrical projection OKLCH represents color via three coordinates: Lightness ($L$), Chroma ($C$), and Hue ($H$).

Euler's identity links five fundamental constants:

$$e^{i\\pi} + 1 = 0$$

## Implementing Dynamic Tokens with NUICSS

In **NUICSS**, tokens leverage CSS \`color-mix()\` in the OKLAB color space to generate harmonious surface tints and contrast borders:

\`\`\`css
:root {
  --color-primary: oklch(0.62 0.24 255);
  --color-surface: oklch(0.98 0.01 240);
}
\`\`\`
`;

export function EngineeringArticlePage() {
  return (
    
  );
}
```

---

## Example 4: Technical API Reference Handbook in React

Renders an API handbook with top navigation breadcrumbs, structured parameter tables, method badges, and a sticky sidebar Table of Contents with active scrollspy using `layout="document"`.

```tsx
'use client';

import React from 'react';
import { MarkonRender } from '@nofinite/markon/react';
import '@nofinite/nuicss/styles.css';

const apiHandbookContent = `
# Edge Session Verification API

The Session Verification API enables microservices to validate asymmetric cryptographic signatures issued by identity providers.

## Endpoint: Verify Session Token

\`POST /v2/sessions/verify\`

| Header | Format | Required | Description |
| :--- | :--- | :---: | :--- |
| \`Authorization\` | \`Bearer <jwt>\` | Yes | Signed Ed25519 identity token |
| \`X-Request-Nonce\` | \`uuidv4\` | Yes | Cryptographic nonce preventing replay |
`;

export function ApiDocumentationPage() {
  return (
    
  );
}
```

---

## Example 5: Next.js App Router Server-Side Rendered Blog

Render Markon documents in Next.js Server Components with **zero client JavaScript overhead**:

```tsx
// app/posts/[slug]/page.tsx (Server Component)
import { renderMarkdown } from '@nofinite/markon';
import '@nofinite/nuicss/styles.css';

interface PostData {
  title: string;
  bodyMarkdown: string;
}

declare function fetchPost(slug: string): Promise<PostData>;

export default async function BlogPostServerPage({ params }: { params: { slug: string } }) {
  const post = await fetchPost(params.slug);

  const { html, toc } = renderMarkdown(post.bodyMarkdown, {
    katex: true,
    highlight: true,
  });

  return (
    <main className="min-h-screen bg-surface max-w-4xl mx-auto py-12 px-6">
      <h1 className="text-4xl font-extrabold tracking-tight mb-8">{post.title}</h1>
      <div className="markon-render-container w-full" dangerouslySetInnerHTML={{ __html: html }} />
    </main>
  );
}
```

---


### Document: markon/installation/page.mdx

# Installation & Setup

Get started with `@nofinite/markon`.

**Nofinite Markon** is engineered as a **universal, framework-agnostic** authoring canvas and publication engine. The core library (`@nofinite/markon`) runs seamlessly in Vanilla TypeScript, Node.js scripts, Vue 3, Svelte 5, Astro, or Edge Workers with zero framework overhead. The React adapter (`@nofinite/markon/react`) provides declarative components for React 18 & 19.

---

## 1. Package Installation

Install `@nofinite/markon` alongside `@nofinite/nuicss` using your preferred package manager:

```bash
# pnpm
pnpm add @nofinite/markon @nofinite/nuicss

# npm
npm install @nofinite/markon @nofinite/nuicss

# yarn
yarn add @nofinite/markon @nofinite/nuicss

# bun
bun add @nofinite/markon @nofinite/nuicss
```

> **Optional Peer Dependency:** `react` and `react-dom` are strictly **optional** peer dependencies (`peerDependenciesMeta.react.optional: true`). If developing with Vanilla JS, Svelte, Vue, or SSR Node.js, you do not need to install React.

---

## 2. Stylesheet Setup

Editor typography, floating bubble menus, slash command palettes, table action bars, and callout styles are pre-compiled into **NUICSS**.

Include `@nofinite/nuicss` in your application stylesheet (`globals.css` or `main.ts`):

```css
/* In your CSS */
@import "@nofinite/nuicss";
```

Or in your JavaScript/TypeScript entry point:

```ts
import '@nofinite/nuicss/styles.css';
```

> **Zero Downstream CSS Invariant:** Do **not** import `@nofinite/markon/styles.css`. All necessary typography classes and design tokens are natively bundled in NUICSS.

---

## 3. Verification

### Option A: Framework-Agnostic Core Verification (Vanilla JS / TS / DOM)

Verify that the editor canvas mounts directly into a raw HTML container:

```html


<script type="module">
  import { MarkonEditor, renderMarkdown } from '@nofinite/markon';
  import '@nofinite/nuicss/styles.css';

  // 1. Mount interactive editor
  const editor = new MarkonEditor({
    element: document.getElementById('editor'),
    initialValue: '# Hello Markon\n\nStart typing with slash commands...',
    showSlashCommands: true,
    showBubbleMenu: true
  });

  // 2. Or compile Markdown to publication HTML (zero DOM required)
  const html = renderMarkdown('# Fast SSR\n\nRuns in Node.js or Edge.');
  console.log('Compiled HTML:', html);
</script>
```

### Option B: React Verification (`@nofinite/markon/react`)

If developing in React or Next.js, verify the declarative components:

```tsx
'use client';

import React, { useState } from 'react';
import { MarkonEditor, MarkonRender } from '@nofinite/markon/react';
import '@nofinite/nuicss/styles.css';

export default function DocumentPage() {
  const [content, setContent] = useState('<h2>Test Header</h2><p>Markon is active.</p>');

  return (
    
  );
}
```

---


### Document: markon/llms/page.mdx

# LLMs.txt Documentation

How to get tools like Cursor, Windsurf, GitHub Copilot, ChatGPT, and Claude to understand `@nofinite/markon`.

> [!TIP]
> Looking for unified ecosystem presets or multi-package rules? Visit our central [AI Agents Hub](/ai).

We support **LLMs.txt** files for making `@nofinite/markon` rich text editor and Markdown rendering primitives directly available to large language models.

---

## Directory Overview

The following machine-readable context files are available:

- [`/markon/llms.txt`](/markon/llms.txt): The main LLMs index for `@nofinite/markon`.
- [`/markon/llms-full.txt`](/markon/llms-full.txt): Complete context bundle containing MarkonEditor and MarkonRender APIs.
- [`/llms.txt`](/llms.txt): Ecosystem index covering all 8 `@nofinite` libraries.
- [`/llms-full.txt`](/llms-full.txt): The unified ecosystem bundle.

---

## Usage with Cursor & Windsurf

```markdown
# Markon Rules for AI Assistants
1. Component Imports: Import MarkonEditor and MarkonRender from '@nofinite/markon/react'.
2. WYSIWYG Authoring: Use MarkonEditor for interactive editing with slash commands and bubble menus.
3. Secure Display: Use MarkonRender for high-speed compiled document rendering.
```

---


### Document: markon/media-and-uploads/page.mdx

# Media and File Uploads

**Nofinite Markon** provides an integrated media subsystem covering interactive image resizing, alignment controls, video embeds, downloadable file attachments, and asynchronous upload placeholders.

All media widgets are styled with **NUICSS** superclasses and respect responsive container constraints.

```ts
// Framework-Agnostic Core
import { MarkonEditor } from '@nofinite/markon';

// React Adapter
import { MarkonEditor as ReactMarkonEditor } from '@nofinite/markon/react';
```

---

## Media Subsystem Capabilities

- **Interactive Images:** Corner drag handles for freeform scaling, width presets (`25%`, `50%`, `75%`, `100%`), alignment (`Left`, `Center`, `Right`), and accessible caption editing.
- **Video Embeds:** Responsive 16:9 embeds for YouTube, Vimeo, and direct MP4/WebM video URLs.
- **File Attachments:** Visual file cards with formatted size labels (e.g. `2.4 MB`) and download triggers for PDFs, ZIPs, and spreadsheets.

---

## 1. Framework-Agnostic Core Upload Handling

Pass `onUploadFile` directly to `MarkonEditor`:

```ts
import { MarkonEditor } from '@nofinite/markon';
import '@nofinite/nuicss/styles.css';

const container = document.querySelector('#editor')!;

const editor = new MarkonEditor({
  element: container,
  placeholder: "Drag and drop media or type '/'...",
  onUploadFile: async (file: File) => {
    const formData = new FormData();
    formData.append('media', file);

    const res = await fetch('/api/uploads', {
      method: 'POST',
      body: formData
    });
    const data = await res.json();

    // Return the uploaded CDN URL:
    return data.url;
  }
});
```

---

## 2. React Adapter Usage

In React applications, implement `onUploadFile`:

```tsx
import React, { useState } from 'react';
import { MarkonEditor } from '@nofinite/markon/react';
import '@nofinite/nuicss/styles.css';

export function MediaUploadingEditor() {
  const [content, setContent] = useState('');

  const handleUpload = async (file: File) => {
    const formData = new FormData();
    formData.append('file', file);

    const response = await fetch('/api/upload', { method: 'POST', body: formData });
    const data = await response.json();
    return data.url;
  };

  return (
    
  );
}
```

---


### Document: markon/page.mdx

<PackageHero packageId="markon" />

---

## Interactive Preview

<Preview 
  name="editor" 
  vanillaCode={`import { MarkonEditor } from '@nofinite/markon';
import '@nofinite/nuicss/styles.css';

const container = document.getElementById('editor-container');

// Mount rich authoring canvas directly to DOM
const editor = new MarkonEditor({
  element: container,
  initialValue: '<h2>Project Vision</h2><p>Start writing with rich formatting...</p>',
  showSlashCommands: true,
  showBubbleMenu: true,
  placeholder: "Type '/' for commands..."
});

// Programmatic export:
// const markdown = editor.getMarkdown();
// const html = editor.getHTML();
// editor.destroy();`}
/>

---

## Architecture: Authoring & Publication Pipeline

**Nofinite Markon** provides an end-to-end publishing pipeline split across two complementary subsystems:

```
[Authoring Canvas]                [Compiled Document AST]              [Publication Engine]
  MarkonEditor      ─── Exports ───>  TipTap JSON AST   ─── Renders ───>  renderMarkdown()
(Slash commands, DND)                or Markdown String                 (Article, Newsroom, Docs)
```

1. **Authoring Layer ([`MarkonEditor`](/markon/editor)):** A rich, keyboard-driven authoring canvas featuring Notion-style slash commands (`/`), gutter block drag handles (`⋮⋮`), interactive table pickers, and debounced draft auto-saving.
2. **UI Publication Layer ([`MarkonRender`](/markon/render)):** The visual presentation engine for compiled Markon JSON and Markdown documents. It transforms abstract ASTs into publication-grade editorial layouts (`article`, `document`, `newsroom`, `minimal`), generating automated sticky Table of Contents with scrollspy, compiling server-side KaTeX mathematics, and formatting author bylines and hero cover images.

---

## Quickstart

### 1. Framework-Agnostic Core (`@nofinite/markon`)

Mount the editor canvas directly to any HTML DOM node, or compile Markdown to HTML with zero DOM dependencies in **Vanilla JavaScript**, **TypeScript**, **Node.js**, **Vue 3**, **Svelte 5**, or **Astro**:

```ts
import { MarkonEditor, renderMarkdown } from '@nofinite/markon';
import '@nofinite/nuicss/styles.css';

// A. Interactive Authoring Canvas in pure DOM
const container = document.getElementById('editor')!;
const editor = new MarkonEditor({
  element: container,
  initialValue: '# Hello World\n\nType `/` for slash commands...',
  showSlashCommands: true,
  showBubbleMenu: true,
  onChange: (html, json, text) => {
    console.log('Document updated:', text);
  }
});

// B. Isomorphic Publication Compiler (runs in Node.js, SSR, or browser)
const publicationHtml = renderMarkdown('# Architectural Whitepaper\n\n$$e^{i\\pi} + 1 = 0$$', {
  layout: 'article',
  showTOC: true
});
```

### 2. React Adapter (`@nofinite/markon/react`)

Declarative React JSX components for React 18 & 19:

```tsx
import React, { useState } from 'react';
import { MarkonEditor, MarkonRender } from '@nofinite/markon/react';
import '@nofinite/nuicss/styles.css';

export default function DocumentEditor() {
  const [content, setContent] = useState('<h2>Project Vision</h2><p>Start writing with rich formatting...</p>');

  return (
    
  );
}
```

---

## Core Capabilities

- **Framework-Agnostic Isomorphic Core**: The root `@nofinite/markon` package runs in pure DOM or server-side Node.js with zero React requirements.
- **4 Specialized Publication Layouts**: Built-in responsive presentation modes for articles, technical documentation, press releases, and minimal embeds.
- **Notion-Style Slash Commands (`/`)**: Type `/` anywhere on a blank line to open a floating command palette for headings, tables, callout boxes, code blocks, and math equations.
- **Gutter Block Drag Handles**: Hover handles for tactile drag-and-drop block reordering, selection, and contextual block transformations.
- **Interactive Data Tables**: 10×10 visual dimension picker, cell merging/splitting, and contextual table action toolbars.
- **Pre-Rendered KaTeX Math**: Math equations are compiled server-side into accessible SVG/HTML without requiring client-side KaTeX runtime scripts.
- **Lowlight Syntax Highlighting**: High-speed AST syntax highlighting across 16 programming languages with 1-click clipboard copy buttons.
- **Draft Auto-Save & Recovery**: Background debounced persistence with live status indicators (`saving`, `saved`, `error`) and crash recovery dialogs.

---

## Documentation Directory

### Advanced Architecture & Deep Guides
- [Markon Publication Renderer](/markon/render) — Complete guide to compiled publication layouts (`article`, `document`, `newsroom`, `minimal`) and SSR execution.
- [Slash Commands Palette](/markon/slash-commands) — Notion-style floating `/` command palette and extension options.
- [Gutter Block Drag Handles](/markon/block-handles) — Tactile block drag handles (`⋮⋮`) and reordering mechanics.
- [Tables & Grids](/markon/tables-and-grids) — Interactive matrix pickers, row/column operations, and cell styling.
- [Callouts & Collapsible Details](/markon/callouts-and-details) — GitHub-style callouts (`:::info`) and interactive accordions.
- [Draft Management & Auto-Save](/markon/draft-management) — Local persistence, debounced auto-saving, and crash recovery.
- [Media & File Uploads](/markon/media-and-uploads) — Direct S3/R2 uploads, drag-and-drop images, and video embedding.
- [Production Examples](/markon/examples) — Production-grade CMS editors, newsroom publication pipelines, and technical documentation hubs.

### Primitives & Setup
- [Installation & Setup](/markon/installation) — Package installation, styling configuration, and peer dependencies.
- [MarkonEditor Authoring Canvas](/markon/editor) — Full API reference for the rich text editor canvas.

---


### Document: markon/render/page.mdx

# Markon Publication Renderer

`MarkonRender` is the **UI publication and presentation engine** of the Markon ecosystem. Rather than serving as a passive viewer, it is designed to consume compiled Markon JSON ASTs, sanitized HTML, or GitHub-Flavored Markdown and transform them into publication-grade editorial layouts, technical documentation, press releases, and structured handbooks.

Powered by **NUICSS** design tokens and superclasses, the renderer is **completely isomorphic with zero DOM dependencies**, allowing it to execute seamlessly in Next.js Server Components, Node.js scripts, and Edge workers, while hydrating interactively on the client.

```ts
// Framework-Agnostic Core (Zero-DOM Isomorphic Compiler)
import { renderMarkdown, renderMarkonContent, type MarkonRenderOptions } from '@nofinite/markon';

// React Adapter (Components)
import { MarkonRender } from '@nofinite/markon/react';
```

---

## Interactive Preview



---

## The 4 Built-In Layout Modes

| Layout Mode | Intended Purpose | Visual Chrome & Elements |
| :--- | :--- | :--- |
| **`article`** *(default)* | Editorial blogs, magazines, and long-form features | Responsive hero cover image, author byline card (avatar, title, profile link), reading time badge, category tag, and sticky interactive Table of Contents |
| **`document`** | Technical handbooks, manuals, and API guides | Header breadcrumbs, last-modified timestamp, and sticky sidebar TOC with active scrollspy |
| **`newsroom`** | Official press releases and corporate announcements | Bold kicker badge, prominent headline, and dateline header with author credentials |
| **`minimal`** | Clean prose container for embeds, modals, and comments | Zero decorative chrome or header metadata; pure styled typographic container |

---

## 1. Framework-Agnostic Core Usage

### Zero-DOM Isomorphic Execution (`renderMarkdown`)

Compile Markdown directly to production HTML in **Node.js**, **Cloudflare Workers**, **Astro**, **Svelte**, or **Vue** without running a browser DOM:

```ts
import { renderMarkdown } from '@nofinite/markon';
import '@nofinite/nuicss/styles.css';

const markdownSource = `
# Designing Perceptually Uniform UI Systems with OKLCH

Modern digital interfaces require color systems that behave predictably across dark and light modes.

## The Mathematical Foundation of OKLCH

Euler's identity links five fundamental constants:

$$e^{i\\pi} + 1 = 0$$

:::info
All components strictly consume tokens from \`@nofinite/nuicss\`.
:::
`;

// Compile to full editorial HTML with KaTeX and lowlight highlighting:
const html = renderMarkdown(markdownSource, {
  layout: 'article',
  metadata: {
    title: 'Designing Perceptually Uniform UI Systems with OKLCH',
    author: {
      name: 'Elena Rostova',
      title: 'Principal Systems Architect'
    },
    publishedAt: '2026-03-15',
    category: 'Architecture'
  },
  showTOC: true
});

// Inject into response:
// res.setHeader('Content-Type', 'text/html');
// res.send(html);
```

---

## 2. React Adapter Usage

In React applications or Next.js App Router pages:

```tsx
import React from 'react';
import { MarkonRender } from '@nofinite/markon/react';
import '@nofinite/nuicss/styles.css';

const postMarkdown = `
# Designing Perceptually Uniform UI Systems with OKLCH

Modern digital interfaces require color systems that behave predictably across dark and light modes.

$$e^{i\\pi} + 1 = 0$$
`;

export function BlogPost() {
  return (
    
  );
}
```

---

## Configuration Reference

| Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `content` | `string \| JSONContent` | — | Raw Markdown string, HTML, or TipTap JSONContent AST |
| `layout` | `'article' \| 'document' \| 'newsroom' \| 'minimal'` | `'article'` | Structural presentation mode |
| `metadata` | `MarkonMetadata` | — | Title, cover image, author credentials, date, and category tags |
| `showTOC` | `boolean` | `true` | Renders sticky interactive Table of Contents with scrollspy |
| `highlightCode`| `boolean` | `true` | AST code syntax highlighting via Lowlight across 16 languages |
| `renderMath` | `boolean` | `true` | Pre-compiles KaTeX LaTeX formulas into accessible HTML/SVG |

---


### Document: markon/slash-commands/page.mdx

# Slash Commands

**Nofinite Markon** includes a Notion-style contextual command palette activated by typing `/` anywhere on an empty line or after whitespace.

The slash command menu enables authors to quickly format text, insert structural elements, embed rich media, and execute custom workflows entirely from the keyboard.

```ts
// Framework-Agnostic Core
import { MarkonEditor, createSlashCommandExtension } from '@nofinite/markon';

// React Adapter
import { MarkonEditor as ReactMarkonEditor } from '@nofinite/markon/react';
```

---

## Overview

- **Trigger:** Type `/` on a new line or after whitespace.
- **Navigation:** Use <kbd>↑</kbd> and <kbd>↓</kbd> arrow keys to navigate options.
- **Selection:** Press <kbd>Enter</kbd> or <kbd>Tab</kbd> to execute the selected command.
- **Dismissal:** Press <kbd>Escape</kbd> or continue typing to dismiss the popover.

---

## 1. Framework-Agnostic Core Usage

Enable slash commands when initializing `MarkonEditor`:

```ts
import { MarkonEditor } from '@nofinite/markon';
import '@nofinite/nuicss/styles.css';

const container = document.querySelector('#editor')!;

const editor = new MarkonEditor({
  element: container,
  initialValue: '<p>Type <code>/</code> for commands...</p>',
  showSlashCommands: true, // Enabled by default
  placeholder: "Type '/' for commands..."
});
```

---

## 2. React Adapter Usage

In React applications, configure slash commands via component props:

```tsx
import React, { useState } from 'react';
import { MarkonEditor } from '@nofinite/markon/react';
import '@nofinite/nuicss/styles.css';

export function EditorWithCommands() {
  const [content, setContent] = useState('<p>Type <code>/</code> to see commands...</p>');

  return (
    
  );
}
```

---

## Built-In Commands Registry

The default registry includes 20 production-ready commands:

| Command | Title | Description | Resulting Action |
| :--- | :--- | :--- | :--- |
| `/h1` | **Heading 1** | Large section heading | Inserts `<h1>` node |
| `/h2` | **Heading 2** | Medium section heading | Inserts `<h2>` node |
| `/h3` | **Heading 3** | Small section heading | Inserts `<h3>` node |
| `/bullet` | **Bullet List** | Unordered bulleted list | Toggles unordered `<ul>` list |
| `/number` | **Numbered List** | Ordered numerical list | Toggles ordered `<ol>` list |
| `/todo` | **Task List** | Interactive checklist with boxes | Inserts task list with checkboxes |
| `/quote` | **Blockquote** | Editorial block quote | Inserts `<blockquote>` node |
| `/code` | **Code Block** | Syntax-highlighted code container | Inserts fenced code block with language selector |
| `/table` | **Table (3x3)** | Data table with header row | Inserts 3x3 table with headers |
| `/math` | **Math Formula** | LaTeX / KaTeX block | Inserts mathematical formula editor |
| `/video` | **Video Embed** | Responsive YouTube, Vimeo, MP4 | Opens modal for video URL |
| `/toggle` | **Collapsible Section** | Notion-style accordion | Inserts `<details>` and `<summary>` |
| `/image` | **Image** | Media image with alignment | Opens file picker or URL modal |
| `/file` | **File Attachment** | Downloadable document pill | Opens file attachment picker |
| `/divider`| **Horizontal Rule** | Visual dividing line | Inserts `<hr>` separator |
| `/highlight` | **Highlight** | Pastel color text background | Applies semantic text highlight |
| `/info` | **Info Callout** | Blue informational note box | Inserts Info alert container |
| `/success`| **Success Callout**| Green confirmation tip box | Inserts Success alert container |
| `/warning`| **Warning Callout**| Amber advisory caution box | Inserts Warning alert container |
| `/danger` | **Danger Callout** | Red error or danger box | Inserts Danger alert container |

---


### Document: markon/tables-and-grids/page.mdx

# Tables and Grids

**Nofinite Markon** provides an interactive table editing and isomorphic rendering suite designed for structured tabular data, API specifications, benchmarks, and financial matrices.

It combines an intuitive visual dimension picker with contextual cell toolbars, cell merging/splitting, and full GitHub-Flavored Markdown table interoperability across both headless DOM/Node runtimes and React.

---

## Key Features

- **Visual Dimension Picker:** Hover-to-select grid popup supporting table sizes up to 10×10.
- **Contextual Table Toolbar:** A floating action bar that automatically appears when the text cursor enters any table cell.
- **Structural Row & Column Commands:** 1-click actions to insert rows above/below, columns left/right, and delete targeted segments.
- **Cell Merging & Splitting:** Combine adjacent rectangular cell ranges or split merged cells back into standard grid units.
- **Header Toggles:** Independently enable or disable top header rows (`<th>`) and left header columns.
- **Zero-DOM Server Table Compilation:** `renderMarkdown()` compiles GFM Markdown tables to clean semantic HTML with zero DOM dependencies.

---

## Interactive Table Toolbar

When an author clicks inside any table cell, a floating context toolbar activates with the following commands:

| Action | Core Command | Description |
| :--- | :--- | :--- |
| **Add Row Above / Below** | `addRowBefore()` / `addRowAfter()` | Inserts a blank row directly above or below current cell |
| **Add Column Left / Right** | `addColumnBefore()` / `addColumnAfter()` | Inserts a blank column to left or right of current cell |
| **Delete Row / Column** | `deleteRow()` / `deleteColumn()` | Removes the current row or column |
| **Merge Cells** | `mergeCells()` | Merges selected adjacent cells into a single spanning cell |
| **Split Cell** | `splitCell()` | Splits a previously merged cell back into its original grid units |
| **Toggle Header** | `toggleHeaderRow()` | Toggles the top row between normal cells and header cells (`<th>`) |
| **Delete Table** | `deleteTable()` | Completely removes the entire table structure |

---

## 1. Usage in Vanilla TypeScript / DOM (Core First)

In pure JavaScript or TypeScript, table functionality is available directly via `MarkonEditor` or imperatively through the underlying editor instance:

```ts
import { MarkonEditor, renderMarkdown } from '@nofinite/markon';
import '@nofinite/nuicss/styles.css';

const initialMarkdown = `
## Cluster Node Specifications

| Node ID | Region | CPU Cores | Memory (GiB) | Status |
| :--- | :--- | :---: | :---: | :--- |
| \`worker-01\` | us-east-1a | 32 | 128 | Active |
| \`worker-02\` | us-east-1b | 64 | 256 | Active |
| \`worker-03\` | eu-central-1 | 16 | 64 | Standby |
`;

const container = document.getElementById('editor-root')!;

// 1. Initialize Markon Editor with Tables enabled
const editor = new MarkonEditor({
  element: container,
  content: initialMarkdown,
  tables: true, // Enables table extensions, floating cell menu, and dimension picker
  onChange: (markdown) => {
    console.log('Updated Markdown:', markdown);
  },
});

// 2. Imperative Table Commands via Core Engine
const addRowBtn = document.getElementById('add-row-btn')!;
addRowBtn.addEventListener('click', () => {
  editor.editor.chain().focus().addRowAfter().run();
});

const mergeBtn = document.getElementById('merge-cells-btn')!;
mergeBtn.addEventListener('click', () => {
  editor.editor.chain().focus().mergeCells().run();
});

// 3. Fast Headless / Server-Side Table Compilation (Zero DOM)
const { html } = renderMarkdown(initialMarkdown);
console.log('Compiled Table HTML:', html);
```

### Table HTML Output Structure

```html

</div>
```

---

## 2. Usage in React

In React applications, `@nofinite/markon/react` wraps the core table extensions and contextual floating action menus into declarative components:

```tsx
'use client';

import React, { useState } from 'react';
import { MarkonEditor } from '@nofinite/markon/react';
import '@nofinite/nuicss/styles.css';

const initialTableContent = `
## Database Sharding Strategy

| Cluster ID | Region | Read Replicas | Status |
| :--- | :--- | :---: | :--- |
| \`shard-alpha\` | us-east-1 | 4 | Primary |
| \`shard-beta\` | eu-west-1 | 2 | Synchronized |
| \`shard-gamma\` | ap-southeast-1 | 2 | Provisioning |
`;

export function TechnicalSpecEditor() {
  const [content, setContent] = useState(initialTableContent);

  return (
    
  );
}
```

---

## Framework Integration Recipes

### Vue 3 (Composition API)

```vue
<script setup lang="ts">
import { ref, onMounted, onBeforeUnmount } from 'vue';
import { MarkonEditor } from '@nofinite/markon';
import '@nofinite/nuicss/styles.css';

const editorEl = ref<HTMLElement | null>(null);
let editor: MarkonEditor | null = null;
const doc = ref('| Column A | Column B |\n| --- | --- |\n| Cell 1 | Cell 2 |');

onMounted(() => {
  if (editorEl.value) {
    editor = new MarkonEditor({
      element: editorEl.value,
      content: doc.value,
      tables: true,
      onChange: (val) => { doc.value = val; },
    });
  }
});

onBeforeUnmount(() => {
  editor?.destroy();
});
</script>

<template>
  
```

---