← Back to Blog

How to Embed Code Blocks in Substack Posts

Formatting

Technical newsletters are booming on Substack. Whether you’re teaching programming, sharing engineering insights, or documenting open source projects, you’ll need to display code in your posts. Substack offers basic code formatting, but understanding its limitations helps you present code that’s actually readable.

Inline Code

Inline code is for short references within a sentence — a function name, a variable, a command, or a file path.

In Substack’s editor, there’s no toolbar button for inline code. You have two options:

  1. Type backticks manually: surround your code with single backticks like `console.log()`
  2. Paste pre-formatted text: if you’re converting from markdown, inline code formatting should transfer when pasting rich text

Inline code renders in a monospace font with a subtle background, visually distinguishing it from surrounding prose.

When to Use Inline Code

  • Function or method names: getElementById(), map(), async/await
  • Variable names: userId, apiKey, config
  • Terminal commands: npm install, git commit
  • File paths: /src/components/Header.tsx
  • Short code fragments: if (x > 0)

When Not to Use Inline Code

  • Multi-line code (use a code block instead)
  • Emphasis on non-code terms (use bold or italic)
  • Brand names or product names (these are proper nouns, not code)

Code Blocks

Code blocks are for multi-line code snippets, configuration files, terminal output, or any content that should be displayed in a monospace, preformatted style.

Adding a Code Block in the Editor

  1. Click the + button that appears between paragraphs
  2. Select the code block option (looks like <>)
  3. Type or paste your code into the block

Alternatively, you can type three backticks (```) on a new line and press Enter — Substack will create a code block.

What Code Blocks Look Like

Substack renders code blocks with:

  • A monospace font (typically a system monospace or similar)
  • A grey or off-white background
  • Left-aligned, preformatted text that preserves whitespace and indentation
  • Horizontal scrolling if lines exceed the content width

The Syntax Highlighting Gap

Here’s the biggest limitation: Substack does not support syntax highlighting. All code appears in a single color, regardless of the programming language.

This means:

function calculateTotal(items) {
  return items.reduce((sum, item) => {
    return sum + item.price * item.quantity;
  }, 0);
}

Keywords like function, return, and const won’t be colored differently from variable names or strings. For simple snippets, this is fine. For longer code blocks, the lack of highlighting can hurt readability.

Workarounds for Syntax Highlighting

Option 1: Screenshots from your editor

Take a screenshot of syntax-highlighted code from VS Code, Sublime Text, or your preferred editor. This preserves colors and formatting exactly as you see them.

Tips for code screenshots:

  • Use a clean theme with good contrast (Dark+ in VS Code works well)
  • Increase the font size slightly for readability in email
  • Crop tightly around the code — no extra whitespace or UI chrome
  • Use a tool like Carbon (carbon.now.sh) or Ray.so for polished code images

Option 2: Use images for critical code

For the most important code samples in your post — the ones readers need to study carefully — consider rendering them as images. Reserve plain code blocks for quick references and short examples.

Option 3: Link to a gist or repository

For very long code samples, link to a GitHub Gist or repository file. Include a simplified version in the post with a “see full code” link.

Code Block Formatting Best Practices

Keep Code Blocks Short

Email viewports are narrow. Long code blocks create excessive scrolling and can cause readers to disengage. Aim for:

  • 15 lines or fewer per code block
  • Break longer examples into multiple blocks with explanatory text between them
  • Remove boilerplate that isn’t relevant to the point you’re making

Add Context Before and After

Never drop a code block into your post without explanation. Before each code block, tell readers what it does and why it matters. After the block, explain the key parts:

The function below calculates the total price for a shopping cart by iterating over each item and multiplying price by quantity.

function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

The reduce method accumulates the running total in sum, starting from 0.

Use Comments for Clarity

Since you don’t have syntax highlighting, inline comments become even more important:

// Fetch user data from the API
const response = await fetch('/api/users');
const users = await response.json();

// Filter to only active users
const activeUsers = users.filter(user => user.isActive);

// Sort by registration date (newest first)
activeUsers.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));

Comments guide the reader’s eye through the code and compensate for the lack of color differentiation.

Indent Consistently

Use consistent indentation — either 2 spaces or 4 spaces, but not a mix. Inconsistent indentation is harder to read in a monospace font without syntax highlighting.

Handling Different Content Types

Terminal Commands

For shell commands, prefix with $ to indicate it’s a command to run:

$ npm install express
$ node server.js

Configuration Files

For JSON, YAML, or TOML configuration:

{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build"
  }
}

Keep configs trimmed to the relevant section. Don’t include an entire package.json if you’re only discussing scripts.

API Responses

When showing API responses, format the JSON readably and highlight the important fields in your surrounding text:

{
  "status": "success",
  "data": {
    "userId": 42,
    "email": "user@example.com",
    "plan": "pro"
  }
}

The Markdown Writer’s Workflow

If you draft your newsletter in markdown, code blocks are natural — you’re already using fenced code blocks with triple backticks. When converting markdown to Substack-ready rich text, tools like DownStack preserve code block formatting so it pastes cleanly into Substack’s editor.

The one thing that won’t transfer is language-specific syntax highlighting. If your markdown specifies a language (```javascript), the language identifier is stripped during conversion since Substack doesn’t use it. The code itself and its indentation are preserved.

Email Rendering Considerations

Code blocks behave differently in email versus the web:

  • Line wrapping: some email clients wrap long lines instead of scrolling horizontally, which can break code formatting
  • Font size: monospace fonts in email may render smaller than on the web
  • Background color: the code block background may not render in all email clients (notably some Outlook versions)
  • Mobile: code blocks on mobile phones may require horizontal scrolling, which some readers find frustrating

To mitigate these issues:

  • Keep lines under 60 characters when possible
  • Test your post’s email preview before publishing
  • For critical code, consider using images instead of text code blocks

Key Takeaways

  • Substack supports inline code (backtick formatting) and multi-line code blocks
  • Syntax highlighting is not available — all code renders in a single color
  • Keep code blocks short (under 15 lines) and add explanatory context
  • Use code screenshots from editors like VS Code for important, longer snippets
  • Comments in code are extra important without syntax highlighting
  • Test code block rendering in Substack’s email preview before publishing
  • For markdown writers, code block formatting transfers cleanly to Substack during conversion
  • Consider linking to GitHub Gists for very long code examples