# Luthor Documentation Full Corpus Concatenated markdown corpus for AI ingestion. Source root: C:\Users\rahul\Documents\GitHub\luthor\apps\web\src\content\docs Generated at: 2026-02-24T16:49:15.770Z --- ## FILE: getting-started/index.md ## URL: https://www.luthor.fyi/docs/getting-started/ --- --- title: Introduction description: What @lyfie/luthor and @lyfie/luthor-headless are, and when to use each package. --- # Introduction `@lyfie/luthor` and `@lyfie/luthor-headless` solve different needs. ## @lyfie/luthor Use this when you want a production-ready editor quickly. - Includes preset editors and prebuilt UI - Includes `@lyfie/luthor-headless` under the hood - Best for fast shipping with strong defaults ## @lyfie/headless Use this when you want full control over UI and behavior. - Extension-first architecture - Bring your own toolbar and app UX - Best for custom product-specific editing flows ## Compatibility Based on package metadata in `packages/luthor/package.json` and `packages/headless/package.json`: - React: `^18.0.0 || ^19.0.0` - React DOM: `^18.0.0 || ^19.0.0` - TypeScript/TSX: fully supported - Lexical: - `@lyfie/luthor`: uses Lexical `^0.40.0` dependencies internally - `@lyfie/luthor-headless`: peer dependency `>=0.40.0` for `lexical` and required `@lexical/*` packages ## Recommended path 1. [Introduction](/docs/getting-started/) 2. [Installation](/docs/getting-started/installation/) 3. [@lyfie/headless](/docs/getting-started/luthor-headless/) 4. [@lyfie/luthor](/docs/getting-started/luthor/) --- ## FILE: getting-started/installation.md ## URL: https://www.luthor.fyi/docs/getting-started/installation/ --- --- title: Installation description: Install, update, and uninstall @lyfie/luthor and @lyfie/luthor-headless. --- # Installation This page covers install, update, and uninstall for both packages. ## Install @lyfie/luthor ```bash npm install @lyfie/luthor react react-dom ``` ## Install @lyfie/luthor-headless ```bash npm install @lyfie/luthor-headless lexical @lexical/code @lexical/link @lexical/list @lexical/markdown @lexical/react @lexical/rich-text @lexical/selection @lexical/table @lexical/utils react react-dom ``` Optional for headless: ```bash npm install highlight.js @emoji-mart/data ``` ## Update packages ```bash npm update @lyfie/luthor @lyfie/luthor-headless ``` ## Uninstall packages ```bash npm uninstall @lyfie/luthor @lyfie/luthor-headless ``` If you installed headless peers directly and want to remove them too: ```bash npm uninstall lexical @lexical/code @lexical/link @lexical/list @lexical/markdown @lexical/react @lexical/rich-text @lexical/selection @lexical/table @lexical/utils highlight.js @emoji-mart/data ``` ## Common mistakes 1. Missing Lexical peer dependencies for headless setup 2. Missing `@lyfie/luthor/styles.css` import for presets 3. React/Lexical version mismatch 4. Following preset docs when implementing headless UI (or vice versa) --- ## FILE: getting-started/luthor-headless.md ## URL: https://www.luthor.fyi/docs/getting-started/luthor-headless/ --- --- title: "@lyfie/headless" description: Minimal setup and validation for @lyfie/luthor-headless. --- # @lyfie/headless Use this when you need full control over editor UI. ## Install ```bash npm install @lyfie/luthor-headless lexical @lexical/code @lexical/link @lexical/list @lexical/markdown @lexical/react @lexical/rich-text @lexical/selection @lexical/table @lexical/utils react react-dom ``` ## Render a minimal headless editor ```tsx import { createEditorSystem, RichText, richTextExtension, boldExtension, italicExtension, } from '@lyfie/luthor-headless'; const extensions = [richTextExtension, boldExtension, italicExtension] as const; const { Provider, useEditor } = createEditorSystem(); function Toolbar() { const { commands, activeStates } = useEditor(); return (
); } export function App() { return ( ); } ``` ## Validate installation - Text area mounts - Buttons execute bold and italic commands - No missing peer dependency errors for Lexical packages --- ## FILE: getting-started/luthor.md ## URL: https://www.luthor.fyi/docs/getting-started/luthor/ --- --- title: "@lyfie/luthor" description: Minimal setup and validation for the preset package. --- # @lyfie/luthor Use this when you want a ready-to-use editor quickly. ## Install ```bash npm install @lyfie/luthor react react-dom ``` ## Render a basic editor ```tsx import { ExtensiveEditor } from '@lyfie/luthor'; import '@lyfie/luthor/styles.css'; export function App() { return ; } ``` ## Validate installation - You can type in the editor - Toolbar appears - No module resolution errors in the dev server --- ## FILE: luthor-headless/features.md ## URL: https://www.luthor.fyi/docs/luthor-headless/features/ --- --- title: Features description: Grouped feature documentation for @lyfie/luthor-headless. --- # Features Feature docs are grouped to match the home page feature set. ## Feature groups - [Typography and Text](/docs/luthor-headless/features/typography-and-text/) - [Structure and Lists](/docs/luthor-headless/features/structure-and-lists/) - [Media and Embeds](/docs/luthor-headless/features/media-and-embeds/) - [Code and Devtools](/docs/luthor-headless/features/code-and-devtools/) - [Interaction and Productivity](/docs/luthor-headless/features/interaction-and-productivity/) - [Customization and Theming](/docs/luthor-headless/features/customization-and-theming/) ## Base runtime ```tsx import { createEditorSystem, RichText, richTextExtension } from '@lyfie/luthor-headless'; const extensions = [richTextExtension] as const; const { Provider } = createEditorSystem(); export function App() { return ( ); } ``` --- ## FILE: luthor-headless/features/code-and-devtools.md ## URL: https://www.luthor.fyi/docs/luthor-headless/features/code-and-devtools/ --- --- title: Code and Devtools description: Code blocks, syntax support, and markdown/json conversion tools. --- # Code and Devtools This group covers code editing and developer-facing utilities. ## Included extensions and utilities - `codeExtension` - `codeIntelligenceExtension` - `codeFormatExtension` - `markdownToJSONB`, `jsonbToMarkdown` ## Example: code editor setup ```tsx import { createEditorSystem, RichText, richTextExtension, codeExtension, codeIntelligenceExtension, } from '@lyfie/luthor-headless'; const extensions = [richTextExtension, codeExtension, codeIntelligenceExtension] as const; const { Provider, useEditor } = createEditorSystem(); function Toolbar() { const { commands } = useEditor(); return ; } export function App() { return ( ); } ``` ## Example: markdown bridge ```ts import { markdownToJSONB, jsonbToMarkdown } from '@lyfie/luthor-headless'; const json = markdownToJSONB('# Title\n\nSome text'); const markdown = jsonbToMarkdown(json); ``` --- ## FILE: luthor-headless/features/customization-and-theming.md ## URL: https://www.luthor.fyi/docs/luthor-headless/features/customization-and-theming/ --- --- title: Customization and Theming description: Custom nodes, theme tokens, and extension-level customization. --- # Customization and Theming This group covers custom block logic and theming APIs. ## Included APIs - `createCustomNodeExtension` - `defaultLuthorTheme` - `mergeThemes` - `createEditorThemeStyleVars` ## Example: custom extension ```tsx import { createEditorSystem, RichText, richTextExtension, createCustomNodeExtension, } from '@lyfie/luthor-headless'; const calloutExtension = createCustomNodeExtension({ key: 'callout', category: 'block', nodeType: 'element', createNode: ({ $createParagraphNode, $createTextNode }) => { const node = $createParagraphNode(); node.append($createTextNode('Callout block')); return node; }, }); const extensions = [richTextExtension, calloutExtension] as const; const { Provider } = createEditorSystem(); export function App() { return ( ); } ``` ## Example: theme override ```ts import { mergeThemes, defaultLuthorTheme } from '@lyfie/luthor-headless'; const theme = mergeThemes(defaultLuthorTheme, { colors: { background: '#0b1020', foreground: '#f8fafc', }, }); ``` --- ## FILE: luthor-headless/features/interaction-and-productivity.md ## URL: https://www.luthor.fyi/docs/luthor-headless/features/interaction-and-productivity/ --- --- title: Interaction and Productivity description: Slash commands, command palette, shortcuts, history, and contextual UI. --- # Interaction and Productivity This group covers keyboard-first and contextual workflows. ## Included extensions - `historyExtension` - `enterKeyBehaviorExtension` - `commandPaletteExtension` - `slashCommandExtension` - `floatingToolbarExtension` - `contextMenuExtension` - `emojiExtension` - `draggableBlockExtension` ## Example ```tsx import { createEditorSystem, RichText, richTextExtension, historyExtension, commandPaletteExtension, slashCommandExtension, draggableBlockExtension, } from '@lyfie/luthor-headless'; const extensions = [ richTextExtension, historyExtension, commandPaletteExtension, slashCommandExtension, draggableBlockExtension, ] as const; const { Provider, useEditor } = createEditorSystem(); function Toolbar() { const { commands } = useEditor(); return (
); } export function App() { return ( ); } ``` --- ## FILE: luthor-headless/features/media-and-embeds.md ## URL: https://www.luthor.fyi/docs/luthor-headless/features/media-and-embeds/ --- --- title: Media and Embeds description: Image, iframe, and YouTube embedding features. --- # Media and Embeds This group covers rich media insertion. ## Included extensions - `imageExtension` - `iframeEmbedExtension` - `youTubeEmbedExtension` ## Example ```tsx import { createEditorSystem, RichText, richTextExtension, imageExtension, iframeEmbedExtension, youTubeEmbedExtension, } from '@lyfie/luthor-headless'; const extensions = [ richTextExtension, imageExtension, iframeEmbedExtension, youTubeEmbedExtension, ] as const; const { Provider, useEditor } = createEditorSystem(); function Toolbar() { const { commands } = useEditor(); return (
); } export function App() { return ( ); } ``` --- ## FILE: luthor-headless/features/structure-and-lists.md ## URL: https://www.luthor.fyi/docs/luthor-headless/features/structure-and-lists/ --- --- title: Structure and Lists description: Headings, links, lists, tables, and document structure tools. --- # Structure and Lists This group covers links, headings, paragraphs, lists, and table workflows. ## Included extensions - `linkExtension` - `blockFormatExtension` - `listExtension` - `tableExtension` - `horizontalRuleExtension` - `tabIndentExtension` ## Example ```tsx import { createEditorSystem, RichText, richTextExtension, linkExtension, blockFormatExtension, listExtension, tableExtension, horizontalRuleExtension, tabIndentExtension, } from '@lyfie/luthor-headless'; const extensions = [ richTextExtension, linkExtension, blockFormatExtension, listExtension, tableExtension, horizontalRuleExtension, tabIndentExtension, ] as const; const { Provider, useEditor } = createEditorSystem(); function Toolbar() { const { commands } = useEditor(); return (
); } export function App() { return ( ); } ``` --- ## FILE: luthor-headless/features/typography-and-text.md ## URL: https://www.luthor.fyi/docs/luthor-headless/features/typography-and-text/ --- --- title: Typography and Text description: Fonts, line-height, and text-formatting capabilities. --- # Typography and Text This group covers typography, essentials, and color controls. ## Included extensions - `boldExtension`, `italicExtension`, `underlineExtension`, `strikethroughExtension` - `subscriptExtension`, `superscriptExtension`, `codeFormatExtension` - `fontFamilyExtension`, `fontSizeExtension`, `lineHeightExtension` - `textColorExtension`, `textHighlightExtension` ## Example ```tsx import { createEditorSystem, RichText, richTextExtension, boldExtension, italicExtension, underlineExtension, fontFamilyExtension, fontSizeExtension, lineHeightExtension, textColorExtension, textHighlightExtension, } from '@lyfie/luthor-headless'; const extensions = [ richTextExtension, boldExtension, italicExtension, underlineExtension, fontFamilyExtension, fontSizeExtension, lineHeightExtension, textColorExtension, textHighlightExtension, ] as const; const { Provider, useEditor } = createEditorSystem(); function Toolbar() { const { commands, activeStates } = useEditor(); return (
); } export function App() { return ( ); } ``` ## Relevant props - `RichText.placeholder`: `undefined (default) | string` - `RichText.disabled`: `false (default) | true` --- ## FILE: luthor/presets.md ## URL: https://www.luthor.fyi/docs/luthor/presets/ --- --- title: Presets description: Preset catalog for @lyfie/luthor, including per-preset docs. --- # Presets `@lyfie/luthor` is a preset package built on top of `@lyfie/luthor-headless`. ## Importing headless from presets package ```ts import { headless } from '@lyfie/luthor'; ``` ## Preset docs - [Extensive](/docs/luthor/presets/extensive-editor/) - [Simple Text](/docs/luthor/presets/simple-text-editor/) - [Rich Text](/docs/luthor/presets/rich-text-box-editor/) - [Chat Window](/docs/luthor/presets/chat-window-editor/) - [Email Compose](/docs/luthor/presets/email-compose-editor/) - [Markdown](/docs/luthor/presets/md-text-editor/) - [Notion Like](/docs/luthor/presets/notion-like-editor/) - [Headless Preset](/docs/luthor/presets/headless-editor-preset/) - [Notes](/docs/luthor/presets/notes-editor/) --- ## FILE: luthor/presets/chat-window-editor.md ## URL: https://www.luthor.fyi/docs/luthor/presets/chat-window-editor/ --- --- title: Chat Window description: Usage and prop defaults for the chat-style editor preset. --- # Chat Window Chat composer style preset with send and action controls. ## Usage ```tsx import { ChatWindowEditor } from '@lyfie/luthor'; import '@lyfie/luthor/styles.css'; export function App() { return ( console.log(jsonb)} submitOnEnter allowShiftEnter /> ); } ``` ## Props `ChatWindowEditorProps` inherits `ExtensiveEditorProps` except `featureFlags` and `isToolbarEnabled`. - `onSend`: `undefined (default) | (payload: { jsonb: string }) => void` - `submitOnEnter`: `true (default) | false` - `allowShiftEnter`: `true (default) | false` - `showVoiceButton`: `false (default) | true` - `showImageButton`: `true (default) | false` - `showSendButton`: `true (default) | false` ## Behavior - Toolbar is disabled by preset defaults - Visual mode only - Enter-to-send behavior is configurable --- ## FILE: luthor/presets/email-compose-editor.md ## URL: https://www.luthor.fyi/docs/luthor/presets/email-compose-editor/ --- --- title: Email Compose description: Usage and prop defaults for the email compose preset. --- # Email Compose Email composer preset with To/Cc/Bcc/Subject shell. ## Usage ```tsx import { EmailComposeEditor } from '@lyfie/luthor'; import '@lyfie/luthor/styles.css'; export function App() { return ; } ``` ## Props `EmailComposeEditorProps` inherits `ExtensiveEditorProps` except `featureFlags`. - `showTo`: `true (default) | false` - `showCc`: `false (default) | true` - `showBcc`: `false (default) | true` - `showSubject`: `true (default) | false` ## Behavior Preset applies email-friendly feature defaults and renders compose header fields. --- ## FILE: luthor/presets/extensive-editor.md ## URL: https://www.luthor.fyi/docs/luthor/presets/extensive-editor/ --- --- title: Extensive description: Full-feature preset and core prop reference. --- # Extensive `ExtensiveEditor` is the base full-feature preset editor. ## Usage ```tsx import { ExtensiveEditor } from '@lyfie/luthor'; import '@lyfie/luthor/styles.css'; export function App() { return ; } ``` ## Core props - `initialTheme`: `'light' (default) | 'dark'` - `showDefaultContent`: `true (default) | false` - `placeholder`: `'Write anything...' (default) | string | { visual?: string; jsonb?: string }` - `initialMode`: `'visual' (default) | 'jsonb'` - `availableModes`: `['visual', 'jsonb'] (default) | ('visual' | 'jsonb')[]` - `toolbarPosition`: `'top' (default) | 'bottom'` - `toolbarAlignment`: `'left' (default) | 'center' | 'right'` - `isToolbarEnabled`: `true (default) | false` - `minimumDefaultLineHeight`: `1.5 (default) | string | number` - `scaleByRatio`: `false (default) | true` - `syncHeadingOptionsWithCommands`: `true (default) | false` - `commandPaletteShortcutOnly`: `false (default) | true` - `isCopyAllowed`: `true (default) | false` - `syntaxHighlighting`: `'auto' | 'disabled'` | extension default behavior if omitted ## Ref API - `injectJSONB(content: string): void` - `getJSONB(): string` ## Notes This is the base preset that other presets build on. --- ## FILE: luthor/presets/headless-editor-preset.md ## URL: https://www.luthor.fyi/docs/luthor/presets/headless-editor-preset/ --- --- title: Headless Preset description: Reference preset showing direct headless composition. --- # Headless Preset Small reference preset demonstrating direct headless composition. ## Usage ```tsx import { HeadlessEditorPreset } from '@lyfie/luthor'; import '@lyfie/luthor/styles.css'; export function App() { return ; } ``` ## Props - `className`: `undefined (default) | string` - `placeholder`: `'Start writing...' (default) | string` ## Behavior Uses a minimal extension set (`richText`, `history`, `bold`, `italic`, `underline`, `list`) and a lightweight toolbar. --- ## FILE: luthor/presets/md-text-editor.md ## URL: https://www.luthor.fyi/docs/luthor/presets/md-text-editor/ --- --- title: Markdown description: Visual and markdown mode preset with mode-switch behavior. --- # Markdown Preset that switches between visual and markdown editing. ## Usage ```tsx import { MDTextEditor } from '@lyfie/luthor'; import '@lyfie/luthor/styles.css'; export function App() { return ; } ``` ## Props `MDTextEditorProps` inherits `ExtensiveEditorProps` except `availableModes` and `initialMode`. - `initialMode`: `'visual' (default) | 'markdown'` ## Behavior - Uses markdown/jsonb conversion when switching modes - Renders source textarea in markdown mode --- ## FILE: luthor/presets/notes-editor.md ## URL: https://www.luthor.fyi/docs/luthor/presets/notes-editor/ --- --- title: Notes description: Notes-style preset with title and action controls. --- # Notes Notes-style preset with title and action controls. ## Usage ```tsx import { NotesEditor } from '@lyfie/luthor'; import '@lyfie/luthor/styles.css'; export function App() { return ( console.log(value)} onPin={() => console.log('pin')} onArchive={() => console.log('archive')} /> ); } ``` ## Props `NotesEditorProps` inherits `ExtensiveEditorProps` except `featureFlags`. - `showTitle`: `true (default) | false` - `title`: `'' (default) | string` - `onTitleChange`: `undefined (default) | (value: string) => void` - `showActions`: `true (default) | false` - `onPin`: `undefined (default) | () => void` - `onArchive`: `undefined (default) | () => void` - `onColorChange`: `undefined (default) | (color: string) => void` - `colorOptions`: `['#fef3c7', '#dbeafe', '#dcfce7'] (default) | readonly string[]` ## Behavior Toolbar is disabled by preset default and feature set is tuned for lightweight note taking. --- ## FILE: luthor/presets/notion-like-editor.md ## URL: https://www.luthor.fyi/docs/luthor/presets/notion-like-editor/ --- --- title: Notion Like description: Slash-first preset with draggable and command-focused defaults. --- # Notion Like Slash-first preset with draggable-focused defaults. ## Usage ```tsx import { NotionLikeEditor } from '@lyfie/luthor'; import '@lyfie/luthor/styles.css'; export function App() { return ; } ``` ## Props `NotionLikeEditorProps` inherits `ExtensiveEditorProps` except `featureFlags` and `isToolbarEnabled`, then re-adds both. - `slashVisibility`: `undefined (default) | SlashCommandVisibility` - `isDraggableEnabled`: `true (default) | false` - `featureFlags`: `undefined (default) | FeatureFlagOverrides` - `isToolbarEnabled`: `false (default) | true` ## Behavior Defaults enable slash commands, draggable blocks, and command palette while keeping toolbar hidden. --- ## FILE: luthor/presets/rich-text-box-editor.md ## URL: https://www.luthor.fyi/docs/luthor/presets/rich-text-box-editor/ --- --- title: Rich Text description: Compact rich text preset and prop defaults. --- # Rich Text Compact rich text preset for focused editing. ## Usage ```tsx import { RichTextBoxEditor } from '@lyfie/luthor'; import '@lyfie/luthor/styles.css'; export function App() { return ; } ``` ## Props `RichTextBoxEditorProps` inherits `ExtensiveEditorProps` except `featureFlags`. - `featureFlags`: `undefined (default) | FeatureFlagOverrides` - `compactToolbar`: `false (default) | true` ## Behavior Default feature flags enable core formatting and disable heavier media/embed features unless re-enabled. --- ## FILE: luthor/presets/simple-text-editor.md ## URL: https://www.luthor.fyi/docs/luthor/presets/simple-text-editor/ --- --- title: Simple Text description: Minimal text-focused preset with constrained editing modes. --- # Simple Text Minimal plain-text style preset built on top of `ExtensiveEditor`. ## Usage ```tsx import { SimpleTextEditor } from '@lyfie/luthor'; import '@lyfie/luthor/styles.css'; export function App() { return ; } ``` ## Props `SimpleTextEditorProps` inherits `ExtensiveEditorProps` except `featureFlags`, `availableModes`, `initialMode`, and `toolbarVisibility`. - `hideToolbarByDefault`: `true (default) | false` ## Behavior - Forces visual-only mode - Disables most rich features by preset defaults