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 `\x3Cp>paragraph tag\x3C/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
    \x3Ch1>Level 1\x3C/h1>
    \x3Ch2>Level 2\x3C/h2>

    \x3Cp>One sentence with a \x3Ca href="https://example.com">link\x3C/a>, and a HTML snippet like \x3Ccode><p>paragraph tag</p>\x3C/code>.\x3C/p>

    \x3Cul>
     \x3Cli>`ul` list item 1\x3C/li>
     \x3Cli>`ul` list item 2\x3C/li>
    \x3C/ul>

    \x3Col>
     \x3Cli>`ol` list item 1\x3C/li>
     \x3Cli>`ol` list item 2\x3C/li>
    \x3C/ol>

    \x3Ctable>
     \x3Cthead>
      \x3Ctr>
       \x3Cth>Table Item\x3C/th>
       \x3Cth>Description\x3C/th>
      \x3C/tr>
     \x3C/thead>
     \x3Ctbody>
      \x3Ctr>
       \x3Ctd>One\x3C/td>
       \x3Ctd>One is the spelling of the number `1`.\x3C/td>
      \x3C/tr>
      \x3Ctr>
       \x3Ctd>Two\x3C/td>
       \x3Ctd>Two is the spelling of the number `2`.\x3C/td>
      \x3C/tr>
     \x3C/tbody>
    \x3C/table>

    \x3Cpre>
     \x3Ccode>var one = 1;
     var two = 2;

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

Code Block Conversions

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

    ```markdown
    your code here
    ```

    ```html
    \x3Cpre>\x3Ccode class="language-md">
    your code here
    \x3C/code>\x3C/pre>
    ```

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

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

    ```markdown
      ```

      ```
      visible backticks
      ```

      ```
    ```

    ```html
      \x3Cpre>\x3Ccode>
      ```

      visible backticks

      ```
      \x3C/code>\x3C/pre>
    ```

Collapsed Section Conversions

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

    ```markdown
    \x3Cdetails>
    \x3Csummary>More info\x3C/summary>

    ### Header inside

    - Lists
    - **Formatting**
    - Code blocks

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

    \x3C/details>
    ```

    ```html
    \x3Cdetails>
    \x3Csummary>More info\x3C/summary>

    \x3Ch3>Header inside\x3C/h3>

    \x3Cul>
     \x3Cli>Lists\x3C/li>
     \x3Cli>\x3Cstrong>Formatting\x3C/strong>\x3C/li>
     \x3Cli>Code blocks\x3C/li>
    \x3C/ul>

    \x3Cpre>
     \x3Ccode class="language-js">console.log("Hello");\x3C/code>
    \x3C/pre>

    \x3C/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
    \x3Cp>This sentence uses \x3Ccode>$\x3C/code> delimiters to show math inline:
     \x3Cmath-renderer>\x3Cmath xmlns="http://www.w3.org/1998/Math/MathML">
      \x3Cmsqrt>\x3Cmn>3\x3C/mn>\x3Cmi>x\x3C/mi>\x3Cmo>−\x3C/mo>\x3Cmn>1\x3C/mn>\x3C/msqrt>
      \x3Cmo>+\x3C/mo>\x3Cmo>(\x3C/mo>\x3Cmn>1\x3C/mn>\x3Cmo>+\x3C/mo>\x3Cmi>x\x3C/mi>
      \x3Cmsup>\x3Cmo>)\x3C/mo>\x3Cmn>2\x3C/mn>\x3C/msup>
     \x3C/math>
    \x3C/math-renderer>
    \x3C/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
    \x3Cp>\x3Cstrong>The Cauchy-Schwarz Inequality\x3C/strong>\x3Cbr>
     \x3Cmath-renderer>
      \x3Cmath xmlns="http://www.w3.org/1998/Math/MathML">
       \x3Cmsup>
        \x3Cmrow>\x3Cmo>(\x3C/mo>
         \x3Cmunderover>\x3Cmo data-mjx-texclass="OP">∑\x3C/mo>
          \x3Cmrow>\x3Cmi>k\x3C/mi>\x3Cmo>=\x3C/mo>\x3Cmn>1\x3C/mn>\x3C/mrow>\x3Cmi>n\x3C/mi>
         \x3C/munderover>
         \x3Cmsub>\x3Cmi>a\x3C/mi>\x3Cmi>k\x3C/mi>\x3C/msub>
         \x3Cmsub>\x3Cmi>b\x3C/mi>\x3Cmi>k\x3C/mi>\x3C/msub>
         \x3Cmo>)\x3C/mo>
        \x3C/mrow>
        \x3Cmn>2\x3C/mn>
       \x3C/msup>
       \x3Cmo>≤\x3C/mo>
       \x3Cmrow>\x3Cmo>(\x3C/mo>
        \x3Cmunderover>\x3Cmo>∑\x3C/mo>
         \x3Cmrow>\x3Cmi>k\x3C/mi>\x3Cmo>=\x3C/mo>\x3Cmn>1\x3C/mn>\x3C/mrow>
         \x3Cmi>n\x3C/mi>
        \x3C/munderover>
        \x3Cmsubsup>\x3Cmi>a\x3C/mi>\x3Cmi>k\x3C/mi>\x3Cmn>2\x3C/mn>\x3C/msubsup>
        \x3Cmo>)\x3C/mo>
       \x3C/mrow>
       \x3Cmrow>\x3Cmo>(\x3C/mo>
         \x3Cmunderover>\x3Cmo>∑\x3C/mo>
          \x3Cmrow>\x3Cmi>k\x3C/mi>\x3Cmo>=\x3C/mo>\x3Cmn>1\x3C/mn>\x3C/mrow>
          \x3Cmi>n\x3C/mi>
         \x3C/munderover>
         \x3Cmsubsup>\x3Cmi>b\x3C/mi>\x3Cmi>k\x3C/mi>\x3Cmn>2\x3C/mn>\x3C/msubsup>
         \x3Cmo>)\x3C/mo>
       \x3C/mrow>
      \x3C/math>
     \x3C/math-renderer>\x3C/p>
    ```

Table Conversions

For more see tables-to-html.md

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

    ```html
    \x3Ctable>
     \x3Cthead>\x3Ctr>\x3Cth>First Header\x3C/th>\x3Cth>Second Header\x3C/th>\x3C/tr>\x3C/thead>
     \x3Ctbody>
      \x3Ctr>\x3Ctd>Content Cell\x3C/td>\x3Ctd>Content Cell\x3C/td>\x3C/tr>
      \x3Ctr>\x3Ctd>Content Cell\x3C/td>\x3Ctd>Content Cell\x3C/td>\x3C/tr>
     \x3C/tbody>
    \x3C/table>
    ```

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

    ```html
    \x3Ctable>
      \x3Cthead>
       \x3Ctr>
        \x3Cth align="left">Left-aligned\x3C/th>
        \x3Cth align="center">Center-aligned\x3C/th>
        \x3Cth align="right">Right-aligned\x3C/th>
       \x3C/tr>
      \x3C/thead>
      \x3Ctbody>
       \x3Ctr>
        \x3Ctd align="left">git status\x3C/td>
        \x3Ctd align="center">git status\x3C/td>
        \x3Ctd align="right">git status\x3C/td>
       \x3C/tr>
       \x3Ctr>
        \x3Ctd align="left">git diff\x3C/td>
        \x3Ctd align="center">git diff\x3C/td>
        \x3Ctd align="right">git diff\x3C/td>
       \x3C/tr>
      \x3C/tbody>
    \x3C/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

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

Troubleshooting

Working with pandoc

Prerequisites

• Pandoc installed (download from \x3Chttps://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: \x3Cp>Hello \x3Cem>pandoc\x3C/em>!\x3C/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

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

Troubleshooting

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\
\
This 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:

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

Troubleshooting

Working with jekyll

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

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

Configure markdown processor in _config.yml:

markdown: kramdown
kramdown:
  input: GFM
  syntax_highlighter: rouge

Troubleshooting

Working with hugo

Prerequisites

• Hugo installed (download from \x3Chttps://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

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

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

References

Writing and Styling Markdown

• basic-markdown.md
• code-blocks.md
• collapsed-sections.md
• tables.md
• writing-mathematical-expressions.md
• Markdown Guide: \x3Chttps://www.markdownguide.org/basic-syntax/>
• Styling Markdown: \x3Chttps://github.com/sindresorhus/github-markdown-css>

markedJS/marked

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

pandoc

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

gomarkdown/markdown

• Official documentation: \x3Chttps://pkg.go.dev/github.com/gomarkdown/markdown>
• Advanced configuration: \x3Chttps://pkg.go.dev/github.com/gomarkdown/[email protected]/html>
• Markdown processing: \x3Chttps://blog.kowalczyk.info/article/cxn3/advanced-markdown-processing-in-go.html>
• GitHub repository: \x3Chttps://github.com/gomarkdown/markdown>

jekyll

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

hugo

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