Skip to content

xberg-io/html-to-markdown / plugin/.cursor-plugin/skills/html-to-markdown-converting-html

html-to-markdown-converting-html

Verified

Use when converting HTML to Markdown, Djot, or plain text. Covers output formats, heading and code-block styles, lists, escaping, wrapping, and HTML preprocessing.

Converting HTML

Use this when the user wants to turn HTML into clean Markdown (or Djot) — a saved page, an HTML email body, a fragment, or a string. Conversion is driven by flags with a positional FILE (stdin is the default input when no file is given); the only subcommand is mcp (run-as-server, see the html-to-markdown-using-the-mcp-server skill).

Basic conversion

# File to stdout
html-to-markdown input.html

# File to a file
html-to-markdown input.html -o output.md

# From stdin
cat page.html | html-to-markdown
echo '<h1>Title</h1><p>Body</p>' | html-to-markdown

The default (no --json) prints plain Markdown text. Use --json only when you need structured metadata/tables (see the html-to-markdown-extracting-metadata and html-to-markdown-extracting-tables skills).

Output format

html-to-markdown input.html --output-format markdown   # default
html-to-markdown input.html --output-format djot        # Djot markup
html-to-markdown input.html -f djot                      # short form

To get plain text (no Markdown syntax), strip tags and treat blocks inline:

html-to-markdown input.html --convert-as-inline --strip-tags "script,style"

Heading and code-block styles

FlagValuesDefaultEffect
--heading-styleatx, underlined, atx-closedatx# h1 vs h1\n=== vs # h1 #
--code-block-stylebackticks, indented, tildesbackticksFence style for code blocks
--code-language / -lstring""Default language for fenced blocks
html-to-markdown input.html --heading-style underlined --code-block-style tildes

Lists and text formatting

# Bullet characters cycle by nesting depth; indent width 1–8
html-to-markdown input.html --bullets '*+-' --list-indent-width 2

# Indent with tabs instead of spaces
html-to-markdown input.html --list-indent-type tabs

# Emphasis symbol and escaping
html-to-markdown input.html --strong-em-symbol _ --escape-misc

Escaping flags (--escape-asterisks, --escape-underscores, --escape-misc, --escape-ascii) trade readability for strict CommonMark safety. Use --escape-ascii only when the output must round-trip through a strict parser.

Wrapping

html-to-markdown input.html --wrap --wrap-width 100   # off by default; 80 if --wrap with no width

Preprocessing (clean noisy pages)

Strip navigation, ads, and forms before converting — essential for scraped web pages:

html-to-markdown input.html --preprocess                     # standard preset
html-to-markdown input.html --preprocess --preset aggressive  # strip more
html-to-markdown input.html --preprocess --keep-navigation    # keep <nav>
html-to-markdown input.html --preprocess --keep-forms         # keep <form>

Presets: minimal, standard (default), aggressive. --preset, --keep-navigation, and --keep-forms all require --preprocess.

Programmatic equivalents

from html_to_markdown import convert, ConversionOptions, PreprocessingOptions

html = "<h1>Title</h1><p>Body text.</p>"
result = convert(
    html,
    ConversionOptions(
        heading_style="atx",
        code_block_style="backticks",
        wrap=True,
        wrap_width=100,
        preprocessing=PreprocessingOptions(enabled=True, preset="aggressive"),
    ),
)
print(result.content)
use html_to_markdown_rs::{convert, ConversionOptions, HeadingStyle};

let options = ConversionOptions::builder().heading_style(HeadingStyle::Atx).wrap(true).build();
let result = convert(html, Some(options))?;

See references/cli-reference.md for the full flag set and references/configuration.md for every option default.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall