{"name":"StackDraft Markdown-to-Substack compatibility dataset","version":"1.0","datePublished":"2026-07-10","url":"https://www.stackdraft.app/research/substack-markdown-compatibility","scope":"StackDraft preparation behavior. Destination-review cases are not asserted as universal Substack or email-client support.","methodology":["Use one focused Markdown input for each formatting or publishing-risk case.","Trace the current renderer, clipboard transformation, generated-asset, or publishing-warning path.","Classify the result as preserved, converted to an asset, flagged, or requiring destination review.","Keep the complete source fixture public so readers can repeat the workflow."],"summary":[{"status":"Preserved","count":9},{"status":"Converted to asset","count":2},{"status":"Flagged","count":7},{"status":"Destination review","count":2}],"cases":[{"id":"single-h1-title","feature":"Single H1 title","sourceExample":"# A practical post title","stackDraftResult":"Rendered as the document H1 and detected as the publication title.","publishingHandoff":"Copy title writes plain text; Copy body removes the first H1 to avoid a duplicate title.","status":"Preserved","evidence":"Clipboard title/body separation path"},{"id":"heading-hierarchy","feature":"H2 and H3 headings","sourceExample":"## Main section\n\n### Supporting section","stackDraftResult":"Rendered as structured H2 and H3 elements.","publishingHandoff":"Copied as rich-text headings; skipped levels trigger a separate warning.","status":"Preserved","evidence":"Markdown renderer and heading-level rule"},{"id":"emphasis","feature":"Bold and italic emphasis","sourceExample":"Use **bold** for a label and *italic* for light emphasis.","stackDraftResult":"Rendered as semantic strong and emphasis elements.","publishingHandoff":"Placed on the clipboard as rich inline formatting with a plain-text fallback.","status":"Preserved","evidence":"Markdown renderer output"},{"id":"links","feature":"Descriptive links","sourceExample":"Read the [publishing guide](https://www.stackdraft.app/guides).","stackDraftResult":"Rendered as an anchor with its destination intact.","publishingHandoff":"Copied as a rich-text link; the final public destination still needs a click test.","status":"Preserved","evidence":"Markdown renderer output"},{"id":"lists","feature":"Bulleted and numbered lists","sourceExample":"1. Draft\n2. Prepare\n3. Verify","stackDraftResult":"Rendered as structured ordered or unordered list markup.","publishingHandoff":"Copied as rich lists; deep nesting should be checked at phone width.","status":"Preserved","evidence":"Markdown renderer output"},{"id":"blockquote","feature":"Blockquotes","sourceExample":"> A concise quotation or callout.","stackDraftResult":"Rendered as a semantic blockquote.","publishingHandoff":"Copied as rich text rather than spacing-based indentation.","status":"Preserved","evidence":"Markdown renderer output"},{"id":"fenced-code","feature":"Fenced code with a language","sourceExample":"```ts\nconst ready = true\n```","stackDraftResult":"Rendered as a preformatted code block with syntax classes.","publishingHandoff":"Copied as a grouped code block; final line wrapping remains a destination check.","status":"Preserved","evidence":"Fenced-code renderer and syntax highlighting path"},{"id":"strikethrough","feature":"GFM strikethrough","sourceExample":"The ~~old step~~ revised step.","stackDraftResult":"Rendered using GitHub Flavored Markdown strikethrough.","publishingHandoff":"Copied as semantic deleted text in the rich body.","status":"Preserved","evidence":"GitHub Flavored Markdown renderer"},{"id":"horizontal-rule","feature":"Horizontal divider","sourceExample":"---","stackDraftResult":"Rendered as a horizontal rule.","publishingHandoff":"Copied as a structural divider rather than a row of literal hyphens.","status":"Preserved","evidence":"Markdown renderer output"},{"id":"gfm-table","feature":"Compact GFM table","sourceExample":"| Plan | Price |\n| --- | ---: |\n| Free | $0 |","stackDraftResult":"Rendered as a table in the preview.","publishingHandoff":"Copy body turns the table into a high-resolution PNG for a predictable email layout.","status":"Converted to asset","evidence":"Table-to-canvas clipboard conversion path"},{"id":"mermaid-diagram","feature":"Mermaid diagram","sourceExample":"```mermaid\nflowchart LR\n  Draft --> Review\n```","stackDraftResult":"Detected and rendered locally as a generated diagram asset.","publishingHandoff":"Prepared as PNG when browser rasterization succeeds, with an SVG fallback warning otherwise.","status":"Converted to asset","evidence":"Mermaid render and asset-generation path"},{"id":"wide-table","feature":"Table wider than five columns","sourceExample":"A GFM table containing six or more columns.","stackDraftResult":"Previewed normally and identified as likely to render poorly in email.","publishingHandoff":"Converted to an image, but the writer is told to simplify or split it first.","status":"Flagged","evidence":"wide-table publishing rule"},{"id":"local-image","feature":"Local image path","sourceExample":"![Architecture](./images/architecture.png)","stackDraftResult":"Rendered when locally resolvable and flagged as unavailable after paste.","publishingHandoff":"Writer must upload the image or replace the path with an appropriate public URL.","status":"Flagged","evidence":"local-image publishing rule"},{"id":"svg-image","feature":"SVG image","sourceExample":"![System diagram](https://example.com/system.svg)","stackDraftResult":"Rendered in preview and identified as an email-compatibility risk.","publishingHandoff":"Writer is advised to use PNG or JPEG for a more predictable email asset.","status":"Flagged","evidence":"svg-image publishing rule"},{"id":"missing-alt","feature":"Image without alt text","sourceExample":"![](https://example.com/chart.png)","stackDraftResult":"Rendered and flagged for missing alternative text.","publishingHandoff":"Writer is prompted to add a useful description before publishing.","status":"Flagged","evidence":"image-alt publishing rule"},{"id":"raw-html","feature":"Raw HTML","sourceExample":"<div class=\"custom-layout\">Content</div>","stackDraftResult":"Sanitized through the allowed HTML schema and flagged as destination-sensitive.","publishingHandoff":"Writer is advised to replace layout HTML with portable Markdown structures.","status":"Flagged","evidence":"HTML sanitizer and raw-html publishing rule"},{"id":"heading-jump","feature":"Skipped heading level","sourceExample":"## Section\n\n#### Detail","stackDraftResult":"Rendered and flagged because the outline jumps from H2 to H4.","publishingHandoff":"Writer is prompted to restore a logical heading hierarchy.","status":"Flagged","evidence":"heading-level publishing rule"},{"id":"long-code","feature":"Code block over 80 lines","sourceExample":"A fenced code block containing more than 80 lines.","stackDraftResult":"Rendered and flagged as too long for comfortable email reading.","publishingHandoff":"Writer is advised to trim the example or link to the complete source.","status":"Flagged","evidence":"long-code publishing rule"},{"id":"math","feature":"KaTeX math","sourceExample":"$$\\mathrm{CTR} = \\frac{clicks}{impressions}$$","stackDraftResult":"Rendered into KaTeX markup in the preview.","publishingHandoff":"Formula survival depends on destination sanitization and must be checked in the final draft and email.","status":"Destination review","evidence":"KaTeX render path; destination not asserted"},{"id":"remote-raster-image","feature":"Remote PNG or JPEG with alt text","sourceExample":"![Publishing workflow](https://example.com/workflow.png)","stackDraftResult":"Rendered with its URL and alternative text intact.","publishingHandoff":"Availability, upload behavior, dimensions, and final alt text must be confirmed in Substack.","status":"Destination review","evidence":"Image renderer path; destination not asserted"}]}