@sullux/markdown-html 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles Sullivan <charles@sullux.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# @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.
+
+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.
+
+## Core Features
+
+* **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.
+
+## Folder Topography
+
+```
+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
+```
+
+## Programmatic Usage
+
+### 1. Converting Markdown to HTML with Options
+
+```javascript
+const { markdownToHtml } = require('@sullux/markdown-html')
+
+const md = `
+# System Spec
+
+![Diagram|400x200](schema.png)
+
+\`\`\`js
+const name = "Sullux";
+\`\`\`
+
+\`\`\`mermaid
+graph TD;
+  A-->B;
+\`\`\`
+`
+
+const html = markdownToHtml(md, {
+  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>
+*/
+```
+
+### 2. Converting HTML back to Markdown
+
+```javascript
+const { htmlToMarkdown } = require('@sullux/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)
+
+console.log(markdown)
+/* Output:
+# Title
+
+This is **bold** text with [a link](https://sullux.com).
+*/
+```
+
+## Running Unit Tests
+
+```bash
+yarn test
+```

package/index.js

@@ -0,0 +1,10 @@
+const { markdownToHtml } = require('./lib/markdown-to-html')
+const { htmlToMarkdown, toMarkdown, parseHtml, toAst } = require('./lib/html-to-markdown')
+
+module.exports = {
+  markdownToHtml,
+  htmlToMarkdown,
+  toMarkdown,
+  parseHtml,
+  toAst,
+}

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

@@ -0,0 +1,36 @@
+const { processInlineNode } = require('./inline-builder')
+const { processBlockNode } = require('./block-builder')
+
+const DEFAULT_STYLE = {
+  fontWeight: 'normal',
+  fontStyle: 'normal',
+  isCode: false,
+}
+
+const toAst = (htmlRoot) => {
+  const blocks = []
+  let currentInline = []
+
+  const traverse = (node, style, inlineTarget) => {
+    const target = inlineTarget || currentInline
+
+    if (processInlineNode(node, style, target, traverse)) return
+    if (processBlockNode(node, style, blocks, currentInline, traverse, toAst)) return
+
+    if (node.children) {
+      for (const child of node.children) traverse(child, style, target)
+    }
+  }
+
+  for (const child of htmlRoot.children) traverse(child, DEFAULT_STYLE, currentInline)
+
+  if (currentInline.length > 0) {
+    if (currentInline[0].type === 'text' && currentInline[0].value === ' ') currentInline.shift()
+    if (currentInline.length > 0 && currentInline[currentInline.length - 1].type === 'text' && currentInline[currentInline.length - 1].value === ' ') currentInline.pop()
+    if (currentInline.length > 0) blocks.push({ type: 'paragraph', children: [...currentInline] })
+  }
+
+  return { frontmatter: {}, blocks }
+}
+
+module.exports = { toAst }

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

@@ -0,0 +1,87 @@
+const { parseStyleAttr } = require('./utils')
+const { processTableNode } = require('./block-table')
+
+const processBlockNode = (node, style, blocks, currentInline, traverse, toAst) => {
+  if (node.type !== 'element') return false
+
+  const tagName = node.tagName
+  const attrs = node.attributes || {}
+  const inlineStyles = parseStyleAttr(attrs.style)
+
+  const flushInline = () => {
+    if (currentInline.length > 0) {
+      blocks.push({ type: 'paragraph', children: [...currentInline] })
+      currentInline.length = 0
+    }
+  }
+
+  if (tagName === 'hr') {
+    flushInline()
+    blocks.push({ type: 'hr' })
+    return true
+  }
+
+  const headerMatch = tagName.match(/^h([1-6])$/)
+  if (headerMatch) {
+    flushInline()
+    const level = parseInt(headerMatch[1])
+    const headerInline = []
+    for (const child of node.children) traverse(child, { ...style, fontWeight: 'normal' }, headerInline)
+    if (headerInline.length > 0) blocks.push({ type: 'header', level, children: headerInline })
+    return true
+  }
+
+  const fontSizeVal = inlineStyles['font-size']
+  if (fontSizeVal && (tagName === 'div' || tagName === 'p' || tagName === 'span')) {
+    const sizePx = parseInt(fontSizeVal)
+    if (sizePx >= 20) {
+      flushInline()
+      const level = sizePx >= 28 ? 1 : (sizePx >= 24 ? 2 : 3)
+      const headerInline = []
+      for (const child of node.children) traverse(child, { ...style, fontWeight: 'normal' }, headerInline)
+      if (headerInline.length > 0) blocks.push({ type: 'header', level, children: headerInline })
+      return true
+    }
+  }
+
+  if (tagName === 'blockquote') {
+    flushInline()
+    const innerDoc = toAst(node)
+    if (innerDoc.blocks.length > 0) blocks.push({ type: 'blockquote', children: innerDoc.blocks })
+    return true
+  }
+
+  if (tagName === 'ul' || tagName === 'ol') {
+    flushInline()
+    const items = []
+    for (const child of node.children) {
+      if (child.tagName === 'li') {
+        const itemInline = []
+        for (const liChild of child.children) traverse(liChild, style, itemInline)
+        if (itemInline.length > 0) items.push(itemInline)
+      } else {
+        traverse(child, style, currentInline)
+      }
+    }
+    if (items.length > 0) blocks.push({ type: tagName === 'ul' ? 'bulletList' : 'orderedList', items })
+    return true
+  }
+
+  if (tagName === 'table') {
+    flushInline()
+    processTableNode(node, style, blocks, traverse)
+    return true
+  }
+
+  const isBlockContainer = new Set(['div', 'p', 'section', 'article', 'main', 'header', 'footer', 'address', 'pre']).has(tagName)
+  if (isBlockContainer) {
+    flushInline()
+    for (const child of node.children) traverse(child, style, currentInline)
+    flushInline()
+    return true
+  }
+
+  return false
+}
+
+module.exports = { processBlockNode }

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

@@ -0,0 +1,50 @@
+const { isCellEmpty, optimizeTable } = require('./utils')
+
+const processTableNode = (node, style, blocks, traverse) => {
+  const tableAlignments = []
+  const tableRows = []
+
+  const findRows = (tableNode) => {
+    for (const child of tableNode.children) {
+      if (child.tagName === 'tr') {
+        const cells = []
+        for (const cellNode of child.children) {
+          if (cellNode.tagName === 'th' || cellNode.tagName === 'td') {
+            if (tableRows.length === 0) {
+              const alignAttr = cellNode.attributes.align || ''
+              const styleMatch = cellNode.attributes.style?.match(/text-align:\s*([a-z]+)/)
+              let align = alignAttr.toLowerCase() || styleMatch?.[1] || 'default'
+              if (align !== 'left' && align !== 'right' && align !== 'center') align = 'default'
+              tableAlignments.push(align)
+            }
+            const cellInline = []
+            for (const cellChild of cellNode.children) traverse(cellChild, style, cellInline)
+            cells.push(cellInline)
+          }
+        }
+        if (cells.length > 0) tableRows.push(cells)
+      } else if (child.tagName === 'tbody' || child.tagName === 'thead' || child.tagName === 'tfoot') {
+        findRows(child)
+      }
+    }
+  }
+
+  findRows(node)
+
+  if (tableRows.length > 0) {
+    const optimized = optimizeTable(tableRows, tableAlignments)
+    if (optimized) {
+      if (optimized.rows[0].length <= 1 || optimized.rows.length <= 1) {
+        for (const row of optimized.rows) {
+          for (const cell of row) {
+            if (!isCellEmpty(cell)) blocks.push({ type: 'paragraph', children: cell })
+          }
+        }
+      } else {
+        blocks.push({ type: 'table', alignments: optimized.alignments, rows: optimized.rows })
+      }
+    }
+  }
+}
+
+module.exports = { processTableNode }

package/lib/html-to-markdown/index.js

@@ -0,0 +1,17 @@
+const { stringify } = require('@sullux/markdown-compiler')
+const { parseHtml } = require('./parse-html')
+const { toAst } = require('./ast-builder')
+
+const htmlToMarkdown = (htmlString) => {
+  if (!htmlString) return ''
+  const htmlTree = parseHtml(htmlString)
+  const markdownAst = toAst(htmlTree)
+  return stringify(markdownAst)
+}
+
+module.exports = {
+  parseHtml,
+  toAst,
+  htmlToMarkdown,
+  toMarkdown: htmlToMarkdown,
+}

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

@@ -0,0 +1,66 @@
+const { parseStyleAttr, decodeHtmlEntities } = require('./utils')
+
+const INLINE_TAGS = new Set([
+  'b', 'strong', 'i', 'em', 'code', 'tt', 'span', 'a', 'img', 'br', 'sub', 'sup', 'del', 's', 'strike', 'mark', 'u'
+])
+
+const processInlineNode = (node, style, currentInline, traverse) => {
+  if (node.type === 'text') {
+    let textVal = decodeHtmlEntities(node.value)
+    if (!style.isCode) textVal = textVal.replace(/\s+/g, ' ')
+    if (textVal === ' ' || textVal === '') {
+      if (textVal === ' ' && currentInline.length > 0) {
+        const lastToken = currentInline[currentInline.length - 1]
+        if (lastToken.type !== 'text' || !lastToken.value.endsWith(' ')) {
+          currentInline.push({ type: 'text', value: ' ' })
+        }
+      }
+      return true
+    }
+
+    let token = { type: 'text', value: textVal }
+    if (style.fontStyle === 'italic') token = { type: 'italic', children: [token] }
+    if (style.fontWeight === 'bold') token = { type: 'bold', children: [token] }
+    if (style.isCode) token = { type: 'code', value: textVal }
+
+    currentInline.push(token)
+    return true
+  }
+
+  if (node.type === 'element') {
+    const tagName = node.tagName
+    const attrs = node.attributes || {}
+    const inlineStyles = parseStyleAttr(attrs.style)
+    const nextStyle = { ...style }
+
+    if (tagName === 'b' || tagName === 'strong') nextStyle.fontWeight = 'bold'
+    if (tagName === 'i' || tagName === 'em') nextStyle.fontStyle = 'italic'
+    if (tagName === 'code' || tagName === 'tt') nextStyle.isCode = true
+    if (inlineStyles['font-weight'] === 'bold' || parseInt(inlineStyles['font-weight']) >= 700) nextStyle.fontWeight = 'bold'
+    if (inlineStyles['font-style'] === 'italic') nextStyle.fontStyle = 'italic'
+
+    if (tagName === 'br') {
+      currentInline.push({ type: 'br' })
+      return true
+    }
+    if (tagName === 'img') {
+      if (attrs.src) currentInline.push({ type: 'image', url: attrs.src, alt: attrs.alt || '' })
+      return true
+    }
+    if (tagName === 'a') {
+      const childTokens = []
+      for (const child of node.children) traverse(child, nextStyle, childTokens)
+      if (childTokens.length > 0) currentInline.push({ type: 'link', url: attrs.href || '', children: childTokens })
+      return true
+    }
+
+    if (INLINE_TAGS.has(tagName)) {
+      for (const child of node.children) traverse(child, nextStyle, currentInline)
+      return true
+    }
+  }
+
+  return false
+}
+
+module.exports = { processInlineNode }

package/lib/html-to-markdown/parse-html.js

@@ -0,0 +1,59 @@
+const { VOID_TAGS, parseAttributes } = require('./utils')
+
+const parseHtml = (rawHtml) => {
+  let html = (rawHtml || '')
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<(script|style)[\s\S]*?<\/\1>/gi, '')
+
+  const root = { type: 'element', tagName: 'root', attributes: {}, children: [] }
+  const stack = [root]
+  let index = 0
+
+  while (index < html.length) {
+    const nextTag = html.indexOf('<', index)
+
+    if (nextTag === -1 || nextTag > index) {
+      const textVal = nextTag === -1 ? html.slice(index) : html.slice(index, nextTag)
+      if (textVal) {
+        stack[stack.length - 1].children.push({ type: 'text', value: textVal })
+      }
+      if (nextTag === -1) break
+    }
+
+    const closeTag = html.indexOf('>', nextTag)
+    if (closeTag === -1) break
+
+    const tagContent = html.slice(nextTag + 1, closeTag).trim()
+    index = closeTag + 1
+
+    if (tagContent.startsWith('/')) {
+      const tagName = tagContent.slice(1).trim().toLowerCase()
+      const matchIdx = stack.map(node => node.tagName).lastIndexOf(tagName)
+      if (matchIdx > 0) {
+        stack.length = matchIdx
+      }
+      continue
+    }
+
+    const isSelfClosing = tagContent.endsWith('/')
+    const cleanedContent = isSelfClosing ? tagContent.slice(0, -1).trim() : tagContent
+
+    const nameMatch = cleanedContent.match(/^([a-zA-Z0-9_\-]+)/)
+    if (!nameMatch) continue
+    const tagName = nameMatch[1].toLowerCase()
+
+    const attrString = cleanedContent.slice(tagName.length).trim()
+    const attributes = parseAttributes(attrString)
+
+    const element = { type: 'element', tagName, attributes, children: [] }
+    stack[stack.length - 1].children.push(element)
+
+    if (!isSelfClosing && !VOID_TAGS.has(tagName)) {
+      stack.push(element)
+    }
+  }
+
+  return root
+}
+
+module.exports = { parseHtml }

package/lib/html-to-markdown/utils.js

@@ -0,0 +1,93 @@
+const VOID_TAGS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr'
+])
+
+const parseAttributes = (attrStr) => {
+  const attrs = {}
+  if (!attrStr) return attrs
+  const matches = attrStr.matchAll(/([a-zA-Z0-9_\-]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g)
+  for (const match of matches) {
+    const key = match[1].toLowerCase()
+    const val = match[2] !== undefined ? match[2] : (match[3] !== undefined ? match[3] : (match[4] !== undefined ? match[4] : ''))
+    attrs[key] = val
+  }
+  return attrs
+}
+
+const parseStyleAttr = (styleStr) => {
+  if (!styleStr) return {}
+  const styles = {}
+  styleStr.split(';').forEach(decl => {
+    const parts = decl.split(':')
+    if (parts.length === 2) {
+      styles[parts[0].trim().toLowerCase()] = parts[1].trim().toLowerCase()
+    }
+  })
+  return styles
+}
+
+const decodeHtmlEntities = (str) => {
+  if (!str) return ''
+  const entities = {
+    nbsp: ' ', zwnj: '', amp: '&', lt: '<', gt: '>', quot: '"', apos: "'",
+    ldquo: '“', rdquo: '”', lsquo: '‘', rsquo: '’', ndash: '–', mdash: '—',
+  }
+  return str
+    .replace(/&([a-z0-9]+);/gi, (match, name) => {
+      const lower = name.toLowerCase()
+      return entities[lower] !== undefined ? entities[lower] : match
+    })
+    .replace(/&#([0-9]+);/g, (match, dec) => String.fromCharCode(parseInt(dec, 10)))
+    .replace(/&#x([0-9a-f]+);/gi, (match, hex) => String.fromCharCode(parseInt(hex, 16)))
+}
+
+const isCellEmpty = (cell) => {
+  if (!cell || cell.length === 0) return true
+  return cell.every(node => {
+    if (node.type === 'text') return !node.value.trim()
+    if (node.type === 'br') return true
+    return false
+  })
+}
+
+const optimizeTable = (rows, alignments) => {
+  const nonDescantRows = rows.filter(row => row.some(cell => !isCellEmpty(cell)))
+  if (nonDescantRows.length === 0) return null
+
+  const numCols = Math.max(...nonDescantRows.map(r => r.length))
+  const emptyCols = new Set()
+  for (let c = 0; c < numCols; c++) {
+    let colIsEmpty = true
+    for (const row of nonDescantRows) {
+      if (row[c] && !isCellEmpty(row[c])) {
+        colIsEmpty = false
+        break
+      }
+    }
+    if (colIsEmpty) emptyCols.add(c)
+  }
+
+  const cleanRows = nonDescantRows.map(row => {
+    const newRow = []
+    for (let c = 0; c < numCols; c++) {
+      if (!emptyCols.has(c)) newRow.push(row[c] || [])
+    }
+    return newRow
+  })
+
+  const cleanAlignments = []
+  for (let c = 0; c < numCols; c++) {
+    if (!emptyCols.has(c)) cleanAlignments.push(alignments[c] || 'default')
+  }
+
+  return { rows: cleanRows, alignments: cleanAlignments }
+}
+
+module.exports = {
+  VOID_TAGS,
+  parseAttributes,
+  parseStyleAttr,
+  decodeHtmlEntities,
+  isCellEmpty,
+  optimizeTable,
+}

package/lib/markdown-to-html/escape.js

@@ -0,0 +1,11 @@
+const escapeHtml = (str) => {
+  if (!str) return ''
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+module.exports = { escapeHtml }

package/lib/markdown-to-html/highlight/bash.js

@@ -0,0 +1,45 @@
+const { escapeHtml } = require('../escape')
+
+const BASH_KEYWORDS = new Set(['if', 'then', 'else', 'elif', 'fi', 'for', 'while', 'in', 'do', 'done', 'case', 'esac', 'function', 'return', 'exit'])
+
+const highlightBash = (code) => {
+  const bashRegex = /(#.*$)|("(?:\\.|[^\\])*?"|'(?:\\.|[^\\])*?')|(\$[a-zA-Z0-9_]+|\$\{[^}]+\})|\b([a-zA-Z0-9_\-]+)\b/gm
+
+  let result = ''
+  let lastIndex = 0
+  let match
+
+  while ((match = bashRegex.exec(code)) !== null) {
+    if (match.index > lastIndex) {
+      result += escapeHtml(code.slice(lastIndex, match.index))
+    }
+
+    const [raw, cmt, strVal, varVal, wordVal] = match
+
+    if (cmt) {
+      result += `<span class="hl-cmt">${escapeHtml(cmt)}</span>`
+    } else if (strVal) {
+      result += `<span class="hl-str">${escapeHtml(strVal)}</span>`
+    } else if (varVal) {
+      result += `<span class="hl-var">${escapeHtml(varVal)}</span>`
+    } else if (wordVal) {
+      if (BASH_KEYWORDS.has(wordVal)) {
+        result += `<span class="hl-kw">${escapeHtml(wordVal)}</span>`
+      } else {
+        result += escapeHtml(wordVal)
+      }
+    } else {
+      result += escapeHtml(raw)
+    }
+
+    lastIndex = bashRegex.lastIndex
+  }
+
+  if (lastIndex < code.length) {
+    result += escapeHtml(code.slice(lastIndex))
+  }
+
+  return result
+}
+
+module.exports = { highlightBash }

package/lib/markdown-to-html/highlight/html.js

@@ -0,0 +1,39 @@
+const { escapeHtml } = require('../escape')
+
+const highlightHtml = (code) => {
+  const htmlRegex = /(<!--[\s\S]*?-->)|(<\/?[a-zA-Z0-9\-]+)|([a-zA-Z0-9\-]+)=("[^"]*"|'[^']*')|(\/?>)/g
+
+  let result = ''
+  let lastIndex = 0
+  let match
+
+  while ((match = htmlRegex.exec(code)) !== null) {
+    if (match.index > lastIndex) {
+      result += escapeHtml(code.slice(lastIndex, match.index))
+    }
+
+    const [raw, cmt, tagStart, attrName, attrVal, tagEnd] = match
+
+    if (cmt) {
+      result += `<span class="hl-cmt">${escapeHtml(cmt)}</span>`
+    } else if (tagStart) {
+      result += `<span class="hl-tag">${escapeHtml(tagStart)}</span>`
+    } else if (attrName && attrVal) {
+      result += `<span class="hl-attr">${escapeHtml(attrName)}</span>=<span class="hl-str">${escapeHtml(attrVal)}</span>`
+    } else if (tagEnd) {
+      result += `<span class="hl-tag">${escapeHtml(tagEnd)}</span>`
+    } else {
+      result += escapeHtml(raw)
+    }
+
+    lastIndex = htmlRegex.lastIndex
+  }
+
+  if (lastIndex < code.length) {
+    result += escapeHtml(code.slice(lastIndex))
+  }
+
+  return result
+}
+
+module.exports = { highlightHtml }

package/lib/markdown-to-html/highlight/index.js

@@ -0,0 +1,33 @@
+const { highlightJs } = require('./js')
+const { highlightJson } = require('./json')
+const { highlightYaml } = require('./yaml')
+const { highlightBash } = require('./bash')
+const { highlightHtml } = require('./html')
+const { highlightSql } = require('./sql')
+const { escapeHtml } = require('../escape')
+
+const DEFAULT_TOKENIZERS = {
+  js: highlightJs,
+  javascript: highlightJs,
+  json: highlightJson,
+  yaml: highlightYaml,
+  yml: highlightYaml,
+  bash: highlightBash,
+  sh: highlightBash,
+  zsh: highlightBash,
+  html: highlightHtml,
+  xml: highlightHtml,
+  sql: highlightSql,
+}
+
+const highlightCode = (code, lang, customTokenizers) => {
+  const tokenizers = { ...DEFAULT_TOKENIZERS, ...customTokenizers }
+  const normalizedLang = (lang || '').toLowerCase()
+  const tokenizer = tokenizers[normalizedLang]
+  if (tokenizer) {
+    return tokenizer(code)
+  }
+  return escapeHtml(code)
+}
+
+module.exports = { DEFAULT_TOKENIZERS, highlightCode }

package/lib/markdown-to-html/highlight/js.js

@@ -0,0 +1,53 @@
+const { escapeHtml } = require('../escape')
+
+const JS_KEYWORDS = new Set([
+  'const', 'let', 'var', 'function', 'return', 'if', 'else', 'for', 'while', 'do',
+  'switch', 'case', 'break', 'continue', 'default', 'import', 'export', 'from',
+  'as', 'class', 'extends', 'super', 'this', 'new', 'try', 'catch', 'finally',
+  'throw', 'async', 'await', 'yield', 'typeof', 'instanceof', 'in', 'of', 'null',
+  'undefined', 'true', 'false', 'void', 'delete'
+])
+
+const highlightJs = (code) => {
+  const tokenRegex = /(\/\/.*$|\/\*[\s\S]*?\*\/)|("(?:\\[\s\S]|[^"\\])*?"|'(?:\\[\s\S]|[^'\\])*?'|`(?:\\[\s\S]|[^`\\])*?`)|(\b[0-9]+(?:\.[0-9]+)?\b)|(\b[a-zA-Z_$][a-zA-Z0-9_$]*\b)|([{}()\[\];,.:+=\-*\/%&|^!~?<>]+)/gm
+
+  let result = ''
+  let lastIndex = 0
+  let match
+
+  while ((match = tokenRegex.exec(code)) !== null) {
+    if (match.index > lastIndex) {
+      result += escapeHtml(code.slice(lastIndex, match.index))
+    }
+
+    const [raw, comment, stringLiteral, numberLiteral, identifier, punctuation] = match
+
+    if (comment) {
+      result += `<span class="hl-cmt">${escapeHtml(comment)}</span>`
+    } else if (stringLiteral) {
+      result += `<span class="hl-str">${escapeHtml(stringLiteral)}</span>`
+    } else if (numberLiteral) {
+      result += `<span class="hl-num">${escapeHtml(numberLiteral)}</span>`
+    } else if (identifier) {
+      if (JS_KEYWORDS.has(identifier)) {
+        result += `<span class="hl-kw">${escapeHtml(identifier)}</span>`
+      } else {
+        result += `<span class="hl-id">${escapeHtml(identifier)}</span>`
+      }
+    } else if (punctuation) {
+      result += `<span class="hl-punc">${escapeHtml(punctuation)}</span>`
+    } else {
+      result += escapeHtml(raw)
+    }
+
+    lastIndex = tokenRegex.lastIndex
+  }
+
+  if (lastIndex < code.length) {
+    result += escapeHtml(code.slice(lastIndex))
+  }
+
+  return result
+}
+
+module.exports = { highlightJs }

package/lib/markdown-to-html/highlight/json.js

@@ -0,0 +1,41 @@
+const { escapeHtml } = require('../escape')
+
+const highlightJson = (code) => {
+  const jsonRegex = /("(?:\\.|[^\\])*?")\s*(:)|("(?:\\.|[^\\])*?")|\b(true|false|null)\b|\b(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)\b|([{}()\[\],])/g
+
+  let result = ''
+  let lastIndex = 0
+  let match
+
+  while ((match = jsonRegex.exec(code)) !== null) {
+    if (match.index > lastIndex) {
+      result += escapeHtml(code.slice(lastIndex, match.index))
+    }
+
+    const [raw, keyStr, colon, valStr, boolNull, num, punc] = match
+
+    if (keyStr && colon) {
+      result += `<span class="hl-key">${escapeHtml(keyStr)}</span>` + `<span class="hl-punc">${escapeHtml(colon)}</span>`
+    } else if (valStr) {
+      result += `<span class="hl-str">${escapeHtml(valStr)}</span>`
+    } else if (boolNull) {
+      result += `<span class="hl-kw">${escapeHtml(boolNull)}</span>`
+    } else if (num) {
+      result += `<span class="hl-num">${escapeHtml(num)}</span>`
+    } else if (punc) {
+      result += `<span class="hl-punc">${escapeHtml(punc)}</span>`
+    } else {
+      result += escapeHtml(raw)
+    }
+
+    lastIndex = jsonRegex.lastIndex
+  }
+
+  if (lastIndex < code.length) {
+    result += escapeHtml(code.slice(lastIndex))
+  }
+
+  return result
+}
+
+module.exports = { highlightJson }

package/lib/markdown-to-html/highlight/sql.js

@@ -0,0 +1,54 @@
+const { escapeHtml } = require('../escape')
+
+const SQL_KEYWORDS = new Set([
+  'SELECT', 'FROM', 'WHERE', 'INSERT', 'INTO', 'UPDATE', 'DELETE', 'CREATE', 'TABLE',
+  'PRIMARY', 'KEY', 'FOREIGN', 'REFERENCES', 'JOIN', 'LEFT', 'RIGHT', 'INNER', 'OUTER',
+  'ON', 'GROUP', 'BY', 'ORDER', 'HAVING', 'LIMIT', 'OFFSET', 'UNION', 'ALL', 'AS', 'AND',
+  'OR', 'NOT', 'IN', 'IS', 'NULL', 'LIKE', 'EXISTS', 'DEFAULT', 'VARCHAR', 'INTEGER', 'INT',
+  'TEXT', 'BOOLEAN', 'TIMESTAMP', 'NOT', 'NULL', 'CAST'
+])
+
+const highlightSql = (code) => {
+  const sqlRegex = /(--.*$|\/\*[\s\S]*?\*\/)|("?:?[a-zA-Z0-9_\-]+"?)|('(?:\\.|[^\'])*?')|\b([0-9]+(?:\.[0-9]+)?)\b|([(),.;=+*\/%<>!]+)/gm
+
+  let result = ''
+  let lastIndex = 0
+  let match
+
+  while ((match = sqlRegex.exec(code)) !== null) {
+    if (match.index > lastIndex) {
+      result += escapeHtml(code.slice(lastIndex, match.index))
+    }
+
+    const [raw, cmt, wordVal, strVal, numVal, puncVal] = match
+
+    if (cmt) {
+      result += `<span class="hl-cmt">${escapeHtml(cmt)}</span>`
+    } else if (strVal) {
+      result += `<span class="hl-str">${escapeHtml(strVal)}</span>`
+    } else if (wordVal) {
+      const upper = wordVal.toUpperCase()
+      if (SQL_KEYWORDS.has(upper)) {
+        result += `<span class="hl-kw">${escapeHtml(wordVal)}</span>`
+      } else {
+        result += escapeHtml(wordVal)
+      }
+    } else if (numVal) {
+      result += `<span class="hl-num">${escapeHtml(numVal)}</span>`
+    } else if (puncVal) {
+      result += `<span class="hl-punc">${escapeHtml(puncVal)}</span>`
+    } else {
+      result += escapeHtml(raw)
+    }
+
+    lastIndex = sqlRegex.lastIndex
+  }
+
+  if (lastIndex < code.length) {
+    result += escapeHtml(code.slice(lastIndex))
+  }
+
+  return result
+}
+
+module.exports = { highlightSql }

package/lib/markdown-to-html/highlight/yaml.js

@@ -0,0 +1,43 @@
+const { escapeHtml } = require('../escape')
+
+const highlightYaml = (code) => {
+  const yamlRegex = /(#.*$)|^([ \t]*[a-zA-Z0-9_\-]+)(:)|("(?:\\.|[^\\])*?"|'(?:\\.|[^\\])*?')|\b(true|false|null)\b|\b([0-9]+(?:\.[0-9]+)?)\b|([:\-\[\]{}])/gm
+
+  let result = ''
+  let lastIndex = 0
+  let match
+
+  while ((match = yamlRegex.exec(code)) !== null) {
+    if (match.index > lastIndex) {
+      result += escapeHtml(code.slice(lastIndex, match.index))
+    }
+
+    const [raw, cmt, keyName, colon, strVal, kwVal, numVal, puncVal] = match
+
+    if (cmt) {
+      result += `<span class="hl-cmt">${escapeHtml(cmt)}</span>`
+    } else if (keyName) {
+      result += `<span class="hl-key">${escapeHtml(keyName)}</span>` + (colon ? `<span class="hl-punc">${escapeHtml(colon)}</span>` : '')
+    } else if (strVal) {
+      result += `<span class="hl-str">${escapeHtml(strVal)}</span>`
+    } else if (kwVal) {
+      result += `<span class="hl-kw">${escapeHtml(kwVal)}</span>`
+    } else if (numVal) {
+      result += `<span class="hl-num">${escapeHtml(numVal)}</span>`
+    } else if (puncVal) {
+      result += `<span class="hl-punc">${escapeHtml(puncVal)}</span>`
+    } else {
+      result += escapeHtml(raw)
+    }
+
+    lastIndex = yamlRegex.lastIndex
+  }
+
+  if (lastIndex < code.length) {
+    result += escapeHtml(code.slice(lastIndex))
+  }
+
+  return result
+}
+
+module.exports = { highlightYaml }

package/lib/markdown-to-html/index.js

@@ -0,0 +1,11 @@
+const { parse } = require('@sullux/markdown-compiler')
+const { renderBlock } = require('./render-block')
+
+const markdownToHtml = (markdown, options = {}) => {
+  if (!markdown) return ''
+  const ast = parse(markdown)
+  const ctx = { ...options, usedSlugs: new Set() }
+  return ast.blocks.map((block) => renderBlock(block, ctx)).join('')
+}
+
+module.exports = { markdownToHtml }

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

@@ -0,0 +1,82 @@
+const { escapeHtml } = require('./escape')
+const { slugify } = require('./slugify')
+const { renderInline } = require('./render-inline')
+const { highlightCode } = require('./highlight')
+
+const renderBlock = (node, options = {}) => {
+  if (!node) return ''
+
+  switch (node.type) {
+    case 'header': {
+      const text = renderInline(node.children)
+      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`
+    }
+    case 'codeBlock': {
+      const lang = node.language || ''
+      if (options.codeRenderers && lang && options.codeRenderers[lang]) {
+        return options.codeRenderers[lang](node, options)
+      }
+      const highlighted = highlightCode(node.value, lang, options.tokenizers)
+      const langClass = lang ? ` class="language-${escapeHtml(lang)}"` : ''
+      return `<pre><code${langClass}>${highlighted}</code></pre>\n`
+    }
+    case 'blockquote': {
+      const innerHtml = node.children ? node.children.map((child) => renderBlock(child, options)).join('') : ''
+      return `<blockquote>\n${innerHtml}</blockquote>\n`
+    }
+    case 'callout': {
+      const style = node.style || 'note'
+      const title = style.charAt(0).toUpperCase() + style.slice(1)
+      const innerHtml = node.children ? node.children.map((child) => renderBlock(child, options)).join('') : ''
+      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('') : ''
+      return `<ul>\n${itemsHtml}</ul>\n`
+    }
+    case 'orderedList': {
+      const itemsHtml = node.items ? node.items.map((item) => `<li>${renderInline(item)}</li>\n`).join('') : ''
+      return `<ol>\n${itemsHtml}</ol>\n`
+    }
+    case 'table': {
+      const alignments = node.alignments || []
+      const rows = node.rows || []
+      if (rows.length === 0) return ''
+
+      const headerRow = rows[0]
+      const bodyRows = rows.slice(1)
+
+      const renderRow = (row, isHeader) => {
+        const cellTag = isHeader ? 'th' : 'td'
+        const cells = row
+          .map((cell, colIdx) => {
+            const align = alignments[colIdx] || 'default'
+            const alignAttr = align !== 'default' ? ` align="${align}"` : ''
+            return `<${cellTag}${alignAttr}>${renderInline(cell)}</${cellTag}>`
+          })
+          .join('')
+        return `<tr>${cells}</tr>\n`
+      }
+
+      let tableHtml = '<table>\n<thead>\n' + renderRow(headerRow, true) + '</thead>\n'
+      if (bodyRows.length > 0) {
+        tableHtml += '<tbody>\n' + bodyRows.map((r) => renderRow(r, false)).join('') + '</tbody>\n'
+      }
+      tableHtml += '</table>\n'
+      return tableHtml
+    }
+    case 'hr': {
+      return '<hr />\n'
+    }
+    default: {
+      return ''
+    }
+  }
+}
+
+module.exports = { renderBlock }

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

@@ -0,0 +1,48 @@
+const { escapeHtml } = require('./escape')
+
+const renderInline = (tokens) => {
+  if (!tokens) return ''
+  if (!Array.isArray(tokens)) return escapeHtml(tokens)
+
+  return tokens
+    .map((token) => {
+      if (!token) return ''
+      if (typeof token === 'string') return escapeHtml(token)
+
+      switch (token.type) {
+        case 'text':
+          return escapeHtml(token.value)
+        case 'bold':
+          return `<strong>${renderInline(token.children)}</strong>`
+        case 'italic':
+          return `<em>${renderInline(token.children)}</em>`
+        case 'strikethrough':
+          return `<del>${renderInline(token.children)}</del>`
+        case 'code':
+          return `<code>${escapeHtml(token.value)}</code>`
+        case 'link':
+          return `<a href="${escapeHtml(token.url)}">${renderInline(token.children)}</a>`
+        case 'wikilink':
+          return `<a href="${escapeHtml(token.target)}">${escapeHtml(token.display)}</a>`
+        case 'image': {
+          let styleAttr = ''
+          if (token.width || token.height) {
+            const styles = []
+            if (token.width) styles.push(`width: ${token.width}`)
+            if (token.height) styles.push(`height: ${token.height}`)
+            styleAttr = ` style="${styles.join('; ')};"`
+          }
+          return `<img src="${escapeHtml(token.url)}" alt="${escapeHtml(token.alt)}"${styleAttr} />`
+        }
+        case 'checkbox':
+          return `<input type="checkbox"${token.checked ? ' checked' : ''} disabled /> `
+        case 'br':
+          return '<br />'
+        default:
+          return escapeHtml(token.value || '')
+      }
+    })
+    .join('')
+}
+
+module.exports = { renderInline }

package/lib/markdown-to-html/slugify.js

@@ -0,0 +1,21 @@
+const slugify = (str, usedSlugs = new Set()) => {
+  let base = String(str || '')
+    .toLowerCase()
+    .replace(/<[^>]+>/g, '')
+    .replace(/[^\w\s-]/g, '')
+    .trim()
+    .replace(/\s+/g, '-')
+
+  if (!base) base = 'section'
+
+  let slug = base
+  let counter = 1
+  while (usedSlugs.has(slug)) {
+    slug = `${base}-${counter}`
+    counter++
+  }
+  usedSlugs.add(slug)
+  return slug
+}
+
+module.exports = { slugify }

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@sullux/markdown-html",
+  "version": "1.0.0",
+  "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>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Sullux/markdown.git",
+    "directory": "packages/markdown-html"
+  },
+  "bugs": {
+    "url": "https://github.com/Sullux/markdown/issues"
+  },
+  "homepage": "https://github.com/Sullux/markdown/tree/main/packages/markdown-html#readme",
+  "keywords": [
+    "markdown",
+    "html",
+    "compiler",
+    "converter",
+    "gfm",
+    "syntax-highlighting",
+    "bidirectional"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@sullux/markdown-compiler": "^1.0.0"
+  }
+}