How to Contribute to the Python Blog: A Complete Guide Using Git and Markdown

Overview

The Python Insider blog has officially moved to blog.python.org, now powered by a Git repository. This modernization makes contributing easier than ever—no more needing a Google account or wrestling with Blogger’s editor. Instead, all posts are plain Markdown files in a GitHub repository. Whether you want to announce a new Python release, report on a core sprint, discuss governance updates, or share anything else relevant to the Python community, this guide will walk you through the entire process, from understanding the new setup to submitting your first pull request.

We’ll cover the prerequisites, step-by-step instructions with real code examples, common pitfalls to avoid, and a summary to get you started quickly. Let’s dive in!

Prerequisites

Before you start, make sure you have:

• A GitHub account (free tier works fine).
• Git installed on your local machine (or you can use the GitHub web interface for simpler contributions).
• A text editor like VS Code, Sublime Text, or even Notepad++ to write Markdown.
• Basic familiarity with Markdown syntax and YAML frontmatter (don’t worry, we’ll show examples).
• Optionally, Node.js and pnpm (or npm/yarn) if you want to preview the site locally using Astro.

That’s it! No special blog editor or permissions required.

Step-by-Step Instructions

1. 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 own GitHub account. You’ll work in this fork and then open a pull request to propose changes.

2. Clone Your Fork Locally (Optional)

If you want to preview your post before submitting (recommended), clone your fork:

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

If you’d rather edit directly on GitHub, skip to step 4.

3. Set Up Local Development (Optional)

The site uses Astro with Tailwind CSS. To preview your post, install dependencies and run the dev server:

pnpm install
pnpm run dev

This starts a local server at http://localhost:4321 (or a similar port). You’ll see your changes in real time as you edit Markdown files.

If you prefer a visual editor, you can also launch the Keystatic CMS in dev mode:

pnpm run dev:cms

Then visit http://localhost:4321/keystatic for a UI-based editing experience. This is entirely optional—raw Markdown works perfectly.

4. Create a New Post Directory

All posts live under content/posts/. Each post has its own directory named with a URL-friendly slug (e.g., my-python-tip). Inside that directory, you’ll place an index.md file (the post content) and optionally any images.

Example structure:

content/posts/
  my-python-tip/
    index.md
    my-image.png

5. Write index.md with Frontmatter

Your index.md must start with YAML frontmatter (between --- lines) containing:

• title: The post’s title (string).
• date: The publication date (format YYYY-MM-DD).
• authors: A list of author names (they must match existing contributor profiles in the repo).
• tags: A list of tags (e.g., release, governance, sprint).
• canonical (optional): if republishing from elsewhere.

Example frontmatter:

---
title: "How to Contribute to the Python Blog"
date: 2024-03-28
authors:
  - John Doe
tags:
  - tutorial
  - blog
---

After the closing ---, write your post in regular Markdown. You can include headings, lists, code blocks, images (use ![alt](image.png)), and anything else Markdown supports.

6. Commit and Push to Your Fork

Once your index.md and any images are ready:

git add content/posts/my-python-tip/
git commit -m "Add post: my-python-tip"
git push origin main

If you edited directly on GitHub, you can skip this step.

7. Open a Pull Request

Navigate to your fork on GitHub and click Contribute then Open Pull Request. Ensure the base repository is python/python-insider-blog (main branch) and the head is your fork. Add a descriptive title and comment explaining what your post covers.

The site is automatically built and deployed via GitHub Actions, so once maintainers review and merge your PR, your post will go live on blog.python.org.

Common Mistakes

• Forgetting YAML frontmatter: Without it, Astro won’t generate the page correctly. Always include title, date, authors, and tags.
• Incorrect date format: Use YYYY-MM-DD. Other formats may break sorting or display.
• Wrong slug directory name: The slug should match the intended URL, be lowercase, and use hyphens. Don’t include spaces or special characters.
• Images not in the same directory: Place images right next to index.md. Referencing images elsewhere may cause broken links after deployment.
• Not pulling latest base: If you work on your fork for a long time, the main repo may have changed. Sync your fork before creating a PR to avoid merge conflicts.
• Missing author profile: Authors listed in frontmatter must exist in the project’s author list (defined elsewhere in the repo). Check the README for details.
• Using raw HTML without escaping: While Markdown allows inline HTML, it’s recommended to stick to Markdown syntax for portability.

Summary

The Python Insider blog’s migration to a Git-based workflow lowers the barrier to contribution. By switching from Blogger to a system of Markdown files in a GitHub repository, anyone with a GitHub account can propose posts via pull requests. This guide walked you through forking the repo, creating a new post with proper YAML frontmatter, and submitting your changes. With the new RSS feed and automatic redirects from old URLs, readers and contributors alike benefit from a more open, efficient platform. Start writing your first post today—every pull request helps the Python community stay informed.