markdown-to-html（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

# 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><p>paragraph tag</p></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

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

<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

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

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

<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

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

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

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

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: https://www.markdownguide.org/basic-syntax/
• Styling Markdown: https://github.com/sindresorhus/github-markdown-css

markedJS/marked

• 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

• 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

• 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

• 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

• 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