How to Contribute to the Official Python Blog via Git: A Step-by-Step Guide

Overview

The Python Insider Blog—the official voice of the Python community—has undergone a major transformation. Previously hosted on Blogger, the blog now lives at blog.python.org, backed by a Git repository. All 307 posts from the Blogger era have been successfully migrated, and old URLs automatically redirect to the new ones. Your RSS reader should pick up the new feed without any manual intervention, but if something looks off, the feed URL is https://blog.python.org/rss.xml.

Why the change? Blogger worked well for a long time, but contributing required a Google account and using Blogger’s editor—a barrier that limited participation. The new setup just needs Markdown files in a Git repository. If you can open a pull request, you can write a post. This guide walks you through everything you need to know to become a contributor.

Prerequisites

Before you dive in, make sure you have the following:

• A GitHub account (free tier is fine).
• Git installed on your local machine (optional if you prefer editing directly on GitHub).
• A text editor (e.g., VS Code, Sublime Text, or even Notepad—Markdown is plain text).
• Basic familiarity with Markdown syntax (headers, links, images, etc.).
• Understanding of what a pull request (PR) is and how to create one.

Step-by-Step Instructions

Step 1: Fork the Repository

1. Navigate to the official repository: https://github.com/python/python-insider-blog.
2. Click the Fork button in the top-right corner. This creates a copy of the repo under your GitHub account.
3. Clone your fork to your local machine (if working locally):
   git clone https://github.com/YOUR_USERNAME/python-insider-blog.git

Step 2: Create a New Post Directory

Each post lives in its own directory under content/posts/. The directory name becomes the URL slug (e.g., my-first-post).

• Inside your local fork, create a new directory:
  mkdir content/posts/my-first-post
• Alternatively, on GitHub, you can navigate into content/posts/ and click Add file → Create new file, then type the path (e.g., my-first-post/index.md).

Step 3: Write Your Post in Markdown

Inside your new directory, create a file named index.md. This file must start with YAML frontmatter—metadata that tells the site about your post. Here’s a template:

---
title: "Your Post Title"
date: 2025-03-15
authors:
  - Your Name
tags:
  - python
  - core-sprint
  - governance
---

Your content goes here in Markdown. You can use **bold**, *italics*, [links](https://example.com), and more.

Important frontmatter fields:

• title: The post’s headline (quoted).
• date: Publication date in YYYY-MM-DD format.
• authors: A list of author names (can be one or many).
• tags: A list of tags—choose from existing ones or create new.

Additional optional fields are documented in the repository’s README.md.

Step 4: Add Images (If Needed)

Place any images directly in the same directory as your index.md. For example, if you have my-first-post/index.md, put my-image.png in my-first-post/. Reference it in Markdown like this:

![Alt text](my-image.png)

The build system will handle the rest.

Step 5: Create a Pull Request

1. Commit your changes locally:

   git add .
   git commit -m "Add post: My First Post"
   git push origin main

2. Go to your fork on GitHub. You’ll see a banner prompting you to create a pull request. Click it.
3. Ensure the base repository is python/python-insider-blog and the base branch is main.
4. Fill in a descriptive title and comment (e.g., “New post about Python 3.13 release”).
5. Submit the PR.

Common Mistakes

• Forgetting YAML frontmatter: Without it, the post won’t display correctly. Always start with --- and include at least title, date, and authors.
• Wrong directory structure: Posts must be content/posts/{slug}/index.md. Placing the file directly in content/posts/ or using a different file name will break the build.
• Not forking first: Directly committing to the main repository is not allowed. Always work from your own fork.
• Images in wrong location: If you place images outside the post’s directory, they won’t be linked correctly. Keep them with the index.md.
• Ignoring existing tags: Use consistent tags (e.g., “python”, “core-sprint”) to keep the blog searchable. Check content/posts/ for existing examples.
• Large pull requests: Submit a single post per PR. Combining multiple posts makes review harder.

What’s Under the Hood?

The blog is built with Astro and deployed as fully static HTML. For those who prefer a visual editor, a Keystatic CMS is available in dev mode—but it’s optional; raw Markdown works fine. Styling uses Tailwind CSS. The entire build and deployment pipeline runs via GitHub Actions, meaning your PR triggers a preview build automatically.

Summary

The move from Blogger to a Git-based platform has made contributing to the Python Insider Blog simpler and more inclusive. To get started:

1. Fork the repository.
2. Create a new directory under content/posts/.
3. Write your post as index.md with YAML frontmatter.
4. Add images in the same directory.
5. Open a pull request.

If you spot broken links, missing images, or formatting issues from the migration, file an issue on the repo. PRs are always welcome. Happy writing!