Contributing to the Python Insider Blog: A Step-by-Step Guide with Git and Markdown

Overview

The official Python Insider Blog has undergone a major transformation. It now lives at blog.python.org, powered by a Git repository instead of the old Blogger system. This change lowers the barrier for community contributions: you no longer need a Google account or to wrestle with Blogger's editor. Every post is simply a Markdown file in a Git repository. If you can open a pull request, you can write a post.

This guide explains everything you need to know to start contributing, from understanding the new setup to submitting your first post. It covers prerequisites, step-by-step instructions, common pitfalls, and a summary of the key points.

Prerequisites

Before you begin, ensure you have the following:

• A GitHub account (free)
• Basic familiarity with Git (cloning, committing, pushing, creating pull requests)
• A text editor (e.g., VS Code, Sublime Text, or even Notepad)
• Knowledge of Markdown syntax (headings, lists, links, images)
• Understanding of YAML frontmatter (simple key-value pairs)

If you are new to Git or Markdown, there are many free tutorials online. This guide assumes you can perform basic GitHub operations.

Step-by-Step Instructions

1. Fork the Repository

Navigate to the official blog repository: https://github.com/python/python-insider-blog. Click the Fork button in the top-right corner to create your own copy under your GitHub account.

2. Clone Your Fork Locally

Open a terminal and run:

git clone https://github.com/<your-username>/python-insider-blog.git
cd python-insider-blog

3. Create a Directory for Your Post

All blog posts live under content/posts/. Each post has its own folder named after a URL-friendly slug. For example, if your post is about Python 3.13 release, you might name the folder python-313-released.

mkdir content/posts/python-313-released

4. Write Your Post as index.md

Inside your new directory, create a file named index.md. This file must start with YAML frontmatter that defines metadata. Here is the required structure:

---
title: "Your Post Title"
date: 2025-03-15
authors:
  - "Your Name"
tags:
  - python
  - release
---

Mandatory fields: title, date, authors (list), tags (list). Additional optional fields are documented in the repository's README.

After the frontmatter, write your post content in Markdown. For example:

## What's New in Python 3.13

We are excited to announce the release of Python 3.13...

![Python logo](cover.png)

5. Add Images (Optional)

Place any images directly in the same directory as your index.md. Reference them with relative paths (e.g., ![alt text](image.png)). No special configuration needed.

6. Commit and Push Your Changes

git add .
git commit -m "Add post: Python 3.13 released"
git push origin main

7. Open a Pull Request

Go to your fork on GitHub. You'll see a banner prompting you to create a pull request. Click it, add a brief description, and submit. The Python development team will review your PR and merge it if everything looks correct.

Common Mistakes

• Missing or malformed frontmatter: The YAML block must start and end with three dashes (---). Incorrect indentation or missing required fields will cause the build to fail.
• Incorrect slug: The folder name must be unique and URL-safe. Avoid spaces, capital letters, or special characters.
• Not forking first: Always work on your own fork. Direct pushes to the main repository are not allowed.
• Forgetting to update RSS feed: If you are migrating from the old blog, note that the new RSS feed URL is https://blog.python.org/rss.xml. Old URLs automatically redirect.
• Ignoring redirects: The 307 posts from Blogger are all migrated, and old links redirect. If you find a broken link, file an issue.

Summary

The Python Insider Blog has moved to a modern, Git-based infrastructure. Contributions are now simpler than ever: fork the repository, add a Markdown post in content/posts/{slug}/index.md with YAML frontmatter, optionally include images, and submit a pull request. The site uses Astro, Tailwind, and GitHub Actions for static deployment, with an optional Keystatic CMS available during development.

This new workflow eliminates the need for a Google account and proprietary editor. If you find any issues from the migration, please report them on the repository.