Substack Test Record — 2026-08-24
Verdict
Substack does not parse a pasted Markdown document. A browser-rendered rich paste is materially better and preserves ordinary article structure, but it is not publication-ready for tables, Markdown footnotes, math, Mermaid, local images, Obsidian syntax, or expandable HTML. Substack's native footnote and LaTeX controls work in an unpublished web/mobile preview, but rich paste does not map Markdown syntax to those native components.
The best first-version handoff is therefore rich HTML plus destination-specific warnings and repairs. Calling the output “one-click ready” would be inaccurate unless the product also converts fragile constructs into Substack-native blocks or safe replacements.
Environment and method
- Publication: temporary test publication
suke(sukejusu.substack.com). - Drafts: three new controlled, unpublished test drafts; no existing creator content was changed.
- Fixture:
docs/research/fixtures/markdown-portability-test-v1.md(3,876 characters at test time). - Raw mode: fixture dispatched to the editor as
text/plain. - Rich mode: fixture rendered by Marked 16.2.1 (
gfm: true,breaks: false) and dispatched with bothtext/htmlandtext/plainclipboard payloads. - Native mode: Substack editor controls were used to insert one footnote and one LaTeX block.
- Preview: unpublished mobile web preview only. No test email was sent and nothing was published.
Mode-level result
| Mode | Result | Measured evidence |
|---|---|---|
| Raw Markdown paste | Fail for formatting | 3,915 text characters became 102 paragraphs; 0 headings, lists, blockquotes, code blocks, tables, images, links, or dividers |
| Rich HTML paste | Partial | 1 H1, 17 H2, H3–H6, 12 list items, 2 blockquotes, 4 code blocks, 1 remote image and 7 links survived; 0 tables survived |
| Native blocks | Pass for tested footnote and block LaTeX | Both rendered in saved mobile preview after autosave |
| Email preview | Not tested | Sending email was intentionally outside this controlled test |
Raw Markdown paste
Raw paste retained readable source text but treated Markdown punctuation as literal content. This verifies the platform-level claim that full Markdown documents are not accepted by the editor.
| Case | Result | Repair required | Evidence |
|---|---|---|---|
| T01 inline formatting and links | Fail | Recreate all formatting and links | top |
| T02 heading hierarchy | Fail | Recreate headings | top |
| T03 lists and tasks | Fail | Recreate list structure and task state | top |
| T04 quote and divider | Fail | Recreate native quote/divider | top |
| T05 fenced code | Fail | Recreate code blocks | footnotes/math/code region |
| T06–T07 tables | Fail | Replace or rebuild outside the Markdown paste | tables |
| T08 images | Fail | Upload images manually | tables/images |
| T09 footnotes | Fail | Recreate with Substack Footnote control | footnotes |
| T10 math | Fail | Recreate with Substack LaTeX control | footnotes/math |
| T11 Mermaid | Fail | Render to an image or preserve as code | footnotes/math/code region |
| T12 Obsidian syntax | Fail | Resolve wiki links, transclusions and callouts before paste | Obsidian |
| T13 raw HTML | Fail | Replace with supported native content | Obsidian/HTML |
| T14 paragraphs and hard breaks | Partial | Paragraph separation remained, but Markdown hard-break intent was not reliably represented | Obsidian/HTML |
| T15 escaping | Partial | Literal text remained but backslashes were visible | raw tail |
| T16 heading anchor | Fail | Recreate link after headings exist | raw tail |
Rich HTML paste
The rich-paste result matched the saved mobile preview; it was not merely an editor-surface artifact.
| Case | Result | Observed behavior | Evidence |
|---|---|---|---|
| T01 inline formatting and links | Pass with caveat | Emphasis, strike, inline code, mailto and HTTPS links survived; relative links were rebound to the Substack publication path | top |
| T02 H1–H6 | Pass with caveat | H1–H6 survived; YAML front matter was incorrectly rendered as an extra H2 and divider by the generic renderer | top |
| T03 nested lists and tasks | Partial | Nested ordered/unordered lists survived; task checkboxes degraded to ordinary list items | top |
| T04 quote and divider | Pass | Quote and divider structure survived | top |
| T05 fenced and long-line code | Pass with review | Code blocks survived, but long-line mobile/email overflow still needs destination review | top |
| T06–T07 tables | Fail | Both tables were flattened into unstructured paragraphs; all table elements were removed | tables |
| T08 remote and local images | Partial | Remote image was imported and rewritten through Substack CDN; local relative image became IMAGE NOT FOUND |
tables/images |
| T09 Markdown footnotes | Fail | Reference syntax remained literal and an indented continuation became a code block; no native footnote nodes were created | footnotes |
| T10 inline/block math | Fail | $...$ and $$...$$ remained literal; no native LaTeX node was created |
footnotes/math |
| T11 Mermaid | Partial | Source survived as a code block but did not render as a diagram | footnotes/math |
| T12 Obsidian syntax | Fail | Wiki links and transclusions stayed literal; callout degraded to a quote containing [!NOTE] |
Obsidian |
| T13 raw HTML | Partial | <details> behavior was removed, summary/body became ordinary paragraphs, while <mark> highlighting survived |
Obsidian/HTML |
| T14 hard breaks and paragraphs | Pass | Hard break and paragraph separation survived | Obsidian/HTML |
| T15 escaping and literal characters | Pass | Escaped Markdown and Unicode rendered as intended | Obsidian/HTML |
| T16 heading anchor | Partial | Anchor link remained, but Substack rewrote it to the draft/preview URL and generated heading ID | preview |
Native controls
The current More menu visibly includes Code block, Divider, Footnote and LaTeX, but no table control.
| Construct | Available | Verified result | Evidence |
|---|---|---|---|
| Table | No visible native control | Not applicable | More menu |
| Code block | Yes | Availability verified; creation not repeated because rich paste already produced code blocks | More menu |
| Footnote | Yes | Native numbered anchor and footnote content rendered in mobile preview | editor, preview |
| Block LaTeX | Yes | \\int_0^1 x^2 \\, dx = \\frac{1}{3} rendered through the native MathJax block in mobile preview |
editor, preview |
| HTML/embed | No general HTML control in More |
Not tested | More menu |
Product implications
- A plain Markdown-to-rich-text converter handles common prose structure but leaves several high-friction constructs unresolved and is already commoditized.
- The differentiated checker must detect front matter, tables, Markdown footnotes, math, Mermaid, local images, relative links and Obsidian constructs before the user pastes.
- For Substack, safe automated repairs are: strip front matter, flatten or image-render tables with accessible fallback, upload/resolve images, convert Mermaid to image, and make relative links absolute.
- Native footnote and LaTeX conversion may require editor automation or an officially supported integration surface; until verified, the honest output is a repair checklist rather than a “one-click publish” promise.
- This single platform test already clears the strategic gate that destination behavior is meaningfully fragmented. Cross-platform demand still requires Beehiiv and preferably Ghost/Kit evidence before product code begins.
Cleanup
The three generated unpublished drafts (raw, rich and native-block tests) were permanently deleted after the screenshots and record were saved. Substack states this deletion cannot be undone. No content was published or emailed.
