How to Contribute to the Official Python Blog Using Git and Markdown

Overview

The Python Insider blog has officially moved to a new home at blog.python.org. This isn't just a URL change—it's a complete overhaul of the blogging platform. Gone are the days of needing a Google account and clunky Blogger editor. The blog now lives as a Git repository on GitHub, and all posts are pure Markdown files. This guide will walk you through what changed, why it matters, and—most importantly—how you can contribute a post yourself.

All 307 legacy posts from the Blogger era have been migrated, and old URLs automatically redirect to the new ones. Your RSS reader should pick up the new feed automatically, but if not, point it to https://blog.python.org/rss.xml.

Prerequisites

Before you start, make sure 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, Sublime Text, Vim, Notepad). No special plugins required.
• Basic Markdown knowledge – You should be comfortable writing headers, lists, links, and images in Markdown.
• Git (optional but helpful) – For local development and preview, you can install Git and the project's build tools (Node.js, npm). But if you prefer editing entirely in GitHub's web interface, that's also possible.

Step-by-Step Instructions

1. Fork the Repository

Head over to the official repository at 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. Create a New Post Directory

Inside your forked repository, navigate to content/posts/. All posts live in their own directory named after a slug (a URL-friendly identifier, e.g., python-3-12-released). Create a new folder there with your desired slug.

Example structure:

content/posts/
  my-first-post/
    index.md
    hero-image.png

3. Write Your Post with YAML Frontmatter

Inside your new directory, create an index.md file. This file must begin with YAML frontmatter—a block of metadata enclosed between triple dashes (---). The required fields are:

• title: The post title (string)
• date: Publication date in YYYY-MM-DD format
• authors: List of author names or GitHub usernames
• tags: List of relevant tags (e.g., release, governance)

Optional fields may include draft (boolean), description, and coverImage. Check the repo's README for full details.

Example frontmatter:

---
title: "Introducing Python 3.12"
date: 2024-10-10
authors:
  - guido
  - pandas-dev
tags:
  - release
  - python-3.12
---

Your post content starts here...

After the closing ---, write your post in Markdown. Use standard Markdown syntax for headings (##, ###), links, lists, code blocks (with triple backticks and language name), and images.

4. Add Images (Optional)

Place image files in the same directory as your index.md. Reference them using relative paths:

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

You can also use subdirectories, but keeping everything in the post's folder simplifies things.

5. Preview Your Post Locally (Recommended but Optional)

If you have Node.js and npm installed, you can preview the site on your local machine:

1. Clone your forked repository: git clone https://github.com/YOUR-USERNAME/python-insider-blog.git
2. Navigate into the directory: cd python-insider-blog
3. Install dependencies: npm install
4. Start the development server: npm run dev
5. Open http://localhost:4321 in your browser. Your post should appear in the list.

You can also use the optional Keystatic CMS visual editor by running npm run dev:keystatic. This gives you a WYSIWYG-like interface, but it's entirely optional and not required for submission.

6. Open a Pull Request

Once your post looks good, commit and push your changes to your fork, then open a pull request (PR) to the main repository (python/python-insider-blog). In the PR description, summarize your changes. The Python team will review, may suggest edits, and then merge. After merging, the site will rebuild automatically via GitHub Actions and deploy as static HTML.

Common Mistakes

Forgetting or Incorrectly Formatting Frontmatter

The most frequent issue is missing YAML frontmatter or misplacing a colon. The frontmatter must be the very first lines of the file, surrounded by --- lines. If you skip it, the build system won't recognize your post. Double-check that fields like date are in YYYY-MM-DD format and that lists are indented properly.

Wrong Directory Structure

Always create a dedicated folder under content/posts/ named exactly as your slug. Do not place index.md directly inside content/posts/—that will cause conflicts. Also, avoid spaces or special characters in folder names; use hyphens.

Broken Image Paths

Images must be in the same directory or in a subdirectory relative to your index.md. If you move images after writing the post, your links will break. Test locally before submitting.

Not Previewing Before PR

While not required, skipping the local preview increases the chance of formatting errors. A quick npm run dev can catch missing frontmatter, broken links, or layout issues.

Ignoring the README

The repository README contains a full list of frontmatter fields, available tags, and troubleshooting tips. Always read it before submitting a PR, especially if you encounter unfamiliar behavior.

Summary

The migration of the Python Insider blog to a Git-based workflow makes contributing easier than ever. With just a fork, a Markdown file, and a pull request, you can share Python news, release announcements, governance updates, and more. The process is simple: fork the repo, create a directory under content/posts/, write your post with YAML frontmatter, add optional images, preview locally if you wish, and open a PR. Common pitfalls include frontmatter errors and incorrect directory structure—but these are easy to avoid with the guidance above. Welcome to the new Python Insider blog, and happy writing!