Substack for Technical Writers: Code, Tables, Diagrams, and Write-Ups
Substack started as a home for essays, but more and more technical writers publish there: engineers, security researchers, data scientists, and quants. The editor handles some technical content well and some not at all.
One security writer tried Substack for CTF write-ups and noticed it supports “code blocks or inline code, but not a basic table.” Another technical writer called the lack of inline LaTeX “by far the worst limitation for technical writers.”
Here’s a map of what works. The paste itself is a DownStack step.
Paste the Markdown through DownStack
Most technical writers already draft in Markdown, in an editor, in a repo, or in Obsidian. Substack’s editor doesn’t accept that Markdown, and copying rendered HTML from elsewhere loses tables. DownStack is the handoff: paste, preview, one click.
- Draft in Markdown with fenced code blocks, tables, headings, and, if you use them, Mermaid diagrams.
- Paste the Markdown into the DownStack editor.
- Check the preview. Code stays code, and tables show as tables so you can confirm the columns.
- Click Copy for Substack. That click draws each table as a hosted image and, for a Mermaid block, swaps in a diagram image from the public mermaid.ink service. Paste into Substack and finish there: buttons, footnotes, the paywall, and any display equations.
DownStack does not convert math. Use Substack’s LaTeX block for key equations and Unicode for simple inline expressions. See LaTeX and math in Substack.
If the draft is in ChatGPT, the DownStack app converts the Markdown and tables inside the chat and does not publish the post. It does not render Mermaid. Table images from the app are kept for 90 days, so run the version you publish through the editor and use Copy for Substack.
What Substack Handles Well
- Code blocks for multi-line snippets, with monospace formatting.
- Inline code for function names, flags, and file paths.
- Headings, lists, and blockquotes for structure.
- Images for screenshots and diagrams.
- A LaTeX block for display equations.
Where It Falls Short
| Need | Substack support | Workaround |
|---|---|---|
| Tables | No table block | DownStack renders each Markdown table as a hosted image |
| Inline math | Not supported | Unicode, inline code, or display LaTeX. DownStack does not convert math |
| Diagrams | No native diagrams | A Mermaid block in the DownStack editor becomes an image |
| Markdown paste | Pasted as literal text | Paste into DownStack, then Copy for Substack |
What to check before you copy
Tables
Results tables, benchmark comparisons, and option matrices are where technical posts break most often. Write them in normal Markdown table syntax:
| Approach | p50 latency | p99 latency |
|:-----------|------------:|------------:|
| Baseline | 42 ms | 310 ms |
| With cache | 18 ms | 95 ms |Right-align numeric columns with ---: so digits line up. For more, see how to format tables in Substack and data tables and charts in Substack.
Diagrams with Mermaid
In the DownStack editor, a Mermaid code block is replaced with a diagram image from mermaid.ink when you copy. That image is what you paste into Substack:
graph LR
A[Draft in Markdown] --> B[DownStack]
B --> C[Paste into Substack]Keep diagrams simple. They’re read on phones.
Code
Keep code blocks short and focused on the lines that matter, and link to the full source in a repo or gist. Long code blocks are hard to read in email, and readers on mobile will scroll sideways. Our code blocks guide covers formatting details.
A Template for Technical Posts
- TL;DR: the result in two sentences.
- Context: the problem and why it matters.
- Approach: what you tried, with short code snippets.
- Results: a table or chart, plus one sentence on what it means.
- Caveats: what didn’t work and what you’d do next.
- Links: repo, data, references.
More structures are in Substack post structure templates.
Key Takeaways
- Substack handles code blocks, inline code, and display LaTeX. It lacks tables, inline math, and native diagrams.
- Paste the Markdown into DownStack and click Copy for Substack. Tables become hosted images, and Mermaid blocks become diagram images.
- The ChatGPT app converts Markdown and tables in the chat. It does not render Mermaid, and those table images last 90 days, so publish from the editor.
- Keep code short, link to full source, and test every post on a phone.