API Reference

Core Function

quikdown(markdown, options?)

Converts markdown text to HTML.

Parameters

Options

Returns

string - The converted HTML

Example

import quikdown from 'quikdown';

const markdown = '# Hello World\n\nThis is **bold** text.';
const html = quikdown(markdown);
console.log(html);
// <h1 class="quikdown-h1">Hello World</h1><p>This is <strong class="quikdown-strong">bold</strong> text.</p>

Configuration Methods

quikdown.configure(options)

Creates a pre-configured parser function with default options.

Parameters

Returns

function - A configured parser function

Example

const myParser = quikdown.configure({
  inline_styles: true,
  fence_plugin: myPlugin
});

// Use the configured parser
const html = myParser('# Heading');
// No need to pass options each time

Style Methods

quikdown.emitStyles(prefix?, theme?)

Returns CSS styles for quikdown HTML output when not using inline styles.

Parameters

• prefix (string, optional) - CSS class prefix. Default: 'quikdown-'
• theme (string, optional) - Theme name: 'light' (default) or 'dark'

Returns

string - CSS stylesheet content with theme-appropriate colors

Example

// Generate light theme CSS
const lightStyles = quikdown.emitStyles('quikdown-', 'light');

// Generate dark theme CSS  
const darkStyles = quikdown.emitStyles('quikdown-', 'dark');

// Add to your page
const styleElement = document.createElement('style');
styleElement.textContent = lightStyles;
document.head.appendChild(styleElement);

// Or use pre-generated theme files
// dist/quikdown.light.css - Light theme with explicit colors
// dist/quikdown.dark.css - Dark theme with auto dark mode support

Theme Features

• Container-based scoping: Use .quikdown-light or .quikdown-dark containers
• Explicit colors: Both themes specify text colors for robustness
• Auto dark mode: Dark CSS includes .quikdown-auto for system preferences
• No conflicts: Multiple themes can coexist on the same page

Generated CSS Classes

.quikdown-h1 { margin-top: 0.5em; margin-bottom: 0.3em }
.quikdown-h2 { margin-top: 0.5em; margin-bottom: 0.3em }
.quikdown-h3 { margin-top: 0.5em; margin-bottom: 0.3em }
.quikdown-h4 { margin-top: 0.5em; margin-bottom: 0.3em }
.quikdown-h5 { margin-top: 0.5em; margin-bottom: 0.3em }
.quikdown-h6 { margin-top: 0.5em; margin-bottom: 0.3em }
.quikdown-pre { background: #f4f4f4; padding: 10px; border-radius: 4px; overflow-x: auto }
.quikdown-code { background: #f0f0f0; padding: 2px 4px; border-radius: 3px }
.quikdown-blockquote { border-left: 4px solid #ddd; margin-left: 0; padding-left: 1em; color: #666 }
.quikdown-table { border-collapse: collapse; width: 100%; margin: 1em 0 }
.quikdown-th { border: 1px solid #ddd; padding: 8px; background-color: #f2f2f2; font-weight: bold }
.quikdown-td { border: 1px solid #ddd; padding: 8px; text-align: left }
.quikdown-hr { border: none; border-top: 1px solid #ddd; margin: 1em 0 }
.quikdown-img { max-width: 100%; height: auto }
.quikdown-a { color: #0066cc; text-decoration: underline }
.quikdown-strong { font-weight: bold }
.quikdown-em { font-style: italic }
.quikdown-del { text-decoration: line-through }
.quikdown-ul { margin: 0.5em 0; padding-left: 2em }
.quikdown-ol { margin: 0.5em 0; padding-left: 2em }
.quikdown-li { margin: 0.25em 0 }

Properties

quikdown.version

The version of quikdown.

Type

string

Example

console.log(quikdown.version); // "1.2.3"

Fence Plugin API

Plugin Object Structure

interface FencePlugin {
  render: (content: string, language: string) => string | undefined;
  reverse?: (element: HTMLElement) => { fence: string; lang: string; content: string } | null;
}

render Parameters

render Returns

• string - HTML to render
• undefined - Use default code block rendering

reverse (optional)

Used by quikdown_bd to convert plugin-rendered HTML back to fenced code blocks.

Example

const syntaxHighlightPlugin = {
  render: (content, language) => {
    if (language && hljs.getLanguage(language)) {
      const highlighted = hljs.highlight(content, { language }).value;
      return `<pre class="hljs"><code class="language-${language}">${highlighted}</code></pre>`;
    }
    // Return undefined to use default rendering
    return undefined;
  }
};

const html = quikdown(markdown, {
  fence_plugin: syntaxHighlightPlugin
});

Plugin Examples

Mermaid Diagrams

const mermaidPlugin = {
  render: (content, language) => {
    if (language === 'mermaid') {
      const id = 'mermaid-' + Math.random().toString(36).substr(2, 9);
      // Render asynchronously after DOM insertion
      setTimeout(() => {
        mermaid.render(id + '-svg', content).then(result => {
          document.getElementById(id).innerHTML = result.svg;
        });
      }, 0);
      return `<div id="${id}" class="mermaid-diagram">Loading...</div>`;
    }
  }
};

Math Rendering

const mathPlugin = {
  render: (content, language) => {
    if (language === 'math' || language === 'latex') {
      return katex.renderToString(content, {
        throwOnError: false,
        displayMode: true
      });
    }
  }
};

Custom Components

const componentPlugin = {
  render: (content, language) => {
    if (language === 'component') {
      try {
        const config = JSON.parse(content);
        return renderComponent(config);
      } catch (e) {
        return `<div class="error">Invalid component: ${e.message}</div>`;
      }
    }
  }
};

Trusted HTML

const trustedHtmlPlugin = {
  render: (content, language) => {
    // Only allow from trusted sources!
    if (language === 'html-render' && isTrustedSource()) {
      return content; // Raw HTML - be careful!
    }
  }
};

Options Deep Dive

bidirectional Option

Enables preservation of original markdown syntax for HTML→Markdown conversion.

bidirectional: false (Default)

Standard HTML output without preservation attributes:

quikdown('**bold**', { bidirectional: false });
// Output: <strong class="quikdown-strong">bold</strong>

bidirectional: true

Adds data-qd attributes to preserve original markdown:

quikdown('**bold**', { bidirectional: true });
// Output: <strong class="quikdown-strong" data-qd="**">bold</strong>

Use when:

• Building a markdown editor
• Need HTML→Markdown conversion
• Want to preserve exact markdown syntax
• Using with quikdown_bd module

lazy_linefeeds Option

Enables lazy line break handling where single newlines become <br> tags.

lazy_linefeeds: false (Default)

Standard markdown behavior - only double spaces before newline create breaks:

quikdown('Line 1\nLine 2');
// Output: <p>Line 1\nLine 2</p>

quikdown('Line 1  \nLine 2');  // Two spaces before \n
// Output: <p>Line 1<br class="quikdown-br">Line 2</p>

lazy_linefeeds: true

Single newlines automatically become line breaks:

quikdown('Line 1\nLine 2', { lazy_linefeeds: true });
// Output: <p>Line 1<br class="quikdown-br">Line 2</p>

• Chat applications
• LLM/AI output formatting
• User-generated content where users expect Enter to create a new line
• Converting informal text to HTML

Behavior:

• Single \n → <br> tag
• Double \n\n → Paragraph break (unchanged)
• Code blocks preserve newlines (no <br> conversion)
• Lists maintain proper structure

inline_styles Option

Controls how styling is applied to generated HTML.

inline_styles: false (Default)

Generates HTML with CSS classes:

quikdown('**bold**', { inline_styles: false });
// Output: <strong class="quikdown-strong">bold</strong>

Use when:

• You have a stylesheet
• You want consistent styling
• You need to override styles
• Page has multiple quikdown instances

inline_styles: true

Generates HTML with inline styles:

quikdown('**bold**', { inline_styles: true });
// Output: <strong style="font-weight: bold">bold</strong>

Use when:

• Rendering in emails
• No stylesheet access
• Isolated components
• Quick prototypes

Supported Markdown

Block Elements

Inline Elements

Element	Syntax	Example
Bold	** or __	**bold**
Italic	* or _	*italic*
Strikethrough	~~	~~strike~~
Code	Single backtick	` code | | Link | text | Google | | Image | | | | Line Break | Two spaces + newline | Line \nBreak | ## Error Handling quikdown is designed to be forgiving and never throw errors: | Input | Result | |-------|--------| | null | "" (empty string) | | undefined | "" (empty string) | | Non-string | "" (empty string) | | Malformed markdown | Best-effort HTML | | Unclosed fence | Treated as regular text | | Invalid table | Rendered as plain text | ## Performance Tips ### 1. Reuse Configured Parsers §CB17§ ### 2. Cache Styles §CB18§ ### 3. Batch Small Documents §CB19§ ## Browser Compatibility | Browser | Version | Notes | |---------|---------|-------| | Chrome | 61+ | Full support | | Firefox | 60+ | Full support | | Safari | 12+ | Full support | | Edge | 79+ | Full support | | IE | ❌ | Not supported | ## Node.js Compatibility | Version | Support | |---------|---------| | 14.x | ✅ Full | | 16.x | ✅ Full | | 18.x | ✅ Full | | 20.x | ✅ Full | ## Module Comparison | Feature | quikdown | quikdownbd | |---------|------------|---------------| | Markdown to HTML | ✅ Yes | ✅ Yes | | HTML to Markdown | ❌ No | ✅ Yes | | Size (minified) | 9.3KB | 14.1KB | | toMarkdown() method | ❌ No | ✅ Yes | | data-qd attributes | ❌ No | ✅ Yes | | Use case | Standard parsing | WYSIWYG editors | ## Bidirectional API **⚠️ Important:** These methods are only available in the quikdownbd module, NOT in regular quikdown. ### quikdownbd(markdown, options?) Converts markdown to HTML with source tracking for bidirectional conversion. Only available when using quikdownbd. #### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | markdown | string | Yes | The markdown text to convert | | options | object | No | Configuration options | #### Options | Option | Type | Default | Description | |--------|------|---------|-------------| | inlinestyles | boolean | false | Use inline styles instead of CSS classes | | fenceplugin | object | undefined | Custom handler for fenced code blocks (object with .render method) | | bidirectional | boolean | true | Add data-qd attributes for source tracking | | lazylinefeeds | boolean | false | Single newlines become tags (v1.0.5+) | #### Returns string - HTML with data-qd attributes for source tracking #### Example §CB20§ ### quikdownbd.toMarkdown(htmlOrElement) Converts HTML back to Markdown using DOM walking and data-qd attributes. #### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | htmlOrElement | string \	HTMLElement | Yes | HTML string or DOM element to convert | #### Returns string - The reconstructed Markdown #### Example §CB21§ #### Browser Requirement toMarkdown requires a DOM environment. In Node.js, use a library like jsdom: §CB22§ ### quikdownbd.configure(options) Creates a pre-configured bidirectional parser with default options. #### Example §CB23§ ### quikdownbd.emitStyles(prefix?, theme?) Returns CSS styles for bidirectional HTML output (currently returns empty string, reserved for future use). ### quikdownbd.version Returns the version string of the quikdown_bd module. ## Module Formats quikdown is distributed in multiple formats: ### Core Module | Format | File | Usage | |--------|------|-------| | UMD | dist/quikdown.umd.js | Browser script tag | | UMD minified | dist/quikdown.umd.min.js | Production browser | | ESM | dist/quikdown.esm.js | ES6 imports | | ESM minified | dist/quikdown.esm.min.js | Production ES6 | | CommonJS | dist/quikdown.cjs | Node.js require() | ### Bidirectional Module | Format | File | Usage | |--------|------|-------| | UMD | dist/quikdownbd.umd.js | Browser script tag | | UMD minified | dist/quikdownbd.umd.min.js | Production browser | | ESM | dist/quikdownbd.esm.js | ES6 imports | | ESM minified | dist/quikdownbd.esm.min.js | Production ES6 | | CommonJS | dist/quikdownbd.cjs | Node.js require() | ## AST Libraries For structured data output, quikdown provides AST (Abstract Syntax Tree) libraries: ### quikdownast(markdown, options?) Parses markdown into an AST object. §CB24§ ### quikdownjson(markdown, options?) Converts markdown to a JSON string. §CB25§ ### quikdownyaml(markdown, options?) Converts markdown to a YAML string. §CB26§ ### quikdownasthtml(input, options?) Renders AST, JSON, YAML, or markdown to HTML. §CB27§ See [AST Documentation](quikdown-ast.md) for complete node type reference. ### AST Module Formats | Format | File | Usage | |--------|------|-------| | ESM | dist/quikdownast.esm.js | ES6 imports | | UMD | dist/quikdownast.umd.min.js | Browser | | CommonJS | dist/quikdownast.cjs | Node.js | Similar formats available for quikdownjson, quikdownyaml, and quikdownasthtml`.

TypeScript

TypeScript definitions are included for all modules:

declare module 'quikdown' {
  interface FencePlugin {
    render: (content: string, language: string) => string | undefined;
    reverse?: (element: HTMLElement) => {
      fence: string;
      lang: string;
      content: string;
    } | null;
  }

  interface QuikdownOptions {
    inline_styles?: boolean;
    fence_plugin?: FencePlugin;
    bidirectional?: boolean;
    lazy_linefeeds?: boolean;
    allow_unsafe_urls?: boolean;
  }
  
  interface QuikdownFunction {
    (markdown: string, options?: QuikdownOptions): string;
    configure(options: QuikdownOptions): (markdown: string) => string;
    emitStyles(prefix?: string, theme?: 'light' | 'dark'): string;
    version: string;
  }
  
  const quikdown: QuikdownFunction;
  export default quikdown;
}