Convert a blog HTML library to a Markdown (Obsidian) vault

Convert a blog HTML library to a Markdown (Obsidian) vault

Mirror a folder of generated .html blogs into a parallel Markdown tree so the same content can be read and managed in Obsidian. The blog-library skill serves the HTML in a web UI; this skill produces plain .md files instead, for users who prefer a Markdown editor.

How it works

Run the bundled converter — it walks the input directory, mirrors the topic folders into <dir>-md/, converts each blog .html to .md, and copies the frame-image folders. Inside each topic bucket (a folder where every blog .html has a same-named sibling image folder — what full-blog produces under e.g. 05-anthropic-devday/), the converter reorganizes the output so blogs are easy to navigate:

<dir>-md/<topic>/
├── blogs/                   ← all blog .md files
│   ├── 01. <Title A>.md
│   ├── 02. <Title B>.md
│   └── …
└── images/                  ← matching image folders
    ├── 01. <Title A>/
    ├── 02. <Title B>/
    └── …

Topic folders that don't look like blog buckets — EPUB exports under EPUBs-html/, for instance, where chapters are lone .html with no paired image folder — are mirrored verbatim with the original numbering.

python3 "${CLAUDE_PLUGIN_ROOT}/skills/html-to-markdown/scripts/html_to_md.py" "<BLOGS_DIR>" [--out-dir DIR]

• Sequential NN. numbering is reassigned per bucket from the alphabetical order of the title (the existing NN. prefix is stripped first). A bucket whose source comes out all 01. flattens to 01..NN; an already well-numbered bucket stays in the same order.
• Image refs rewritten: each .md's ![…](<old-stem>/…) becomes ![…](../images/<new-stem>/…), percent-encoded the same way html_to_md emits them — a single deterministic prefix swap, so alt-text and other encoded content is untouched.
• Self-contained vault. All images live under the topic's images/, so relative links resolve in Obsidian. Open <dir>-md/ directly as a vault.
• Body only. Only the article body (div.post-body from full-blog's render_html) is converted; the site chrome (top bar, footer) is dropped. The blog title and source URL are lifted into YAML frontmatter.
• Standard library + BeautifulSoup only (bs4, already a full-blog dep).
• Pass --no-organize to opt out and mirror the input layout verbatim.

Steps

1. Pick the directory of blogs (the full-blog --out-dir).
2. Run the converter. Default output is a sibling <dir>-md/; override with --out-dir. It prints one line per converted file (use --quiet for just the summary) and a final markdown=… images_copied=… failed=… tally.
3. Report the output path and tell the user to open it as an Obsidian vault.

What the conversion produces

• Frontmatter: title and source (the YouTube URL), then a visible # Title.
• Paragraphs / headings: <p>→prose, <h2>/<h3>→##/###. The lead paragraph's drop-cap is visual-only and renders as normal prose.
• Figures: ![alt](image) followed by an italic caption line with a [▶ M:SS](youtube-deeplink) jump link. figure-row galleries (a CSS-only side-by-side layout) simply stack as consecutive images in Markdown.
• Lists / blockquotes / inline code, links, bold, italic are preserved.
• <hr class="divider"> → ---; the trailing "Additional frames" section becomes a ## Additional frames heading.

Notes

• Image paths are percent-encoded (decode-then-encode, so already-encoded paths aren't double-encoded). Spaces/Hangul in folder names become %20…, which Obsidian and any CommonMark renderer decode to find the local file. Raw spaces would otherwise truncate a ![]() link.
• Idempotent: re-running overwrites the mirror. Blogs deleted upstream are NOT pruned — delete the -md/ dir and re-run for a clean mirror.
• One unreadable HTML file is reported as FAIL and skipped; the run continues.
• Korean/translated blogs convert identically — the parser is content-agnostic.

Resources

• scripts/html_to_md.py — the standalone converter (run it).