markdown-to-html

Markdown to HTML Conversion

Expert skill for converting Markdown documents to HTML using the marked.js library, or writing data conversion scripts; in this case scripts similar to markedJS/marked repository. For custom scripts knowledge is not confined to marked.js, but data conversion methods are utilized from tools like pandoc and gomarkdown/markdown for data conversion; jekyll/jekyll and gohugoio/hugo for templating systems.

The conversion script or tool should handle single files, batch conversions, and advanced configurations.

When to Use This Skill

• User asks to "convert markdown to html" or "transform md files"
• User wants to "render markdown" as HTML output
• User needs to generate HTML documentation from .md files
• User is building static sites from Markdown content
• User is building template system that converts markdown to html
• User is working on a tool, widget, or custom template for an existing templating system
• User wants to preview Markdown as rendered HTML

Converting Markdown to HTML

Essential Basic Conversions

For more see basic-markdown-to-html.md

    ```markdown
    # Level 1
    ## Level 2

    One sentence with a [link](https://example.com), and a HTML snippet like `<p>paragraph tag</p>`.

    - `ul` list item 1
    - `ul` list item 2

    1. `ol` list item 1
    2. `ol` list item 1

    | Table Item | Description |
    | One | One is the spelling of the number `1`. |
    | Two | Two is the spelling of the number `2`. |

    ```js
    var one = 1;
    var two = 2;

    function simpleMath(x, y) {
     return x + y;
    }
    console.log(simpleMath(one, two));
    ```
    ```

    ```html
    <h1>Level 1</h1>
    <h2>Level 2</h2>

    <p>One sentence with a <a href="https://example.com">link</a>, and a HTML snippet like <code>&lt;p&gt;paragraph tag&lt;/p&gt;</code>.</p>

    <ul>
     <li>`ul` list item 1</li>
     <li>`ul` list item 2</li>
    </ul>

    <ol>
     <li>`ol` list item 1</li>
     <li>`ol` list item 2</li>
    </ol>

    <table>
     <thead>
      <tr>
       <th>Table Item</th>
       <th>Description</th>
      </tr>
     </thead>
     <tbody>
      <tr>
       <td>One</td>
       <td>One is the spelling of the number `1`.</td>
      </tr>
      <tr>
       <td>Two</td>
       <td>Two is the spelling of the number `2`.</td>
      </tr>
     </tbody>
    </table>

    <pre>
     <code>var one = 1;
     var two = 2;

     function simpleMath(x, y) {
      return x + y;
     }
     console.log(simpleMath(one, two));</code>
    </pre>
    ```

Code Block Conversions

For more see code-blocks-to-html.md

    ```markdown
    your code here
    ```

    ```html
    <pre><code class="language-md">
    your code here
    </code></pre>
    ```

    ```js
    console.log("Hello world");
    ```

    ```html
    <pre><code class="language-js">
    console.log("Hello world");
    </code></pre>
    ```

    ```markdown
      ```

      ```
      visible backticks
      ```

      ```
    ```

    ```html
      <pre><code>
      ```

      visible backticks

      ```
      </code></pre>
    ```

Collapsed Section Conversions

For more see collapsed-sections-to-html.md

    ```markdown
    <details>
    <summary>More info</summary>

    ### Header inside

    - Lists
    - **Formatting**
    - Code blocks

        ```js
        console.log("Hello");
        ```

    </details>
    ```

    ```html
    <details>
    <summary>More info</summary>

    <h3>Header inside</h3>

    <ul>
     <li>Lists</li>
     <li><strong>Formatting</strong></li>
     <li>Code blocks</li>
    </ul>

    <pre>
     <code class="language-js">console.log("Hello");</code>
    </pre>

    </details>
    ```

Mathematical Expression Conversions

For more see writing-mathematical-expressions-to-html.md

    ```markdown
    This sentence uses `$` delimiters to show math inline: $\sqrt{3x-1}+(1+x)^2$
    ```

    ```html
    <p>This sentence uses <code>$</code> delimiters to show math inline:
     <math-renderer><math xmlns="http://www.w3.org/1998/Math/MathML">
      <msqrt><mn>3</mn><mi>x</mi><mo>−</mo><mn>1</mn></msqrt>
      <mo>+</mo><mo>(</mo><mn>1</mn><mo>+</mo><mi>x</mi>
      <msup><mo>)</mo><mn>2</mn></msup>
     </math>
    </math-renderer>
    </p>
    ```

    ```markdown
    **The Cauchy-Schwarz Inequality**\
    $$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
    ```

    ```html
    <p><strong>The Cauchy-Schwarz Inequality</strong><br>
     <math-renderer>
      <math xmlns="http://www.w3.org/1998/Math/MathML">
       <msup>
        <mrow><mo>(</mo>
         <munderover><mo data-mjx-texclass="OP">∑</mo>
          <mrow><mi>k</mi><mo>=</mo><mn>1</mn></mrow><mi>n</mi>
         </munderover>
         <msub><mi>a</mi><mi>k</mi></msub>
         <msub><mi>b</mi><mi>k</mi></msub>
         <mo>)</mo>
        </mrow>
        <mn>2</mn>
       </msup>
       <mo>≤</mo>
       <mrow><mo>(</mo>
        <munderover><mo>∑</mo>
         <mrow><mi>k</mi><mo>=</mo><mn>1</mn></mrow>
         <mi>n</mi>
        </munderover>
        <msubsup><mi>a</mi><mi>k</mi><mn>2</mn></msubsup>
        <mo>)</mo>
       </mrow>
       <mrow><mo>(</mo>
         <munderover><mo>∑</mo>
          <mrow><mi>k</mi><mo>=</mo><mn>1</mn></mrow>
          <mi>n</mi>
         </munderover>
         <msubsup><mi>b</mi><mi>k</mi><mn>2</mn></msubsup>
         <mo>)</mo>
       </mrow>
      </math>
     </math-renderer></p>
    ```

Table Conversions

For more see tables-to-html.md

    ```markdown
    | First Header  | Second Header |
    | ------------- | ------------- |
    | Content Cell  | Content Cell  |
    | Content Cell  | Content Cell  |
    ```

    ```html
    <table>
     <thead><tr><th>First Header</th><th>Second Header</th></tr></thead>
     <tbody>
      <tr><td>Content Cell</td><td>Content Cell</td></tr>
      <tr><td>Content Cell</td><td>Content Cell</td></tr>
     </tbody>
    </table>
    ```

    ```markdown
    | Left-aligned | Center-aligned | Right-aligned |
    | :---         |     :---:      |          ---: |
    | git status   | git status     | git status    |
    | git diff     | git diff       | git diff      |
    ```

    ```html
    <table>
      <thead>
       <tr>
        <th align="left">Left-aligned</th>
        <th align="center">Center-aligned</th>
        <th align="right">Right-aligned</th>
       </tr>
      </thead>
      <tbody>
       <tr>
        <td align="left">git status</td>
        <td align="center">git status</td>
        <td align="right">git status</td>
       </tr>
       <tr>
        <td align="left">git diff</td>
        <td align="center">git diff</td>
        <td align="right">git diff</td>
       </tr>
      </tbody>
    </table>
    ```

Working with markedJS/marked

Prerequisites

• Node.js installed (for CLI or programmatic usage)
• Install marked globally for CLI: npm install -g marked
• Or install locally: npm install marked

Quick Conversion Methods

See marked.md Quick Conversion Methods

Step-by-Step Workflows

See marked.md Step-by-Step Workflows

CLI Configuration

Using Config Files

Create ~/.marked.json for persistent options:

{
  "gfm": true,
  "breaks": true
}

Or use a custom config:

marked -i input.md -o output.html -c config.json

CLI Options Reference

Option	Description
-i, --input <file>	Input Markdown file
-o, --output <file>	Output HTML file
-s, --string <string>	Parse string instead of file
-c, --config <file>	Use custom config file
--gfm	Enable GitHub Flavored Markdown
--breaks	Convert newlines to <br>
--help	Show all options

Security Warning

⚠️ Marked does NOT sanitize output HTML. For untrusted input, use a sanitizer:

import { marked } from 'marked';
import DOMPurify from 'dompurify';

const unsafeHtml = marked.parse(untrustedMarkdown);
const safeHtml = DOMPurify.sanitize(unsafeHtml);

Recommended sanitizers:

• DOMPurify (recommended)
• sanitize-html
• js-xss

Supported Markdown Flavors

Flavor	Support
Original Markdown	100%
CommonMark 0.31	98%
GitHub Flavored Markdown	97%

Troubleshooting

Issue	Solution
Special characters at file start	Strip zero-width chars: content.replace(/^[\u200B\u200C\u200D\uFEFF]/,"")
Code blocks not highlighting	Add a syntax highlighter like highlight.js
Tables not rendering	Ensure gfm: true option is set
Line breaks ignored	Set breaks: true in options
XSS vulnerability concerns	Use DOMPurify to sanitize output

Working with pandoc

Prerequisites

• Pandoc installed (download from https://pandoc.org/installing.html)
• For PDF output: LaTeX installation (MacTeX on macOS, MiKTeX on Windows, texlive on Linux)
• Terminal/command prompt access

Quick Conversion Methods

Method 1: CLI Basic Conversion

# Convert markdown to HTML
pandoc input.md -o output.html

# Convert with standalone document (includes header/footer)
pandoc input.md -s -o output.html

# Explicit format specification
pandoc input.md -f markdown -t html -s -o output.html

Method 2: Filter Mode (Interactive)

# Start pandoc as a filter
pandoc

# Type markdown, then Ctrl-D (Linux/macOS) or Ctrl-Z+Enter (Windows)
Hello *pandoc*!
# Output: <p>Hello <em>pandoc</em>!</p>

Method 3: Format Conversion

# HTML to Markdown
pandoc -f html -t markdown input.html -o output.md

# Markdown to LaTeX
pandoc input.md -s -o output.tex

# Markdown to PDF (requires LaTeX)
pandoc input.md -s -o output.pdf

# Markdown to Word
pandoc input.md -s -o output.docx

CLI Configuration

Option	Description
-f, --from <format>	Input format (markdown, html, latex, etc.)
-t, --to <format>	Output format (html, latex, pdf, docx, etc.)
-s, --standalone	Produce standalone document with header/footer
-o, --output <file>	Output file (inferred from extension)
--mathml	Convert TeX math to MathML
--metadata title="Title"	Set document metadata
--toc	Include table of contents
--template <file>	Use custom template
--help	Show all options

Security Warning

⚠️ Pandoc processes input faithfully. When converting untrusted markdown:

• Use --sandbox mode to disable external file access
• Validate input before processing
• Sanitize HTML output if displayed in browsers

# Run in sandbox mode for untrusted input
pandoc --sandbox input.md -o output.html

Supported Markdown Flavors

Flavor	Support
Pandoc Markdown	100% (native)
CommonMark	Full (use -f commonmark)
GitHub Flavored Markdown	Full (use -f gfm)
MultiMarkdown	Partial

Troubleshooting

Issue	Solution
PDF generation fails	Install LaTeX (MacTeX, MiKTeX, or texlive)
Encoding issues on Windows	Run chcp 65001 before using pandoc
Missing standalone headers	Add -s flag for complete documents
Math not rendering	Use --mathml or --mathjax option
Tables not rendering	Ensure proper table syntax with pipes and dashes

Working with gomarkdown/markdown

Prerequisites

• Go 1.18 or higher installed
• Install the library: go get github.com/gomarkdown/markdown
• For CLI tool: go install github.com/gomarkdown/mdtohtml@latest

Quick Conversion Methods

Method 1: Simple Conversion (Go)

package main

import (
    "fmt"
    "github.com/gomarkdown/markdown"
)

func main() {
    md := []byte("# Hello World\n\nThis is **bold** text.")
    html := markdown.ToHTML(md, nil, nil)
    fmt.Println(string(html))
}

Method 2: CLI Tool

# Install mdtohtml
go install github.com/gomarkdown/mdtohtml@latest

# Convert file
mdtohtml input.md output.html

# Convert file (output to stdout)
mdtohtml input.md

Method 3: Custom Parser and Renderer

package main

import (
    "github.com/gomarkdown/markdown"
    "github.com/gomarkdown/markdown/html"
    "github.com/gomarkdown/markdown/parser"
)

func mdToHTML(md []byte) []byte {
    // Create parser with extensions
    extensions := parser.CommonExtensions | parser.AutoHeadingIDs | parser.NoEmptyLineBeforeBlock
    p := parser.NewWithExtensions(extensions)
    doc := p.Parse(md)

    // Create HTML renderer with extensions
    htmlFlags := html.CommonFlags | html.HrefTargetBlank
    opts := html.RendererOptions{Flags: htmlFlags}
    renderer := html.NewRenderer(opts)

    return markdown.Render(doc, renderer)
}

CLI Configuration

The mdtohtml CLI tool has minimal options:

mdtohtml input-file [output-file]

For advanced configuration, use the Go library programmatically with parser and renderer options:

Parser Extension	Description
parser.CommonExtensions	Tables, fenced code, autolinks, strikethrough, etc.
parser.AutoHeadingIDs	Generate IDs for headings
parser.NoEmptyLineBeforeBlock	No blank line needed before blocks
parser.MathJax	MathJax support for LaTeX math

HTML Flag	Description
html.CommonFlags	Common HTML output flags
html.HrefTargetBlank	Add target="_blank" to links
html.CompletePage	Generate complete HTML page
html.UseXHTML	Generate XHTML output

Security Warning

⚠️ gomarkdown does NOT sanitize output HTML. For untrusted input, use Bluemonday:

import (
    "github.com/microcosm-cc/bluemonday"
    "github.com/gomarkdown/markdown"
)

maybeUnsafeHTML := markdown.ToHTML(md, nil, nil)
html := bluemonday.UGCPolicy().SanitizeBytes(maybeUnsafeHTML)

Recommended sanitizer: Bluemonday

Supported Markdown Flavors

Flavor	Support
Original Markdown	100%
CommonMark	High (with extensions)
GitHub Flavored Markdown	High (tables, fenced code, strikethrough)
MathJax/LaTeX Math	Supported via extension
Mmark	Suppor

...