How to Contribute to the Python Insider Blog with Git and Markdown

Introduction

The Python Insider Blog has found a new home at blog.python.org, and with it comes a streamlined workflow built on Git and Markdown. All 307 previous posts have been migrated, and old links redirect correctly — your RSS feed should update automatically to https://blog.python.org/rss.xml. This modern setup lowers the bar for contributors: no more needing a Google account or wrestling with Blogger's editor. If you can open a pull request, you can write a post.

This guide walks you through the entire process, from setting up your environment to submitting your contribution. Whether you're announcing a Python release, a core sprint, a governance update, or anything else official, you'll be publishing in no time.

What You Need

• GitHub account — forking the repository and opening pull requests.
• Text editor — any plain-text editor works; VS Code, Sublime Text, or even Notepad will do.
• Basic Git knowledge (optional but helpful) — cloning, committing, and pushing changes.
• Python Insider Blog repository — https://github.com/python/python-insider-blog
• Optional: Node.js and Astro — if you want to preview your post locally (see the repo README).

Step-by-Step Guide

Step 1: Fork the Repository

1. Navigate to python/python-insider-blog on GitHub.
2. Click the Fork button in the upper-right corner to create your own copy.
3. Clone your fork to your local machine using:
   git clone git@github.com:YOUR-USERNAME/python-insider-blog.git
4. Change into the directory:
   cd python-insider-blog

Step 2: Create a Directory for Your Post

1. Inside the cloned repo, navigate to content/posts/.
2. Create a new directory named with your post's URL-friendly slug. For example, if your post is titled “Python 3.12 Released”, use something like python-3-12-released.
   mkdir -p content/posts/python-3-12-released

Step 3: Write Your Post in Markdown

1. Inside your new directory, create a file named index.md.
2. Add YAML frontmatter at the top with required fields: title, date, authors, tags. Example:
   

   ---
   title: "Python 3.12 Released"
   date: 2025-03-10
   authors: ["Guido van Rossum"]
   tags: ["release", "news"]
   ---
   

3. Write your content using standard Markdown syntax. You can include headings, lists, links, images, and code blocks.

Step 4: Add Images (Optional)

1. Place any images you want to use in the same directory as your index.md file (e.g., content/posts/python-3-12-released/logo.png).
2. Reference them in your Markdown using relative paths:
   ![Python logo](logo.png)

Step 5: Preview Your Post (Optional)

1. If you have Node.js installed, you can run the local development server:
   npm install (once) then npm run dev.
2. Open the URL shown (usually http://localhost:4321) and navigate to your post.
3. Alternatively, you can use the Keystatic CMS in dev mode by visiting /admin — but raw Markdown is fully supported.

Step 6: Commit and Push Your Changes

1. Stage your new files:
   git add content/posts/python-3-12-released/
2. Commit with a descriptive message:
   git commit -m "Add post: Python 3.12 Released"
3. Push to your fork:
   git push origin main

Step 7: Open a Pull Request

1. Go to your fork on GitHub and click the Contribute button (or Pull Request tab).
2. Click Open Pull Request. Ensure the base repository is python/python-insider-blog and the head is your fork with the new branch (if you created one) or main.
3. Give your PR a clear title and description. Mention what the post covers.
4. Click Create Pull Request.

Your PR will be reviewed by the Python Insider team. Once merged, the site rebuilds automatically via GitHub Actions and your post goes live on blog.python.org.

Tips for a Smooth Contribution

• Check the repository README — it contains detailed information about frontmatter fields and local development.
• Follow the style of existing posts — look at a few index.md files in content/posts/ to match formatting.
• Test your links and images before submitting to avoid broken assets.
• If you spot migration issues (broken links, missing images, formatting glitches), please file an issue on the repository. PRs to fix them are welcome too.
• Your RSS feed should work automatically — the new feed URL is https://blog.python.org/rss.xml. If you experience any issues, readers can update manually.
• No special tools required — just a text editor and Git. The entire build is powered by Astro, Tailwind, and GitHub Actions, so you don't need to install anything unless you want to preview.

Now you're ready to contribute to the Python Insider Blog! The new Git-based workflow makes it easier than ever to share Python news with the community. Happy writing!