quikdown 1.0.3 → 1.0.5

package/README.md

@@ -4,459 +4,229 @@
 [![npm version](https://img.shields.io/npm/v/quikdown.svg)](https://www.npmjs.com/package/quikdown)
 [![Coverage Status](https://img.shields.io/badge/coverage-99%25-blue.svg)](https://github.com/deftio/quikdown)
 [![License: BSD-2-Clause](https://img.shields.io/badge/License-BSD%202--Clause-blue.svg)](https://opensource.org/licenses/BSD-2-Clause)
-[![Bundle Size](https://img.shields.io/badge/minified-<10KB-blue.svg)](https://github.com/deftio/quikdown/tree/main/dist)
 
-A lightweight, fast markdown parser with built-in XSS protection. Quikdown works in both browser and Node.js environments.  Via its fenced plug-in support it can support highlighted code blocks, diagrams, and other custom fenced content.
+Quikdown is a small, secure markdown parser with bidirectional conversion. Zero dependencies, XSS protection built-in, extensible via plugins for code highlighting and diagrams, and works in browser and Node.js.
 
-🚀 **[Try Live Demo](https://deftio.github.io/quikdown/examples/quikdown-live.html)** - Interactive markdown editor with real-time preview  
-📚 **[View Examples](examples/)** - Additional demos and test pages  
-📖 **[Read Documentation](docs/)** - Architecture, security, API reference, and plugin guide
+For small and fast projects quikdown includes built-in inline styles for a "batteries included" rendering experience, but these can be overridden with themed css (see light and dark examples).
+
+- **quikdown.js** (8.7KB) - Markdown to HTML Parser
+- **quikdown_bd.js** (13KB) - Bidirectional (HTML ↔ Markdown) Parser
+- **quikdown_edit.js** (36KB) - Drop-in editor component (HTML ↔ Markdown) with md/split/html views
+
+🚀 **[Live Demo](https://deftio.github.io/quikdown/examples/quikdown-live.html)** | **[Editor Demo](https://deftio.github.io/quikdown/examples/qde/)** | **[Documentation](docs/)**
+
+📍 **Quick Links:** [Installation](#installation) • [Quick Start](#quick-start) • [API](#api-reference) • [TypeScript](#typescript-support) • [Plugins](#fence-plugins) • [Examples](examples/)
 
 ## Features
 
-- 🚀 **Lightweight** - Under 10KB minified
-- 🔒 **Secure by default** - Built-in XSS protection with URL sanitization
-- 🎨 **Flexible styling** - Inline styles or CSS classes including light and dark mode generation, custom themes
-- 🔌 **Plugin system** - Extensible fence block handlers
 - 📦 **Zero dependencies** - No external libraries required
 - 🌐 **Universal** - Works in browsers and Node.js
+- 🚀 **Lightweight** - 8.7KB (core), 13KB (bidirectional), 36KB (editor)
+- 🔒 **Secure by default** - Built-in XSS protection with URL sanitization
+- 🎨 **Flexible styling** - Inline styles or CSS classes with theme support
+- 🔌 **Plugin system** - Extensible fence block handlers
 - ⚡ **Fast** - Optimized regex-based parsing
-- 📝 **CommonMark subset** - Supports essential markdown features
+- 📝 **CommonMark subset** - Essential markdown features
 - ✅ **Task Lists** - GitHub-style checkboxes
 - 🔗 **Autolinks** - Automatic URL detection
+- 🔄 **Bidirectional** - Convert HTML back to Markdown (quikdown_bd)
+- 💬 **Lazy linefeeds** - Single newlines become line breaks (configurable)
+- 📱 **Editor component** - Drop-in markdown editor with live preview
 
 ## Installation
 
+Quikdown is available via [NPM](https://www.npmjs.com/package/quikdown) and related [unpkg](https://unpkg.com/quikdown) and [jsdelivr](https://cdn.jsdelivr.net/npm/quikdown)
+
+### NPM package
 ```bash
 npm install quikdown
 ```
 
-Or via CDN:
+### CDN using UNPKG  
 
-**ES Modules (recommended for modern applications):**
+**CDN (ES Modules):**
 ```html
 <script type="module">
   import quikdown from 'https://unpkg.com/quikdown/dist/quikdown.esm.min.js';
-  
-  const html = quikdown('# Hello World');
-  document.body.innerHTML = html;
+  document.body.innerHTML = quikdown('# Hello World');
 </script>
 ```
 
-**UMD (for legacy browser support):**
+**CDN (UMD):**
 ```html
 <script src="https://unpkg.com/quikdown/dist/quikdown.umd.min.js"></script>
 <script>
-  // Available as window.quikdown
-  const html = quikdown('# Hello World');
+  document.body.innerHTML = quikdown('# Hello World');
 </script>
 ```
 
-> **Production tip:** Pin to a specific version for stability (e.g., `https://unpkg.com/quikdown@1.0.3/dist/quikdown.esm.min.js`)
-
 ## Quick Start
 
-### Basic Usage
-
-```javascript
-import quikdown from 'quikdown';
-
-const markdown = '# Hello World\n\nThis is **bold** text.';
-const html = quikdown(markdown);
-console.log(html);
-// Output: <h1>Hello World</h1><p>This is <strong>bold</strong> text.</p>
-```
+Quikdown is built in 3 versions. The smallest (quikdown) provides markdown to html conversion only.  The next (quikdown_bd) provides markdown to html and html to markdown support.  The lightweight editor quikdown_edit allows a bidirectional editor with lazy loading for common fences such as codeblocks, svg, and mermaid diagrams is also provided.
 
-### With Options
+### Markdown → HTML (quikdown.js)
 
 ```javascript
-const html = quikdown(markdown, {
-    inline_styles: true,  // Use inline styles instead of classes
-    fence_plugin: myFenceHandler  // Custom code fence handler
-});
-```
-
-### TypeScript Support
-
-quikdown includes TypeScript definitions for better IDE support and type safety:
-
-```typescript
-import quikdown, { QuikdownOptions } from 'quikdown';
-
-const options: QuikdownOptions = {
-    inline_styles: true,
-    fence_plugin: (content: string, language: string) => {
-        return `<pre class="hljs ${language}">${content}</pre>`;
-    }
-};
-
-const html: string = quikdown(markdown, options);
-```
-
-## Supported Markdown
-
-quikdown supports a practical subset of CommonMark:
-
-### Text Formatting
-- **Bold**: `**text**` or `__text__`
-- *Italic*: `*text*` or `_text_`
-- ~~Strikethrough~~: `~~text~~`
-- `Code`: `` `code` ``
-
-### Headings
-```markdown
-# H1 Heading
-## H2 Heading
-### H3 Heading
-#### H4 Heading
-##### H5 Heading
-###### H6 Heading
-```
-
-### Lists
+// Basic conversion
+const html = quikdown('# Hello World',
+    {inline_styles: true}  // Use inline styles,  more options in API docs
+);
 
-Unordered:
-```markdown
-- Item 1
-- Item 2
-  - Nested item
-* Also works with asterisks
-```
-
-Ordered:
-```markdown
-1. First item
-2. Second item
-   1. Nested item
-```
+document.body.innerHTML = html;
 
-Task Lists:
-```markdown
-- [x] Completed task
-- [ ] Pending task
-- [ ] Another todo
 ```
 
-### Links and Images
-```markdown
-[Link text](https://example.com)
-![Alt text](image.jpg)
-
-// Autolinks - URLs are automatically linked
-Visit https://github.com for more info
-```
+### Bidirectional Markdown ↔  HTML (quikdown_bd.js)
 
-### Code Blocks
-````markdown
 ```javascript
-console.log('Hello, world!');
-```
+// Convert with source tracking
+const htmlString = quikdown_bd(markdown, options);
 
-// Also supports ~~~ fences
-~~~python
-print("Hello, world!")
-~~~
-````
-
-### Tables
-```markdown
-| Header 1 | Header 2 |
-|----------|----------|
-| Cell 1   | Cell 2   |
-| Cell 3   | Cell 4   |
+// Convert HTML back to Markdown
+const markdown = quikdown_bd.toMarkdown(htmlString);
 ```
 
-### Other Elements
-- **Blockquotes**: `> Quote text`
-- **Horizontal rules**: `---` or `***` or `___`
-- **Line breaks**: Two spaces at end of line or `<br>`
+Note: quikdown does not provide a *generic* html to markdown conversion but uses special tags and limited DOM parsing for HTML to markdown conversion.  Standard markdown components such as headings, text styles, tables, quotes, etc are supported.  For custom fences quikdown relies on its tag system or 3rd party handlers to provide reverse (html to md) conversion.
 
-## Configuration Options
-
-### `inline_styles` (boolean)
-When `true`, uses inline styles for formatting. When `false`, uses CSS classes.
+### Editor (quikdown_edit.js)
 
 ```javascript
-// With inline_styles: true
-quikdown('**bold**', { inline_styles: true });
-// Output: <strong style="font-weight: bold;">bold</strong>
+const editor = new QuikdownEditor('#container', {
+  mode: 'split',           // 'source', 'split', 'preview' 
+  theme: 'auto',           // 'light', 'dark', 'auto'
+  plugins: { highlightjs: true, mermaid: true } // built-in fence handlers, see API docs for custom plugins
+});
 
-// With inline_styles: false (default)
-quikdown('**bold**', { inline_styles: false });
-// Output: <strong>bold</strong>
+editor.setMarkdown('# Content  \nTo be quik or not to be.');  // provide default content
+const content = editor.getMarkdown(); // get source content, see APIs for getting / setting HTML 
 ```
 
-### `fence_plugin` (function)
-Custom handler for fenced code blocks. Useful for syntax highlighting or diagrams.
+## Other Configuration Options
+quikdown supports built-in styles for a "batteries included" experience or you can bring your own CSS themes.  Example css files are provided for basic light and dark themes to get started.
 
 ```javascript
-function fencePlugin(code, language) {
-    if (language === 'mermaid') {
-        return `<div class="mermaid">${code}</div>`;
-    }
-    // Return undefined to use default handling
-}
-
-const html = quikdown(markdown, { fence_plugin: fencePlugin });
+const html = quikdown(markdown, {
+  lazy_linefeeds: true,    // Single newlines become <br>
+  inline_styles: false,    // Use class based CSS instead of inline styles
+  fence_plugin: myHandler  // Custom code block processor
+});
 ```
 
-## Plugin System
-
-For a complete plugin development guide, see [docs/plugin-guide.md](docs/plugin-guide.md)
-
-### Creating a Fence Plugin
-
-Fence plugins allow you to customize how code blocks are rendered:
+### Styling Options
 
+**Inline styles:** All formatting uses inline CSS
 ```javascript
-function myFencePlugin(code, language) {
-    // Handle specific languages
-    if (language === 'graph') {
-        return renderGraph(code);
-    }
-    
-    // Add syntax highlighting
-    if (language && hljs.getLanguage(language)) {
-        const highlighted = hljs.highlight(code, { language }).value;
-        return `<pre><code class="language-${language}">${highlighted}</code></pre>`;
-    }
-    
-    // Return undefined for default handling
-    return undefined;
-}
+quikdown('**bold**', { inline_styles: true });
+// <strong style="font-weight: bold;">bold</strong>
 ```
 
-### Example: Mermaid Diagrams
-
+**Class-based styling:** Uses CSS classes (default)
 ```javascript
-function mermaidPlugin(code, language) {
-    if (language === 'mermaid') {
-        const id = 'mermaid-' + Math.random().toString(36).substr(2, 9);
-        // Render with mermaid.js after DOM update
-        setTimeout(() => {
-            mermaid.render(id + '-svg', code).then(result => {
-                document.getElementById(id).innerHTML = result.svg;
-            });
-        }, 0);
-        return `<div id="${id}" class="mermaid">Loading diagram...</div>`;
-    }
-}
-
-const html = quikdown(markdownWithMermaid, { 
-    fence_plugin: mermaidPlugin 
-});
+quikdown('**bold**');
+// <strong>bold</strong>
+// Requires CSS: .quikdown strong { font-weight: bold; }
+// see included dist/quikdown.light.css or quikdown.dark.css
 ```
 
-## Security
-
-For detailed security information, see [docs/security.md](docs/security.md)
+### Fence Plugins
 
-quikdown includes built-in XSS protection:
+Quikdown provides a callback for all fenced text such as code blocks, math, svg etc.
 
-- All HTML tags in markdown are escaped by default
-- Attributes are sanitized
-- JavaScript URLs are blocked
-- Only safe markdown constructs are converted to HTML
+Handle code blocks with custom languages:
 
 ```javascript
-const unsafe = '<script>alert("XSS")</script> **bold**';
-const safe = quikdown(unsafe);
-// Output: &lt;script&gt;alert("XSS")&lt;/script&gt; <strong>bold</strong>
-```
-
-## Quikdown Lexer Version
-An experimental lexer-based implementation is available for testing. See [docs/lexer-implementation.md](docs/lexer-implementation.md) for details.
-
-
-## API Reference
-
-For complete API documentation, see [docs/api-reference.md](docs/api-reference.md)
-
-### `quikdown(markdown, options?)`
+function fencePlugin(code, language) {
+  if (language === 'mermaid') {
+    // Process with mermaid library and return rendered diagram
+    const id = 'mermaid-' + Math.random().toString(36).substr(2, 9);
+    setTimeout(() => mermaid.render(id + '-svg', code).then(result => {
+      document.getElementById(id).innerHTML = result.svg;
+    }), 0);
+    return `<div id="${id}" class="mermaid">Loading diagram...</div>`;
+  }
+  return `<pre>${code}</pre>`;
+  // Return undefined for default handling
+}
 
-Main function to convert markdown to HTML.
+const html = quikdown(markdown, { fence_plugin: fencePlugin });
+```
 
-**Parameters:**
-- `markdown` (string): The markdown text to convert
-- `options` (object, optional):
-  - `inline_styles` (boolean): Use inline styles instead of classes
-  - `fence_plugin` (function): Custom fence block handler
 
-**Returns:** HTML string
+## TypeScript Support
 
-### `quikdown.configure(options)`
+quikdown includes TypeScript definitions for better IDE support and type safety:
 
-Creates a configured instance of the parser.
+``` javascript
+import quikdown, { QuikdownOptions } from 'quikdown';
 
-```javascript
-const myParser = quikdown.configure({
+const options: QuikdownOptions = {
     inline_styles: true,
-    fence_plugin: myPlugin
-});
-
-// Use the configured parser
-const html = myParser(markdown);
-```
-
-### `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' or 'dark' (default: 'light')
-
-```javascript
-// Get light theme CSS
-const lightStyles = quikdown.emitStyles();
+    fence_plugin: (content: string, language: string) => {
+        return `<pre class="hljs ${language}">${content}</pre>`;
+    }
+};
 
-// Get dark theme CSS  
-const darkStyles = quikdown.emitStyles('quikdown-', 'dark');
+const html: string = quikdown(markdown, options);
 
-// Add to your stylesheet or <style> tag
 ```
 
-## Theming
-
-QuikDown supports flexible theming through container-based CSS scoping:
+## Supported Markdown
 
-### Using Pre-built Themes
+**Text formatting:** `**bold**`, `*italic*`, `~~strikethrough~~`, `` `code` ``
 
-```html
-<!-- Load theme CSS files -->
-<link rel="stylesheet" href="quikdown.light.css">
-<link rel="stylesheet" href="quikdown.dark.css">
-
-<!-- Apply themes via container classes -->
-<div class="quikdown-light">
-  <!-- Light themed content -->
-</div>
-
-<div class="quikdown-dark">
-  <!-- Dark themed content -->
-</div>
-```
+**Headings:** `# H1` through `###### H6`
 
-### Theme Architecture
+**Lists:**
 
-- **Structural styles**: Shared across all themes (margins, padding, font-sizes)
-- **Theme colors**: Scoped to container classes (`.quikdown-light`, `.quikdown-dark`)
-- **No conflicts**: Multiple themes can coexist on the same page
-- **No default theme**: Without a container class, only structural styles apply
+- Unordered lists  
+1. Ordered lists  
+- [x] Task lists  
 
-### Inline Styles
+**Links:** `[text](url)` and automatic URL detection
 
-For a batteries-included approach without CSS files:
+**Code blocks:**  
 
 ```javascript
-// Use inline styles (always light theme currently)
-const html = quikdown(markdown, { inline_styles: true });
+console.log('syntax highlighting support via plugins');
 ```
 
-## Browser Usage
-
-### ES Modules (Recommended)
+**Tables, blockquotes, horizontal rules** - See [documentation](docs/) for complete syntax reference
 
-```html
-<!DOCTYPE html>
-<html>
-<head>
-    <meta charset="UTF-8">
-</head>
-<body>
-    <div id="output"></div>
-    <script type="module">
-        import quikdown from 'https://unpkg.com/quikdown/dist/quikdown.esm.min.js';
-        
-        const markdown = '# Hello quikdown!\n\nSupports **bold** and *italic* text.';
-        const html = quikdown(markdown, { inline_styles: true });
-        document.getElementById('output').innerHTML = html;
-    </script>
-</body>
-</html>
-```
+## API Reference
 
-### UMD Script Tag (Legacy)
+For complete API documentation, see [docs/api-reference.md](docs/api-reference.md)
 
-```html
-<!DOCTYPE html>
-<html>
-<head>
-    <script src="https://unpkg.com/quikdown/dist/quikdown.umd.min.js"></script>
-</head>
-<body>
-    <div id="output"></div>
-    <script>
-        const markdown = '# Hello quikdown!';
-        const html = quikdown(markdown, { inline_styles: true });
-        document.getElementById('output').innerHTML = html;
-    </script>
-</body>
-</html>
-```
+## Security
 
-## Node.js Usage
+All HTML is escaped by default. Only safe markdown constructs become HTML:
 
 ```javascript
-const quikdown = require('quikdown');
-
-const markdown = '# Server-side Markdown';
-const html = quikdown(markdown);
-
-// Use in Express, etc.
-res.send(html);
+const unsafe = '<script>alert("XSS")</script> **bold**';
+const safe = quikdown(unsafe);
+// &lt;script&gt;alert("XSS")&lt;/script&gt; <strong>bold</strong>
 ```
 
-## Performance
-
-quikdown is optimized for speed:
+## Framework Integration
 
-- Single-pass regex parsing
-- Minimal memory allocation
-- No AST generation
-- Efficient string operations
-
-Benchmarks show quikdown performs comparably to larger markdown parsers while maintaining a much smaller footprint.
+Works with React, Vue, Svelte, Angular. See [Framework Integration Guide](docs/framework-integration.md) for examples.
 
 ## Limitations
 
-quikdown intentionally doesn't support:
-
-- HTML blocks (for security)
-- Reference-style links
+For size and security, quikdown doesn't support:
+- Reference-style links  
 - Footnotes
 - Definition lists
-- Complex table alignment
-- Nested blockquotes with different markers
-
-These omissions keep the parser small, fast, and secure.
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to the branch (`git push origin feature/AmazingFeature`)
-5. Open a Pull Request
 
-## Testing
-
-```bash
-# Run tests
-npm test
-
-# Watch mode
-npm run test:watch
-
-# Coverage report
-npm run test:coverage
+Note that raw html, svg, etc can be rendered using appropriate fences
+```html
+<h1>My HTML Content</h1>
+<p>Some HTML</p>
 ```
+as long as an appropriate fence plugin is provided.  See API docs for example or try out in quikdown_edit.js which has built-in support for HTML with XSS prevention.
 
 ## License
 
-BSD 2-Clause License - see [LICENSE.txt](LICENSE.txt) file for details.
+BSD 2-Clause - see [LICENSE.txt](LICENSE.txt)
 
 ## Acknowledgments
 
@@ -465,14 +235,9 @@ BSD 2-Clause License - see [LICENSE.txt](LICENSE.txt) file for details.
 - CommonMark spec for markdown standardization
 
 
-Choose quikdown when you need:
-- A lightweight solution
-- Built-in security
-- Simple plugin system
-- Zero dependencies
-
-
 ## Support
 
-- 🐛 Issues: [GitHub Issues](https://github.com/deftio/quikdown/issues)
+- 📖 [Documentation](docs/)
+- 🐛 [Issues](https://github.com/deftio/quikdown/issues)
+- 📦 [Examples](examples/)