@python/blog-utils

Shared Astro components for the three PSF-family blogs: psf/blog, blog.pypi.org, and Python Insider.

Each site vendored its own copy of these components, so fixes landed in one repo and never reached the other two. This package holds the copies that are identical across all three, so a fix ships once.

Install

bun add @python/blog-utils

Astro compiles the .astro sources directly — the package has no build step.

Use

---
import Pagination from "@python/blog-utils/components/Pagination.astro";
import Pep from "@python/blog-utils/components/references/Pep.astro";
import { externalIcon } from "@python/blog-utils/components/references/icons";
---

<Pagination currentPage={2} totalPages={9} baseUrl="/blog" />

Two things the consuming site must provide

1. Import the badge styles. The reference components are styled by a stylesheet the package ships, scoped to .prose (a badge outside a .prose container is deliberately unstyled):

@import "@python/blog-utils/styles/references.css";

It covers every reference type the remark plugin detects.

CommandPalette needs its own stylesheet too — it is built from .cmdk-* classes rather than utilities, so without this it renders as unstyled text:

@import "@python/blog-utils/styles/command-palette.css";

2. Tailwind must scan this package. Tailwind v4 skips node_modules, so the classes in these components are invisible to it by default. Add to your global CSS:

@source "../../node_modules/@python/blog-utils/src";

3. Pagination reads two theme tokens so each site keeps its own palette:

@theme {
  --color-py-blue: #306998;    /* active page, light mode */
  --color-py-blue-dm: #ffd43b; /* active page, dark mode  */
}

Contents

| Export | Notes | | --- | --- | | components/PythonLogo.astro | byte-identical across all three sites | | components/Pagination.astro | token-based variant, from psf/blog | | components/references/{Docs,GhRepo,GhUser,Pep,PyPi}.astro | byte-identical across all three sites | | components/references/icons | superset of the three copies | | lib/og-fonts | Inter 400/600/700 loader for satori OG images |

Component gallery

Every component, in every state and placement, on one page:

make dev      # or: make preview

The gallery lives in demo/ and imports the package sources by relative path, so it exercises the same files npm ships. It is never published — files in package.json limits the tarball to src/.

Run make help for the full target list.

Releasing

Publishing runs from GitHub Actions with npm Trusted Publishing (OIDC) — there is no npm token to leak. See .github/workflows/publish.yml.