How to Contribute to the Python Insider Blog: A Complete Guide

Overview

The Python Insider blog has undergone a major transformation. Formerly hosted on Blogger, the official Python blog now lives at https://blog.python.org. All 307 posts from the Blogger era have been migrated automatically, and old URLs redirect to the new ones seamlessly. This move isn't just a change of address—it's a fundamental shift in how the blog is managed. Instead of requiring a Google account and the Blogger editor, contributions are now handled through a Git repository. Writing a post is as simple as creating a Markdown file and submitting a pull request. This guide will walk you through everything you need to know to become a contributor, from understanding the new setup to submitting your first post.

Prerequisites

Before you start, ensure you have the following:

• A GitHub account – you'll need this to fork the repository and open pull requests.
• A text editor – any plain text editor works (VS Code, Notepad++, vim, etc.). Markdown syntax is all you need.
• Basic familiarity with Git (optional but helpful) – concepts like cloning, committing, and pushing will smooth the process. However, you can also use GitHub's web interface to create files and propose changes without local Git.
• A web browser to preview your post – local development setup is optional (see advanced section).

Step-by-Step Instructions

1. Understand the New Blog Structure

The blog is built with Astro and deployed as fully static HTML. Content lives in a Git repository hosted on GitHub: python/python-insider-blog. Each post resides in its own directory under content/posts/. The directory is named with a URL-friendly slug (e.g., python-3-12-released). Inside that directory, you'll find:

• index.md – the post content in Markdown, with YAML frontmatter at the top.
• Any images or assets used in the post (placed alongside index.md).

The YAML frontmatter includes fields like title, date, authors, and tags. Here's a minimal example:

---
title: My First Post
date: 2025-03-15
authors: ["Your Name"]
tags: ["announcement", "python"]
---

Your Markdown content goes here.

2. Fork the Repository

Navigate to https://github.com/python/python-insider-blog and click the Fork button in the top-right corner. This creates a copy of the repository under your GitHub account.

If you plan to work locally, clone your fork:

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

If you prefer to avoid the command line, you can also create files directly on GitHub's web interface in your fork.

3. Create Your Post

Inside the cloned repository (or your fork on GitHub), navigate to content/posts/. Create a new directory with a unique slug (e.g., my-first-post). Inside that directory, create a file named index.md.

Add the YAML frontmatter followed by your post content in Markdown. For example:

---
title: Celebrating Python's 35th Birthday
date: 2025-02-20
authors: ["Guido van Rossum"]
tags: ["community", "history"]
---

It all started in February 1991… and we've come a long way!

[Read more about the history](https://python.org/doc/essays/foreword/).

If your post includes images, place them in the same directory as index.md. Reference them with relative paths:

![Python logo](python-logo.png)

4. Preview Your Post (Optional but Recommended)

To see how your post will look before submitting, you can run the site locally. The repository uses Astro and Node.js. Follow these steps:

• Ensure you have Node.js (version 18 or later) installed.
• From the project root, install dependencies: npm install
• Start the development server: npm run dev
• Open your browser to http://localhost:4321 (the default port).

The server supports hot-reloading so changes to your Markdown file will appear instantly.

Alternatively, the repo also includes Keystatic CMS, a visual editor that you can use in dev mode. To use it, run npm run dev and navigate to /admin. This is entirely optional—raw Markdown is the primary workflow.

5. Submit a Pull Request

Once your post is ready, commit the changes and push to your fork:

git add content/posts/my-first-post/
git commit -m "Add post: Celebrating Python's 35th Birthday"
git push origin main

Then, on GitHub, go to your fork and click the Contribute button (or open a pull request). Write a clear description of your post and mention any relevant issues (e.g., if this post is part of an approved topic).

The core team will review your PR. Once approved and merged, the post will automatically be built and deployed via GitHub Actions to https://blog.python.org.

Common Mistakes

Forgetting YAML Frontmatter

Every post must start with valid YAML frontmatter delimited by ---. Missing or malformed frontmatter will cause the build to fail. Pay special attention to quoted strings if your title contains colons or other special characters.

Incorrect Directory Structure

Each post must be inside a uniquely named directory under content/posts/. Placing index.md directly in content/posts/ or using a duplicate slug will lead to errors. Always create a new folder with a slug that doesn't conflict with existing ones.

Image Path Errors

Images must reside in the same directory as the index.md of your post. If you reference an image with an absolute path or a path pointing to another post's folder, it will break. Use relative paths like ./image.png or just image.png.

Broken Links from Migration

While all old URLs automatically redirect to the new ones, you may still find broken internal links or missing images left over from the migration. If you spot any, please file an issue on the repository. PRs to fix these are welcome too.

Summary

The Python Insider blog's move from Blogger to a Git-based system has made contributing significantly easier. Now, anyone with a GitHub account and basic Markdown skills can propose a post. The workflow is simple: fork the repository, create a new directory under content/posts/ with a properly formatted index.md file, add your images, and submit a pull request. The site is built with Astro and deployed statically, and optional visual editing via Keystatic CMS is available for those who prefer it. Remember to check the repository's README for full details on frontmatter fields and local development. Happy writing—we look forward to your contribution!