quikdown 1.0.2 → 1.0.3

package/README.md

@@ -1,10 +1,10 @@
 # quikdown
 
 [![CI](https://github.com/deftio/quikdown/actions/workflows/ci.yml/badge.svg)](https://github.com/deftio/quikdown/actions/workflows/ci.yml)
-[![npm version](https://badge.fury.io/js/quikdown.svg)](https://www.npmjs.com/package/quikdown)
-[![Coverage Status](https://img.shields.io/badge/coverage-99%25-brightgreen.svg)](https://github.com/deftio/quikdown)
+[![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-green.svg)](https://github.com/deftio/quikdown/tree/main/dist)
+[![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.
 
@@ -16,7 +16,7 @@ A lightweight, fast markdown parser with built-in XSS protection. Quikdown works
 
 - 🚀 **Lightweight** - Under 10KB minified
 - 🔒 **Secure by default** - Built-in XSS protection with URL sanitization
-- 🎨 **Flexible styling** - Inline styles or CSS classes including examples for light and dark mode generation
+- 🎨 **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
@@ -32,10 +32,28 @@ npm install quikdown
 ```
 
 Or via CDN:
+
+**ES Modules (recommended for modern applications):**
+```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;
+</script>
+```
+
+**UMD (for legacy browser support):**
 ```html
-<script src="https://unpkg.com/quikdown/dist/quikdown.umd.js"></script>
+<script src="https://unpkg.com/quikdown/dist/quikdown.umd.min.js"></script>
+<script>
+  // Available as window.quikdown
+  const html = 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
@@ -58,6 +76,23 @@ const html = quikdown(markdown, {
 });
 ```
 
+### 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:
@@ -229,6 +264,10 @@ 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)
@@ -259,29 +298,77 @@ const myParser = quikdown.configure({
 const html = myParser(markdown);
 ```
 
-### `quikdown.emitStyles()`
+### `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
-const styles = quikdown.emitStyles();
+// Get light theme CSS
+const lightStyles = quikdown.emitStyles();
+
+// Get dark theme CSS  
+const darkStyles = quikdown.emitStyles('quikdown-', 'dark');
+
 // Add to your stylesheet or <style> tag
 ```
 
+## Theming
+
+QuikDown supports flexible theming through container-based CSS scoping:
+
+### Using Pre-built Themes
+
+```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>
+```
+
+### Theme Architecture
+
+- **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
+
+### Inline Styles
+
+For a batteries-included approach without CSS files:
+
+```javascript
+// Use inline styles (always light theme currently)
+const html = quikdown(markdown, { inline_styles: true });
+```
+
 ## Browser Usage
 
-### Via Script Tag
+### ES Modules (Recommended)
 
 ```html
 <!DOCTYPE html>
 <html>
 <head>
-    <script src="https://unpkg.com/quikdown/dist/quikdown.umd.js"></script>
+    <meta charset="UTF-8">
 </head>
 <body>
     <div id="output"></div>
-    <script>
-        const markdown = '# Hello quikdown!';
+    <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>
@@ -289,13 +376,23 @@ const styles = quikdown.emitStyles();
 </html>
 ```
 
-### ES Modules
-
-```javascript
-import quikdown from 'quikdown';
+### UMD Script Tag (Legacy)
 
-const html = quikdown('**Hello** world!');
-document.body.innerHTML = html;
+```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>
 ```
 
 ## Node.js Usage