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](references/basic-markdown-to-html.md)

# Level 1

## Level 2

One sentence with a link, 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. |

    var one = 1;
    var two = 2;

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

<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](references/code-blocks-to-html.md)

your code here

<pre><code class="language-md">

your code here

</code></pre>

console.log("Hello world");

<pre><code class="language-js">

console.log("Hello world");

</code></pre>

visible backticks

<pre><code>

      visible backticks

</code></pre>

Collapsed Section Conversions

For more see [collapsed-sections-to-html.md](references/collapsed-sections-to-html.md)

<details>

<summary>More info</summary>

### Header inside

• Lists
• Formatting
• Code blocks

        console.log("Hello");

</details>

<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](references/writing-mathematical-expressions-to-html.md)

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

<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>

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)$$

<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](references/tables-to-html.md)

| First Header | Second Header |

| ------------- | ------------- |

| Content Cell | Content Cell |

| Content Cell | Content Cell |

<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>

| Left-aligned | Center-aligned | Right-aligned |

| :--- | :---: | ---: |

| git status | git status | git status |

| git diff | git diff | git diff |

<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](references/marked.md)

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](references/marked.md) Quick Conversion Methods

Step-by-Step Workflows

See [marked.md](references/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](references/pandoc.md)

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](references/gomarkdown.md)

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 | Supported |

Troubleshooting

| Issue | Solution |

|-------|----------|

| Windows/Mac newlines not parsed | Use parser.NormalizeNewlines(input) |

| Tables not rendering | Enable parser.Tables extension |

| Code blocks without highlighting | Integrate with syntax highlighter like Chroma |

| Math not rendering | Enable parser.MathJax extension |

| XSS vulnerabilities | Use Bluemonday to sanitize output |

Working with [jekyll](references/jekyll.md)

Prerequisites

• Ruby version 2.7.0 or higher
• RubyGems
• GCC and Make (for native extensions)
• Install Jekyll and Bundler: gem install jekyll bundler

Quick Conversion Methods

Method 1: Create New Site

# Create a new Jekyll site
jekyll new myblog

# Change to site directory
cd myblog

# Build and serve locally
bundle exec jekyll serve

# Access at http://localhost:4000

Method 2: Build Static Site

# Build site to _site directory
bundle exec jekyll build

# Build with production environment
JEKYLL_ENV=production bundle exec jekyll build

Method 3: Live Reload Development

# Serve with live reload
bundle exec jekyll serve --livereload

# Serve with drafts
bundle exec jekyll serve --drafts

CLI Configuration

| Command | Description |

|---------|-------------|

| jekyll new <path> | Create new Jekyll site |

| jekyll build | Build site to _site directory |

| jekyll serve | Build and serve locally |

| jekyll clean | Remove generated files |

| jekyll doctor | Check for configuration issues |

| Serve Options | Description |

|---------------|-------------|

| --livereload | Reload browser on changes |

| --drafts | Include draft posts |

| --port <port> | Set server port (default: 4000) |

| --host <host> | Set server host (default: localhost) |

| --baseurl <url> | Set base URL |

Security Warning

⚠️ Jekyll security considerations:

• Avoid using safe: false in production
• Use exclude in _config.yml to prevent sensitive files from being published
• Sanitize user-generated content if accepting external input
• Keep Jekyll and plugins updated

# _config.yml security settings
exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - vendor

Supported Markdown Flavors

| Flavor | Support |

|--------|---------|

| Kramdown (default) | 100% |

| CommonMark | Via plugin (jekyll-commonmark) |

| GitHub Flavored Markdown | Via plugin (jekyll-commonmark-ghpages) |

| RedCarpet | Via plugin (deprecated) |

Configure markdown processor in _config.yml:

markdown: kramdown
kramdown:
  input: GFM
  syntax_highlighter: rouge

Troubleshooting

| Issue | Solution |

|-------|----------|

| Ruby 3.0+ fails to serve | Run bundle add webrick |

| Gem dependency errors | Run bundle install |

| Slow builds | Use --incremental flag |

| Liquid syntax errors | Check for unescaped { in content |

| Plugin not loading | Add to _config.yml plugins list |

Working with [hugo](references/hugo.md)

Prerequisites

• Hugo installed (download from <https://gohugo.io/installation/>)
• Git (recommended for themes and modules)
• Go (optional, for Hugo Modules)

Quick Conversion Methods

Method 1: Create New Site

# Create a new Hugo site
hugo new site mysite

# Change to site directory
cd mysite

# Add a theme
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke
echo "theme = 'ananke'" >> hugo.toml

# Create content
hugo new content posts/my-first-post.md

# Start development server
hugo server -D

Method 2: Build Static Site

# Build site to public directory
hugo

# Build with minification
hugo --minify

# Build for specific environment
hugo --environment production

Method 3: Development Server

# Start server with drafts
hugo server -D

# Start with live reload and bind to all interfaces
hugo server --bind 0.0.0.0 --baseURL http://localhost:1313/

# Start with specific port
hugo server --port 8080

CLI Configuration

| Command | Description |

|---------|-------------|

| hugo new site <name> | Create new Hugo site |

| hugo new content <path> | Create new content file |

| hugo | Build site to public directory |

| hugo server | Start development server |

| hugo mod init | Initialize Hugo Modules |

| Build Options | Description |

|---------------|-------------|

| -D, --buildDrafts | Include draft content |

| -E, --buildExpired | Include expired content |

| -F, --buildFuture | Include future-dated content |

| --minify | Minify output |

| --gc | Run garbage collection after build |

| -d, --destination <path> | Output directory |

| Server Options | Description |

|----------------|-------------|

| --bind <ip> | Interface to bind to |

| -p, --port <port> | Port number (default: 1313) |

| --liveReloadPort <port> | Live reload port |

| --disableLiveReload | Disable live reload |

| --navigateToChanged | Navigate to changed content |

Security Warning

⚠️ Hugo security considerations:

• Configure security policy in hugo.toml for external commands
• Use --enableGitInfo carefully with public repositories
• Validate shortcode parameters for user-generated content

# hugo.toml security settings
[security]
  enableInlineShortcodes = false
  [security.exec]
    allow = ['^go$', '^npx$', '^postcss$']
  [security.funcs]
    getenv = ['^HUGO_', '^CI$']
  [security.http]
    methods = ['(?i)GET|POST']
    urls = ['.*']

Supported Markdown Flavors

| Flavor | Support |

|--------|---------|

| Goldmark (default) | 100% (CommonMark compliant) |

| GitHub Flavored Markdown | Full (tables, strikethrough, autolinks) |

| CommonMark | 100% |

| Blackfriday (legacy) | Deprecated, not recommended |

Configure markdown in hugo.toml:

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      definitionList = true
      footnote = true
      linkify = true
      strikethrough = true
      table = true
      taskList = true
    [markup.goldmark.renderer]
      unsafe = false  # Set true to allow raw HTML

Troubleshooting

| Issue | Solution |

|-------|----------|

| "Page not found" on paths | Check baseURL in config |

| Theme not loading | Verify theme in themes/ or Hugo Modules |

| Slow builds | Use --templateMetrics to identify bottlenecks |

| Raw HTML not rendering | Set unsafe = true in goldmark config |

| Images not loading | Check static/ folder structure |

| Module errors | Run hugo mod tidy |

References

Writing and Styling Markdown

• [basic-markdown.md](references/basic-markdown.md)
• [code-blocks.md](references/code-blocks.md)
• [collapsed-sections.md](references/collapsed-sections.md)
• [tables.md](references/tables.md)
• [writing-mathematical-expressions.md](references/writing-mathematical-expressions.md)
• Markdown Guide: <https://www.markdownguide.org/basic-syntax/>
• Styling Markdown: <https://github.com/sindresorhus/github-markdown-css>

[markedJS/marked](references/marked.md)

• Official documentation: <https://marked.js.org/>
• Advanced options: <https://marked.js.org/using_advanced>
• Extensibility: <https://marked.js.org/using_pro>
• GitHub repository: <https://github.com/markedjs/marked>

[pandoc](references/pandoc.md)

• Getting started: <https://pandoc.org/getting-started.html>
• Official documentation: <https://pandoc.org/MANUAL.html>
• Extensibility: <https://pandoc.org/extras.html>
• GitHub repository: <https://github.com/jgm/pandoc>

[gomarkdown/markdown](references/gomarkdown.md)

• Official documentation: <https://pkg.go.dev/github.com/gomarkdown/markdown>
• Advanced configuration: <https://pkg.go.dev/github.com/gomarkdown/markdown@v0.0.0-20250810172220-2e2c11897d1a/html>
• Markdown processing: <https://blog.kowalczyk.info/article/cxn3/advanced-markdown-processing-in-go.html>
• GitHub repository: <https://github.com/gomarkdown/markdown>

[jekyll](references/jekyll.md)

• Official documentation: <https://jekyllrb.com/docs/>
• Configuration options: <https://jekyllrb.com/docs/configuration/options/>
• Plugins: <https://jekyllrb.com/docs/plugins/>
• Installation
• Generators
• Converters
• Commands
• Tags
• Filters
• Hooks
• GitHub repository: <https://github.com/jekyll/jekyll>

[hugo](references/hugo.md)

• Official documentation: <https://gohugo.io/documentation/>
• All Settings: <https://gohugo.io/configuration/all/>
• Editor Plugins: <https://gohugo.io/tools/editors/>
• GitHub repository: <https://github.com/gohugoio/hugo>