How to Publish VS Code Markdown to Substack

Keep the article source publishable

A repository article should be understandable without your editor state. Use standard Markdown where possible, store supporting images in a deliberate location, and avoid links that only work from the current checkout. This makes the source useful in code review and reduces surprises in the publishing handoff.

Do not put credentials, unpublished internal URLs, customer identifiers, or machine-specific paths in examples. A Git diff is an excellent final privacy review because it shows exactly what changed in the article and its assets.

content/
  agent-loop.md
  images/
    agent-loop.png
samples/
  agent-loop.ts

Fix relative links and local images

Publish from VS Code in seven steps

1. 01

   Write and preview the Markdown

   Use VS Code’s preview to catch malformed headings, lists, links, fences, and tables while the draft is still in the repository.

2. 02

   Run the code you show

   Test commands and examples from a clean enough environment to catch omitted imports, stale flags, and output that no longer matches the prose.

3. 03

   Review the diff

   Scan for secrets, internal references, accidental changes, oversized assets, and language that only makes sense to repository collaborators.

4. 04

   Load the .md file into StackDraft

   Drag the file into the app and compare the rendered article with the intended outline. The draft remains in the browser.

5. 05

   Resolve publishing checks

   Fix missing alt text, local asset paths, long code, wide tables, heading jumps, and diagrams that need static rendering.

6. 06

   Copy title and body

   Put the title in Substack’s title field, paste the prepared body into the editor, and confirm every generated asset arrives.

7. 07

   Send a test email

   Validate the actual reader experience: mobile width, code readability, link destinations, image descriptions, and dark-mode contrast.

Use source control as an editorial tool

• Keep article edits separate from unrelated product changes when possible.
• Review prose and code examples in the same commit so they cannot silently diverge.
• Use descriptive image filenames and include the editable diagram source.
• Check changed URLs instead of assuming an old link is still public.
• Ask a reviewer to follow the instructions, not just proofread them.
• Tag or record the source revision associated with the published article.

Prepare technical blocks for the inbox

A Markdown preview shows what a capable web renderer can do; it does not show what an email client will preserve. Convert Mermaid blocks to PNG, reduce tables to a few columns, shorten code, and use plain-language explanations around every complex artifact.

StackDraft uses GitHub Flavored Markdown for tables, highlights fenced code, renders Mermaid locally, and warns about patterns that tend to fail in publishing. Use the preview as an intermediate quality gate, then use Substack’s test email as the final one.

Repository-to-newsletter checklist

• The Markdown passes the project’s formatter or lint rules, if any.
• Every code example has been tested and trimmed for the article.
• No secret, internal hostname, customer data, or personal path appears in the diff.
• Relative links and images have a publishing destination.
• The article has one H1 and a coherent heading outline.
• Tables, code, and diagrams fit a phone-width reading experience.
• The Substack title and body are separated correctly.
• A real test email passes before the post is scheduled or sent.