# Md To Substack > md-to-substack: Convert Markdown to Substack-publishable HTML - Skill: `manan-buddhadev/md-to-substack` (Agent Skill) - Install (CLI): `npx skillmds@latest add manan-buddhadev/md-to-substack` - Raw SKILL.md: https://api.skillmd.com/api/skills/manan-buddhadev/md-to-substack/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: manan-buddhadev (https://skillmd.com/u/manan-buddhadev) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/manan-buddhadev/md-to-substack --- # md-to-substack: Convert Markdown to Substack-publishable HTML Convert a `.md` file into an `.html` file optimized for Substack's rich text editor, based on the conversion rules used by https://md-to-substack.netlify.app (github.com/simpolism/md-to-substack). ## How to invoke ``` /md-to-substack ``` Example: ``` /md-to-substack BLOG.md /md-to-substack /Users/manan/Vibes/website-revamp/BLOG.md ``` ## What you do 1. Read the input `.md` file 2. Convert it to Substack-compatible HTML (rules below) 3. Wrap in a minimal HTML shell for browser rendering 4. Write the output as `-substack.html` in the same directory 5. Tell the user how to use it --- ## Conversion rules ### Element ordering (critical) **The `

` MUST be the first element.** Substack uses the first heading as the post title. Any content before it (series callouts, blockquotes) gets treated as the title instead. If the markdown has a callout or series line before the `# Title`, move it to immediately after the H1 in the HTML output. ### Headings ``` # Title →

Title

## Section →

Section

### Sub →

Sub

``` No custom classes needed — Substack's editor reads standard HTML heading tags. ### Series/callout blockquote (the `> **Label** · ...` pattern) Move after H1. Use `` for the label, normal text for the rest. No `` wrapper: ```html
Building with Claude · Part 1 of an ongoing series ...
``` ### Paragraphs Each block of text becomes a standard `
`: ```html
text here
``` Substack's editor respects paragraph breaks on paste. ### Line breaks within paragraphs Single line breaks in markdown → `
` inside the `
`. For better Substack compatibility, convert `
` to separate `
` tags (the "extra spacing" behavior from the tool): ``` Line one\nLine two →
Line one
Line two
``` ### Bold and italic ``` **text** → text *text* → text ``` ### Inline code ``` `code` → code ``` ### Links **Always add `target="_blank"`** — Substack requires links to open in new tabs: ``` [text](url) → text ``` ### Code blocks ```html
...code content here...
``` Strip the language hint (` ```js `, ` ```jsx `, etc.) from the opening fence line. Escape HTML entities inside code blocks: - `<` → `<` - `>` → `>` - `&` → `&` ### Blockquotes ``` > text →
text
``` ### Horizontal rules ``` --- →
``` Substack renders `
` as a section divider. ### Unordered lists ```html

item one

item two

``` ### Ordered lists ```html

item one

item two

``` ### Smart quotes Convert straight quotes to curly quotes (the tool enables this by default via marked-smartypants): ``` "text" → "text" 'text' → 'text' ``` Do NOT apply smart quotes inside `` or `` blocks. --- ## Output HTML shell ```html [converted content here] ``` The design mirrors the tool's NYT-inspired editorial style (Helvetica Neue for UI/headers, Times New Roman for body). --- ## Do not include HTML comments Comments with `--` in their syntax (``) can leak into clipboard paste in some browsers. Omit all comments from the output HTML. --- ## Instructions to give the user after writing the file ``` Done. Output written to: -substack.html To publish on Substack: 1. Open -substack.html in your browser → open -substack.html 2. Cmd+A to select all, Cmd+C to copy 3. Go to your Substack draft and paste (Cmd+V) Notes: - Code blocks need a manual step: Substack doesn't preserve on paste. For each code block, delete what pasted and use Substack's code block button instead. - Links will open in new tabs (target="_blank" is set). - Smart quotes are applied automatically. ```