How to Add Code Blocks to Substack Without Breaking the Layout

Choose inline code or a code block

Substack’s editors expose code formatting, but the most portable source is still semantic Markdown. Backticks describe the role of the text without carrying an IDE theme, font, or background into the publishing workflow.

Write a portable fenced code block

Put three backticks on their own lines and add a recognized language label immediately after the opening fence. The label helps a Markdown renderer choose syntax highlighting; it is not part of the code readers copy.

```ts
export function canonicalUrl(pathname: string) {
  return new URL(pathname, "https://www.stackdraft.app").toString()
}
```

Move Markdown code into Substack

1. 01

   Reduce the example

   Delete setup and output that do not support the article’s point. Prefer one focused example over a full production file.

2. 02

   Wrap long expressions intentionally

   Break chains, arrays, commands, and object literals at meaningful boundaries. Email readers should not need to discover the important token by scrolling sideways.

3. 03

   Render the Markdown

   Load the draft in StackDraft and confirm the code appears as a distinct preformatted block. Long blocks trigger a publishing warning.

4. 04

   Copy the prepared body

   Paste the rich-text result into the desktop Substack editor and confirm the code remains grouped as one block.

5. 05

   Test copy and mobile behavior

   Open the test email on a phone, follow the explanation around the code, and copy a representative line if copying is part of the reader task.

Edit code for readers, not for the repository

• Introduce what the example proves before showing it.
• Keep lines near a narrow reading width when the language permits it.
• Use comments to explain intent or omitted context, not obvious syntax.
• Replace long generated IDs and payloads with clearly marked placeholders.
• Show relevant error lines instead of an entire stack trace.
• Put installation commands and application code in separate blocks.
• Link to the tested full source when exact reproduction matters.

Avoid screenshots for code readers need to use

A code screenshot can preserve a visual theme, but it prevents selection, makes zooming necessary, and is difficult for assistive technology. Use real code text for instructions and examples. Reserve images for explaining a visual editor state or annotating a UI where pixels are the actual subject.

If you include a code image for visual emphasis, provide the meaningful snippet as text or link to an accessible source. Alt text is useful context, but it is not a practical replacement for a long runnable program.

Pre-publish code checklist

• Every code block has a purpose stated in nearby prose.
• The language label matches the syntax.
• No secret, personal path, or internal hostname remains.
• Long lines and large output samples have been reduced.
• Placeholders are unmistakably placeholders.
• The final Substack preview preserves whitespace and grouping.
• The test email is readable without rotating or zooming the phone.
• The complete tested source is linked when omissions matter.