Skip to content

Publish a Blog Post on the VS Code Website

Jump to bottom
Nick Trogh edited this page Mar 5, 2026 · 1 revision

Instructions for publishing a blog post on the VS Code website

1. Overview

This guide walks you through the process of publishing a blog post on the VS Code website. Before diving into the technical setup, we recommend drafting your post in a Word document and sharing it with the product team (Nick and other PMs) via chat for initial feedback and review. This early collaboration ensures your content aligns with our messaging and strategic goals before you proceed with the technical publication steps.

2. Fork and clone the repository

  1. Fork the repository at github.com/microsoft/vscode-docs to your GitHub account

  2. Clone your fork locally:

    git clone https://github.com/YOUR-USERNAME/vscode-docs.git
cd vscode-docs

3. Enable Git LFS

This repository uses Git LFS for images and videos. You must set it up before working with media files. Note that uploading media via the GitHub web interface is not supported.

brew install git-lfs   # macOS
git lfs install

4. Keep your fork up to date

Before starting, make sure your fork is up to date. On GitHub, go to your fork and select Sync fork to pull in the latest changes from upstream.

Then pull locally:

git checkout main
git pull

5. Create a branch

git checkout -b blog/YOUR-USERNAME

6. Create the folder structure and files

Posts must live under blogs/YYYY/MM/DD/:

blogs/
  2026/
    03/
      05/
        your-post-name.md
        hero-image.png

7. Write the post

Start with the required YAML frontmatter:

---
Order: <unique number, higher than the most recent post>
TOCTitle: <short title, max 30 characters>
PageTitle: "Full blog post title"
MetaDescription: "SEO description, max 160 characters."
MetaSocialImage: hero-image.png # filename can be different, but the image must be in the same folder as the post
Date: YYYY-MM-DD
Author: Full Name
---

Content structure:

  • # Title as H1
  • Byline immediately below: <Month> <day>, <year> by [Name](link-to-social-profile)
  • Brief intro summarizing the main points
  • Sections with ## Heading (H2)
  • Include a social image in the same folder as the post and reference it in MetaSocialImage
  • Images and videos: use relative paths with alt/title text. All media files must be uploaded via Git LFS and stored in the same folder as the post.
  • Links to docs using full URLs
  • End with a call to action and: Happy coding! 💙

8. Commit and push

git add blogs/2026/[month]/[day]
git commit -m "Blog: your post name"
git push origin blog/YOUR-USERNAME

9. Open a Pull Request

Go to your fork on GitHub and open a PR from your branch targeting main on microsoft/vscode-docs. You can submit it as a draft PR and share it with Nick Trogh for review.

Clone this wiki locally
⚡