Documentation

Content: HTML, Markdown, JSON

JSON is canonical and lossless. HTML is lossless for everything Penna can produce. Markdown covers everything but colors/alignment (rendered as plain text). Recommended: store JSON, render with renderToHTML.

import { renderToHTML, toMarkdown, fromMarkdown } from '@abhinavakhil/penna-core'
renderToHTML(json)            // string, no DOM needed
toMarkdown(fromMarkdown(md))  // parser/serializer are exported too

Rendering content anywhere

Three ways to show saved content:

1. Server / no editor: renderToHTML(json) and wrap it in <div class="penna-content"> with penna.css loaded. Pixel-identical to the editor. Works in Node, Workers, Deno, Bun.
2. React / Vue: <PennaContent json={doc} />.
3. Read-only editor: createEditor(el, { content, readonly: true, toolbar: false }). Checkbox and embed interactions still work.

Sanitise on the server if content comes from untrusted users. The schema already rejects script, inline handlers and unknown tags, but defence in depth is cheap.

Images & uploads

Drop, paste, pick from the toolbar, or /image. Images get resize handles, alignment and alt text when selected. Videos too. By default files are stored inline as data URLs so it works with zero setup; for real apps pass onUpload:

createEditor('#editor', {
  onUpload: async (file) => {
    const { url } = await supabase.storage.from('images').upload(`${crypto.randomUUID()}-${file.name}`, file)
    return url   // any string URL — S3, Cloudinary, your API…
  },
})

Pasting a bare image URL inserts an image. Pasting a YouTube / Vimeo / Loom / Figma / CodePen link on an empty line inserts an embed. Pasting a URL over selected text makes a link.

AI

import { ai } from '@abhinavakhil/penna-ai'

createEditor('#editor', {
  extensions: [
    ai({
      provider: 'groq',          // 'groq' | 'gemini' | 'openrouter' | 'together' | 'ollama'
      apiKey: KEY,               //  | 'openai' | 'mistral' | 'openai-compatible'
      // model: 'llama-3.3-70b-versatile',   // optional, each provider has a good default
      // baseUrl: 'https://your-proxy/v1',   // required for 'openai-compatible'
      // fetch: myFetch,                     // route through your server
      // actions: [...defaultActions, myAction],
    }),
  ],
})

Free by default. Groq, Gemini, OpenRouter and Together all have free tiers; Ollama is free and local. Paid models work through the OpenAI, Mistral presets or any OpenAI-compatible URL (Anthropic via a shim, Azure, Vercel AI Gateway, LiteLLM, your own proxy).

Triggers: Ctrl+J, the ✦ button in the bubble menu and toolbar, or /ai and /continue. Results stream into a preview; nothing changes the document until you accept.

Custom actions: an action is { id, title, prompt(ctx) → messages, mode?: "replace" | "insert", askInput? }. Pass actions to replace the list, or spread defaultActions to extend it.

Production note: a key in the browser is visible to your users. Point baseUrl at a tiny proxy that adds the key server-side, or pass a custom fetch. Hosted Penna AI (no key, usage-billed) is planned; provider: 'penna' is reserved for it.

Themes, dark mode & RTL

On auto, Penna follows data-theme="dark" (or Tailwind's .dark) on any ancestor, then prefers-color-scheme. Force a theme with theme: 'light' | 'dark' | 'sepia'. For Urdu, Arabic or Hebrew set dir: 'rtl'; the stylesheet uses logical properties, so everything mirrors. Every color is a CSS variable on .penna and .penna-content:

.penna, .penna-content {
  --pn-font: Inter, sans-serif;
  --pn-accent: #e11d48;        /* links, active buttons, selection */
  --pn-bg: #fff;  --pn-fg: #111;  --pn-muted: #666;  --pn-border: #eee;
  --pn-surface: #fff;          /* menus, toolbar */
  --pn-radius: 12px;
  --pn-highlight: #fef08a;  --pn-code-bg: #f3f4f6;  --pn-pre-bg: #0f172a;
}

Class names are stable and prefixed with pn- if you want to go further.

Typography choices are stored on paragraph and heading nodes, so JSON and HTML preserve them. Penna never downloads fonts in your users' applications; load the families you expose through your own CSS or font host:

createEditor('#editor', {
  typography: {
    bodyFontFamily: 'Inter',
    headingFontFamily: 'Plus Jakarta Sans',
    fontFamilies: [
      { label: 'Brand Sans', value: 'Brand Sans' },
      { label: 'Editorial Serif', value: 'Lora' },
    ],
    fontSizes: ['14px', '16px', '18px', '24px', '32px'],
    lineHeights: ['1', '1.25', '1.5', '1.75', '2'],
  },
})

Built-in extensions

All opt-in and exported from @abhinavakhil/penna-core. Add only the ones you need:

import { shortcuts, fundraisingShortcuts, proofread, mentions, mergeFields, comments, versionHistory, focusMode } from '@abhinavakhil/penna-core'

createEditor('#editor', { extensions: [
  shortcuts({ items: fundraisingShortcuts }),        // /budget, /impact, /milestones · Ctrl+Alt+B/I/M
  proofread({ onChange: (s) => showScore(s.score) }), // typos, wordy phrases, long sentences
  mentions({ items: (q) => api.people(q) }),        // @Name
  mergeFields({ fields: [{ key: 'first_name', label: 'first name' }] }), // {{first_name}}
  comments({ onAdd: (c) => api.createThread(c), onSelect: openThread }),
  versionHistory({ key: 'campaign-42', author: user.name }),
  focusMode({ level: 'sentence' }),
] })

Helpers for your own features: readability(text) (grade and reading age), diffWords / diffHTML, commands.insertStarter('My name is ___'), and suggestPlugin() to build your own trigger-character menu.

Writing your own extension

An extension is a plain object. This is how @abhinavakhil/penna-ai is built, and it's enough for most needs:

import { commands, type PennaExtension } from '@abhinavakhil/penna-core'

const signature: PennaExtension = {
  name: 'signature',
  slashItems: [{ id: 'sig', title: 'Signature', icon: '✍️', group: 'Custom', run: (view) => {
    view.dispatch(view.state.tr.insertText('— Abhinav'))
  }}],
  bubbleItems: [{ id: 'shout', icon: 'highlight', label: 'Shout', run: (view) => commands.highlight('#fca5a5')(view.state, view.dispatch) }],
  toolbarItems: ['|', { id: 'sig', icon: 'text', label: 'Signature', run: (view) => view.dispatch(view.state.tr.insertText('— Abhinav')) }],
  plugins: (editor) => [ /* any ProseMirror plugins */ ],
}
createEditor('#editor', { extensions: [signature] })

To fully replace a menu, pass your own array to toolbar, bubbleMenu or slashMenu. defaultToolbarItems, defaultBubbleItems and defaultSlashItems are exported so you can filter or reorder them. The schema, keymap, input rules and every plugin are exported from @abhinavakhil/penna-core if you want to build something entirely different on top.

Keyboard shortcuts