@sullux/markdown-html 1.0.0 → 1.0.1

package/README.md

@@ -1,113 +1,45 @@
+<p align="center">
+  <img src="docs/logo.svg" alt="Markdown HTML" width="160" height="160" />
+</p>
+
 # @sullux/markdown-html
 
-A high-performance, bidirectional Markdown $\leftrightarrow$ HTML compiler supporting GitHub-Flavored Markdown (GFM), GitBook hints, pluggable code block renderers, built-in syntax highlighting, and custom image dimensions.
+A high-performance, zero-dependency, bidirectional Markdown ↔ HTML compiler supporting GitHub-Flavored Markdown (GFM), GitBook hints, pluggable code block renderers, built-in syntax highlighting, and custom image dimensions.
 
-Part of the Sullux markdown suite, `@sullux/markdown-html` relies on `@sullux/markdown-compiler` for AST parsing and stringifying, ensuring zero dependencies and fully auditable code.
+📖 **Official Documentation:** [https://sullux.com/projects/markdown/markdown-html/](https://sullux.com/projects/markdown/markdown-html/)
 
-## Core Features
+## Overview
 
-* **Bidirectional Transformations:**
-  * `markdownToHtml(markdown, options)`: Renders AST-driven semantic HTML.
-  * `htmlToMarkdown(html)`: Converts HTML documents/emails back to clean GFM Markdown.
-* **Pluggable Code Block Renderers:** Register custom handlers for languages like `mermaid`, `dot`, or bespoke blocks via `options.codeRenderers`.
-* **Built-in Zero-Dependency Syntax Highlighting:**
-  * Out-of-the-box tokenizers for `js`, `json`, `yaml`, `bash`, `html`, and `sql`.
-  * Customizable and overridable via `options.tokenizers`.
-* **Image Dimension Styling:** Multi-syntax dimension support (Obsidian `|400x200`, Pandoc/GitLab `{width=50%}`, GitHub `{:width="400px"}`, VS Code `=300x200`) rendered as inline CSS (`style="width: 400px; height: 200px;"`).
-* **Rich Component Support:**
-  * Auto-slugified heading IDs with deduplication (`<h2 id="section-one-1">`).
-  * Callouts (`> [!NOTE]`, `{% hint %}`).
-  * Task list checkboxes (`- [ ]`, `- [x]`).
-  * GFM tables with column alignment attributes (`<th align="center">`).
-  * YAML frontmatter stripping.
+Part of the Sullux markdown suite, `@sullux/markdown-html` relies on `@sullux/markdown-compiler` to deliver fast, bidirectional conversion between Markdown and clean, semantic HTML. It transforms Markdown ASTs into HTML with auto-slugified heading IDs, callout boxes, task lists, GFM tables, and multi-syntax image dimensions styled as inline CSS. It also parses arbitrary HTML documents, emails, or CMS content back into canonical GFM Markdown with style normalization and layout table flattening.
 
-## Folder Topography
+Key capabilities include pluggable code block renderers for diagrams (such as Mermaid or Graphviz) and zero-dependency compile-time syntax highlighting for common languages (`js`, `json`, `yaml`, `bash`, `html`, `sql`).
 
-```
-packages/markdown-html/
-├── lib/
-│   ├── markdown-to-html/     # Markdown -> AST -> HTML renderer (<100 lines each)
-│   │   ├── index.js
-│   │   ├── render-block.js
-│   │   ├── render-inline.js
-│   │   ├── slugify.js
-│   │   ├── escape.js
-│   │   └── highlight/        # Zero-dependency language tokenizers
-│   │       ├── index.js
-│   │       ├── js.js
-│   │       ├── json.js
-│   │       ├── yaml.js
-│   │       ├── bash.js
-│   │       ├── html.js
-│   │       └── sql.js
-│   └── html-to-markdown/     # HTML -> AST -> Markdown compiler (<100 lines each)
-│       ├── index.js
-│       ├── parse-html.js
-│       ├── ast-builder.js
-│       ├── block-builder.js
-│       ├── block-table.js
-│       ├── inline-builder.js
-│       └── utils.js
-├── index.js                  # Package entrypoint
-└── package.json              # Package manifest
-```
+## Quick Start
 
-## Programmatic Usage
+### Installation
 
-### 1. Converting Markdown to HTML with Options
-
-```javascript
-const { markdownToHtml } = require('@sullux/markdown-html')
-
-const md = `
-# System Spec
-
-![Diagram|400x200](schema.png)
+```bash
+yarn add @sullux/markdown-html
+```
 
-\`\`\`js
-const name = "Sullux";
-\`\`\`
+### Usage
 
-\`\`\`mermaid
-graph TD;
-  A-->B;
-\`\`\`
-`
+```javascript
+const { markdownToHtml, htmlToMarkdown } = require('@sullux/markdown-html')
 
-const html = markdownToHtml(md, {
+// Convert Markdown to semantic HTML with custom code renderers
+const html = markdownToHtml('# Hello\n\n![Diagram|400x200](arch.png)', {
   codeRenderers: {
     mermaid: (node) => `<div class="mermaid">${node.value}</div>\n`,
   },
 })
 
-console.log(html)
-/* Output includes:
-<h1 id="system-spec">System Spec</h1>
-<p><img src="schema.png" alt="Diagram" style="width: 400px; height: 200px;" /></p>
-<pre><code class="language-js"><span class="hl-kw">const</span> <span class="hl-id">name</span> <span class="hl-punc">=</span> <span class="hl-str">&quot;Sullux&quot;</span><span class="hl-punc">;</span></code></pre>
-<div class="mermaid">graph TD;
-  A-->B;</div>
-*/
+// Convert HTML back to clean GFM Markdown
+const markdown = htmlToMarkdown('<h1>Hello</h1><p>This is <strong>bold</strong> text.</p>')
 ```
 
-### 2. Converting HTML back to Markdown
-
-```javascript
-const { htmlToMarkdown } = require('@sullux/markdown-html')
+For complete guides, syntax highlighting details, and full API specifications, see the [official documentation](https://sullux.com/projects/markdown/markdown-html/).
 
-const htmlInput = '<h1>Title</h1><p>This is <strong>bold</strong> text with <a href="https://sullux.com">a link</a>.</p>'
-const markdown = htmlToMarkdown(htmlInput)
+## Contributing & License
 
-console.log(markdown)
-/* Output:
-# Title
-
-This is **bold** text with [a link](https://sullux.com).
-*/
-```
-
-## Running Unit Tests
-
-```bash
-yarn test
-```
+Please see the [Monorepo README](../../README.md) for contribution guidelines, testing instructions, and license details.

package/lib/html-to-markdown/block-builder.js

@@ -21,6 +21,13 @@ const processBlockNode = (node, style, blocks, currentInline, traverse, toAst) =
     return true
   }
 
+  if ((attrs.class || '').includes('math-display') || (tagName !== 'span' && attrs['data-latex'])) {
+    flushInline()
+    const latex = attrs['data-latex'] || (node.children ? node.children.map((c) => c.value || '').join('').replace(/^\$\$|\$\$$/g, '').trim() : '')
+    blocks.push({ type: 'mathBlock', value: latex })
+    return true
+  }
+
   const headerMatch = tagName.match(/^h([1-6])$/)
   if (headerMatch) {
     flushInline()

package/lib/html-to-markdown/inline-builder.js

@@ -47,6 +47,11 @@ const processInlineNode = (node, style, currentInline, traverse) => {
       if (attrs.src) currentInline.push({ type: 'image', url: attrs.src, alt: attrs.alt || '' })
       return true
     }
+    if ((attrs.class || '').includes('math-inline') || (tagName === 'span' && attrs['data-latex'])) {
+      const latex = attrs['data-latex'] || (node.children ? node.children.map((c) => c.value || '').join('').replace(/^\$|\$$/g, '').trim() : '')
+      currentInline.push({ type: 'inlineMath', value: latex })
+      return true
+    }
     if (tagName === 'a') {
       const childTokens = []
       for (const child of node.children) traverse(child, nextStyle, childTokens)

package/lib/markdown-to-html/render-block.js

@@ -8,13 +8,13 @@ const renderBlock = (node, options = {}) => {
 
   switch (node.type) {
     case 'header': {
-      const text = renderInline(node.children)
+      const text = renderInline(node.children, options)
       const rawText = node.children ? node.children.map((c) => (c.type === 'text' ? c.value : '')).join('') : ''
       const slug = (options.slugify || slugify)(rawText, options.usedSlugs)
       return `<h${node.level} id="${slug}">${text}</h${node.level}>\n`
     }
     case 'paragraph': {
-      return `<p>${renderInline(node.children)}</p>\n`
+      return `<p>${renderInline(node.children, options)}</p>\n`
     }
     case 'codeBlock': {
       const lang = node.language || ''
@@ -36,11 +36,11 @@ const renderBlock = (node, options = {}) => {
       return `<div class="callout callout-${style}">\n<div class="callout-title">${title}</div>\n${innerHtml}</div>\n`
     }
     case 'bulletList': {
-      const itemsHtml = node.items ? node.items.map((item) => `<li>${renderInline(item)}</li>\n`).join('') : ''
+      const itemsHtml = node.items ? node.items.map((item) => `<li>${renderInline(item, options)}</li>\n`).join('') : ''
       return `<ul>\n${itemsHtml}</ul>\n`
     }
     case 'orderedList': {
-      const itemsHtml = node.items ? node.items.map((item) => `<li>${renderInline(item)}</li>\n`).join('') : ''
+      const itemsHtml = node.items ? node.items.map((item) => `<li>${renderInline(item, options)}</li>\n`).join('') : ''
       return `<ol>\n${itemsHtml}</ol>\n`
     }
     case 'table': {
@@ -57,7 +57,7 @@ const renderBlock = (node, options = {}) => {
           .map((cell, colIdx) => {
             const align = alignments[colIdx] || 'default'
             const alignAttr = align !== 'default' ? ` align="${align}"` : ''
-            return `<${cellTag}${alignAttr}>${renderInline(cell)}</${cellTag}>`
+            return `<${cellTag}${alignAttr}>${renderInline(cell, options)}</${cellTag}>`
           })
           .join('')
         return `<tr>${cells}</tr>\n`
@@ -73,6 +73,14 @@ const renderBlock = (node, options = {}) => {
     case 'hr': {
       return '<hr />\n'
     }
+    case 'html': {
+      return `${node.value}\n`
+    }
+    case 'mathBlock': {
+      const mathRenderer = options.mathBlockRenderer || options.codeRenderers?.math
+      if (mathRenderer) return mathRenderer(node, options)
+      return `<div class="math-display" data-latex="${escapeHtml(node.value)}">$$\n${escapeHtml(node.value)}\n$$</div>\n`
+    }
     default: {
       return ''
     }

package/lib/markdown-to-html/render-inline.js

@@ -1,6 +1,6 @@
 const { escapeHtml } = require('./escape')
 
-const renderInline = (tokens) => {
+const renderInline = (tokens, options = {}) => {
   if (!tokens) return ''
   if (!Array.isArray(tokens)) return escapeHtml(tokens)
 
@@ -13,15 +13,15 @@ const renderInline = (tokens) => {
         case 'text':
           return escapeHtml(token.value)
         case 'bold':
-          return `<strong>${renderInline(token.children)}</strong>`
+          return `<strong>${renderInline(token.children, options)}</strong>`
         case 'italic':
-          return `<em>${renderInline(token.children)}</em>`
+          return `<em>${renderInline(token.children, options)}</em>`
         case 'strikethrough':
-          return `<del>${renderInline(token.children)}</del>`
+          return `<del>${renderInline(token.children, options)}</del>`
         case 'code':
           return `<code>${escapeHtml(token.value)}</code>`
         case 'link':
-          return `<a href="${escapeHtml(token.url)}">${renderInline(token.children)}</a>`
+          return `<a href="${escapeHtml(token.url)}">${renderInline(token.children, options)}</a>`
         case 'wikilink':
           return `<a href="${escapeHtml(token.target)}">${escapeHtml(token.display)}</a>`
         case 'image': {
@@ -36,6 +36,10 @@ const renderInline = (tokens) => {
         }
         case 'checkbox':
           return `<input type="checkbox"${token.checked ? ' checked' : ''} disabled /> `
+        case 'inlineMath': {
+          if (options.inlineMathRenderer) return options.inlineMathRenderer(token, options)
+          return `<span class="math-inline" data-latex="${escapeHtml(token.value)}">$${escapeHtml(token.value)}$</span>`
+        }
         case 'br':
           return '<br />'
         default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sullux/markdown-html",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A high-performance, bidirectional Markdown <-> HTML compiler supporting GFM, GitBook hints, syntax highlighting, and custom image dimensions.",
   "main": "./index.js",
   "author": "Charles Sullivan <charles@sullux.com>",