@vdaluz/astro-blog 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Da Luz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# @vdaluz/astro-blog
+
+[![CI](https://github.com/vdaluz/astro-blog/actions/workflows/ci.yml/badge.svg)](https://github.com/vdaluz/astro-blog/actions/workflows/ci.yml)
+
+A blog needs a listing page, pagination, related posts, tag filters, JSON-LD, RSS, and a Shiki-highlighted code theme - most of it undifferentiated work you rebuild every time you spin up an Astro site. `@vdaluz/astro-blog` packages that layer as token-driven components, so styling comes from your own CSS custom properties, not a hardcoded palette. Ships raw `.astro` and `.ts` - the consuming app's Astro/Vite compiles them (no prebuild step). Built for and proven in production across two sites, [vdaluz.com](https://vdaluz.com) and [imperfectsystems.com](https://imperfectsystems.com) - see [Consumers](#consumers).
+
+> **Scope:** this is a component library, not a drop-in blog. Routes (`src/pages/blog/*`) and content (`src/content/blog/*.md`) stay in each app - see [Per-app glue](#per-app-glue).
+
+## Install
+
+Pinned https tarball from a tag (no registry needed):
+
+```jsonc
+// package.json
+"dependencies": {
+  "@vdaluz/astro-blog": "https://github.com/vdaluz/astro-blog/archive/refs/tags/v0.7.0.tar.gz"
+}
+```
+
+> **Why a tarball, not `github:vdaluz/astro-blog#v0.1.0`?** npm canonicalizes GitHub
+> shorthand (and even an explicit `git+https://` URL) to `git+ssh://` in the lockfile.
+> CI runners (e.g. Cloudflare Pages/Workers) have no SSH key, so `npm ci` would fail to
+> clone it. The `/archive/refs/tags/<tag>.tar.gz` URL is anonymous https with an integrity
+> hash in the lockfile - it just works in CI. Bump the tag in the URL to upgrade. This is the
+> only supported install path; there's no npm registry package (tag-tarball works for anyone,
+> no registry auth needed).
+
+Peer dependency: `astro` >= 6. For post body styling you'll also want `@tailwindcss/typography` in the app.
+
+## Four things every consumer MUST do
+
+1. **Define the token CSS variables.** Components reference only these names:
+   `bg`, `surface`, `surface-muted`, `fg`, `muted`, `border`, `accent`, `accent-strong`, `accent-soft`, `on-accent`.
+   Copy `src/styles/tokens.example.css` into your app and set your palette.
+
+2. **Alias the tokens in `tailwind.config.mjs` AND scan the package** (this glob is the #1 thing people forget - without it the package's utility classes are never generated):
+
+   ```js
+   export default {
+     content: [
+       './src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}',
+       './node_modules/@vdaluz/astro-blog/**/*.{astro,ts}', // <-- required
+     ],
+     theme: {
+       extend: {
+         colors: {
+           bg: 'rgb(var(--bg) / <alpha-value>)',
+           surface: 'rgb(var(--surface) / <alpha-value>)',
+           'surface-muted': 'rgb(var(--surface-muted) / <alpha-value>)',
+           fg: 'rgb(var(--fg) / <alpha-value>)',
+           muted: 'rgb(var(--muted) / <alpha-value>)',
+           border: 'rgb(var(--border) / <alpha-value>)',
+           accent: 'rgb(var(--accent) / <alpha-value>)',
+           'accent-strong': 'rgb(var(--accent-strong) / <alpha-value>)',
+           'accent-soft': 'rgb(var(--accent-soft) / <alpha-value>)',
+           'on-accent': 'rgb(var(--on-accent) / <alpha-value>)',
+         },
+       },
+     },
+     plugins: [require('@tailwindcss/typography')],
+   };
+   ```
+
+3. **Wire Shiki** in `astro.config.mjs` and ship the matching CSS handoff (included in `tokens.example.css`):
+
+   ```js
+   import { shikiConfig } from '@vdaluz/astro-blog';
+   export default defineConfig({ markdown: { shikiConfig } });
+   ```
+
+   The `shikiConfig` uses `defaultColor: false`, so the CSS handoff is what actually colors code blocks. They must ship together. **Dark-only sites:** keep `shikiConfig` and force `<html class="dark">` so the dark vars always apply.
+
+4. **Generate a matching `.webp` sibling for every `heroImage`.** `PostCard` and `RelatedPosts` derive the thumbnail `src` by swapping the `heroImage` extension (`.jpg`/`.jpeg`/`.png`/`.gif`) for `.webp` - they never render the raw file. If a post sets `heroImage: /assets/images/foo.jpeg`, `assets/images/foo.webp` must exist at that same path or the thumbnail 404s. Any image pipeline that outputs a same-basename `.webp` next to the original works (e.g. a Sharp-based build step); nothing in this package generates it for you.
+
+## Example
+
+`PostCard` rendering real posts on vdaluz.com's `/blog` listing:
+
+![PostCard grid on vdaluz.com's blog listing page](docs/postcard-example.png)
+
+## Exports
+
+| Import | What |
+| --- | --- |
+| `@vdaluz/astro-blog` | `blogSchema`, `buildBlogPostingSchema`, `scoreRelated`, `normalizeTag`, `filterPostsByTag`, `shikiConfig`, `buildRssItems`, `t`, `formatDate`, types |
+| `@vdaluz/astro-blog/PostCard.astro` | Post card for listings |
+| `@vdaluz/astro-blog/RelatedPosts.astro` | Related-posts grid |
+| `@vdaluz/astro-blog/Pagination.astro` | Paginated listing nav |
+| `@vdaluz/astro-blog/Subheading.astro` | Small uppercase section label |
+| `@vdaluz/astro-blog/BlogPostMeta.astro` | JSON-LD BlogPosting `<script>` |
+| `@vdaluz/astro-blog/HeroImageCredit.astro` | Photographer/source/license attribution line for a post's `heroImageCredit` |
+| `@vdaluz/astro-blog/TagFilterNav.astro` | Filter chip nav (e.g. by project or topic tag) |
+| `@vdaluz/astro-blog/TableOfContents.astro` | "On this page" nav from a post's `headings` array (sticky sidebar on desktop, `<details>` on mobile) |
+| `@vdaluz/astro-blog/remark` | `remarkReadingTime` - writes `minutesRead` to the page's frontmatter |
+
+Components that build post URLs (`PostCard`, `RelatedPosts`, `Pagination`) accept an optional `base` prop (default `/blog`).
+
+`PostCard`, `RelatedPosts`, `Pagination`, and `BlogPostMeta` accept an optional `locale` prop (`'en' | 'es'`, default `'en'`) that localizes their built-in UI strings (dates, "Read More", pagination labels) and `BlogPostMeta`'s JSON-LD `inLanguage` field. It does not affect the post URLs those components build - a locale-specific `base` still needs passing separately if the consuming app routes translated posts under a different prefix (e.g. `/es/blog`).
+
+`PostCard` accepts an optional `categoryLabel` prop to override the category badge text (default `post.data.category`). `RelatedPosts` accepts the same override as a `(post) => string` function, since it renders a badge per post. Use these when `category` is a canonical/English taxonomy value that the consuming app translates for display - the package has no built-in category translation since the taxonomy itself is app-defined.
+
+### Hero image attribution
+
+`blogSchema()` validates an optional `heroImageCredit` field (`name`, `url`, `source: 'pexels' | 'unsplash' | 'openverse'`, optional `licenseName`/`licenseUrl`) for posts whose hero image needs attribution - required for CC/attribution-required sources like Openverse, not just polite. Render it with `HeroImageCredit`:
+
+```astro
+---
+import HeroImageCredit from '@vdaluz/astro-blog/HeroImageCredit.astro';
+---
+
+{entry.data.heroImageCredit && (
+  <HeroImageCredit credit={entry.data.heroImageCredit} locale={locale} />
+)}
+```
+
+### Updated dates
+
+Set `updatedDate` in a post's frontmatter when you substantively edit it after publishing. `buildBlogPostingSchema` uses it for the JSON-LD `dateModified` field, falling back to `pubDate` when unset - so an edited post can signal freshness without every post needing the field.
+
+### Table of contents + reading time
+
+`TableOfContents` reads the `headings` array Astro's own `render()` already returns - no separate parsing step. It renders nothing if the post has fewer than `minHeadings` (default 3) h2/h3 headings.
+
+```js
+// astro.config.mjs
+import { remarkReadingTime } from '@vdaluz/astro-blog/remark';
+export default defineConfig({ markdown: { remarkPlugins: [remarkReadingTime] } });
+```
+
+```astro
+---
+import TableOfContents from '@vdaluz/astro-blog/TableOfContents.astro';
+import { t } from '@vdaluz/astro-blog';
+
+const { Content, headings, remarkPluginFrontmatter } = await render(entry);
+const strings = t(locale);
+---
+
+<span>{strings.minRead(remarkPluginFrontmatter.minutesRead)}</span>
+<TableOfContents headings={headings} locale={locale} />
+```
+
+`TableOfContents` anchors each entry to `#<slug>` - the consuming app's markdown-to-HTML pipeline must emit matching `id` attributes on the rendered `<h2>`/`<h3>` tags (Astro/rehype does this by default; verify if a custom rehype config strips heading ids).
+
+## Per-app glue
+
+Each site keeps these - they can't be packaged because they bind to the app's own collection and routes.
+
+`src/content.config.ts`:
+
+```ts
+import { defineCollection } from 'astro:content';
+import { glob } from 'astro/loaders';
+import { blogSchema } from '@vdaluz/astro-blog';
+
+const blog = defineCollection({
+  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
+  schema: blogSchema({ defaultAuthor: 'Your Name' }),
+});
+export const collections = { blog };
+```
+
+`src/pages/blog/[...page].astro` and `[...slug].astro`: do `getCollection` / `getStaticPaths` / `render()` in-app (tied to your collection), then render the package components. Keep `export const prerender = true`. Site-specific headings and CTAs live here.
+
+Related posts:
+
+```ts
+import { scoreRelated } from '@vdaluz/astro-blog';
+const related = scoreRelated(entry, allPosts, { k: 3, aliases: { ha: 'home-assistant' } });
+```
+
+Tag/project filtering: the route (`src/pages/blog/tag/[tag].astro` or similar) is per-app since URL
+shape and how you build the tag list are site-specific. `filterPostsByTag` + `Pagination` do the rest -
+`Pagination`'s `base` prop already works with any route prefix, no changes needed for a filtered route:
+
+```ts
+import { filterPostsByTag } from '@vdaluz/astro-blog';
+
+export const getStaticPaths: GetStaticPaths = async ({ paginate }) => {
+  const all = await getCollection('blog');
+  const filtered = filterPostsByTag(all, 'homelab').sort(
+    (a, b) => b.data.pubDate.getTime() - a.data.pubDate.getTime()
+  );
+  return paginate(filtered, { pageSize: 5 });
+};
+```
+
+```astro
+<Pagination page={page} base="/blog/tag/homelab" />
+```
+
+`TagFilterNav` renders the filter chips themselves - build the `options` array (label, href, whether
+it's the active filter) from whatever tag list your app tracks:
+
+```astro
+<TagFilterNav
+  options={[
+    { label: 'All', href: '/blog', active: !tag },
+    { label: 'Homelab', href: '/blog/tag/homelab', active: tag === 'homelab' },
+  ]}
+/>
+```
+
+RSS feed (`src/pages/rss.xml.ts`, needs the app's own `@astrojs/rss` dependency - this package doesn't ship it):
+
+```ts
+import rss from '@astrojs/rss';
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import { buildRssItems } from '@vdaluz/astro-blog';
+
+export const prerender = true;
+
+export const GET: APIRoute = async (context) => {
+  const now = new Date();
+  const posts = (await getCollection('blog'))
+    .filter((p) => p.data.pubDate <= now)
+    .sort((a, b) => b.data.pubDate.getTime() - a.data.pubDate.getTime());
+
+  return rss({
+    title: 'Your Site - Blog',
+    description: 'Your site description',
+    site: context.site!,
+    items: buildRssItems(posts),
+  });
+};
+```
+
+## Contributing
+
+Issues welcome. PRs by discussion - open an issue first for anything beyond a typo or docs fix.
+
+## Consumers
+
+- [vdaluz.com](https://vdaluz.com)
+- [imperfectsystems.com](https://imperfectsystems.com)

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@vdaluz/astro-blog",
+  "version": "0.9.0",
+  "description": "Token-driven Astro blog components, related-posts scoring, a schema factory, and Shiki config - proven in production on vdaluz.com and imperfectsystems.com.",
+  "keywords": [
+    "astro",
+    "astro-component",
+    "blog",
+    "blog-components",
+    "related-posts",
+    "rss",
+    "shiki",
+    "json-ld"
+  ],
+  "homepage": "https://github.com/vdaluz/astro-blog#readme",
+  "bugs": {
+    "url": "https://github.com/vdaluz/astro-blog/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vdaluz/astro-blog.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "astro check",
+    "test": "node --test"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./shiki": "./src/lib/shiki.ts",
+    "./PostCard.astro": "./src/components/PostCard.astro",
+    "./RelatedPosts.astro": "./src/components/RelatedPosts.astro",
+    "./Pagination.astro": "./src/components/Pagination.astro",
+    "./Subheading.astro": "./src/components/Subheading.astro",
+    "./BlogPostMeta.astro": "./src/components/BlogPostMeta.astro",
+    "./HeroImageCredit.astro": "./src/components/HeroImageCredit.astro",
+    "./TagFilterNav.astro": "./src/components/TagFilterNav.astro",
+    "./TableOfContents.astro": "./src/components/TableOfContents.astro",
+    "./remark": "./src/lib/remark-reading-time.ts",
+    "./styles/tokens.example.css": "./src/styles/tokens.example.css"
+  },
+  "peerDependencies": {
+    "astro": ">=6.0.0"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.9",
+    "@types/node": "^26.1.1",
+    "astro": "^7.1.3",
+    "typescript": "^6.0.3"
+  }
+}

package/src/components/BlogPostMeta.astro

@@ -0,0 +1,23 @@
+---
+import { buildBlogPostingSchema } from '../lib/schema';
+import type { BlogPostLike } from '../lib/types';
+import type { Locale } from '../lib/i18n';
+
+interface Props {
+  post: BlogPostLike;
+  /** Origin only, e.g. "https://imperfectsystems.com". */
+  siteUrl: string;
+  /** Route prefix posts live under. Defaults to "/blog". */
+  basePath?: string;
+  /** Site/brand name for JSON-LD publisher. Falls back to the post author. */
+  publisherName?: string;
+  /** Locale for the JSON-LD `inLanguage` field. Omitted if unset. */
+  locale?: Locale;
+}
+
+const { post, siteUrl, basePath = '/blog', publisherName, locale } = Astro.props;
+const schema = buildBlogPostingSchema({ post, siteUrl, basePath, publisherName, locale });
+---
+
+{/* JSON-LD is valid in <body>; render this anywhere inside the post page. */}
+<script type="application/ld+json" set:html={JSON.stringify(schema)} />

package/src/components/HeroImageCredit.astro

@@ -0,0 +1,33 @@
+---
+import { t, type Locale } from '../lib/i18n';
+import type { HeroImageCredit as HeroImageCreditData } from '../lib/types';
+
+interface Props {
+  credit: HeroImageCreditData;
+  /** Locale for the credit label text. Defaults to "en". */
+  locale?: Locale;
+}
+
+const { credit, locale = 'en' } = Astro.props;
+const strings = t(locale);
+---
+
+<p class="text-xs text-muted mt-2">
+  {strings.photoCredit}
+  {' '}
+  <a href={credit.url} class="underline hover:text-accent">{credit.name}</a>
+  {' '}
+  {strings.via}
+  {' '}
+  {credit.source}
+  {
+    credit.licenseUrl && credit.licenseName && (
+      <>
+        {', '}
+        <a href={credit.licenseUrl} class="underline hover:text-accent">
+          {credit.licenseName}
+        </a>
+      </>
+    )
+  }
+</p>

package/src/components/Pagination.astro

@@ -0,0 +1,155 @@
+---
+import { t, type Locale } from '../lib/i18n';
+
+interface Props {
+  page: {
+    currentPage: number;
+    lastPage: number;
+    url: {
+      prev?: string;
+      next?: string;
+      first?: string;
+      last?: string;
+    };
+  };
+  /** Route prefix posts live under. Defaults to "/blog". */
+  base?: string;
+  /** Locale for UI strings. Defaults to "en". */
+  locale?: Locale;
+}
+
+const { page, base = '/blog', locale = 'en' } = Astro.props;
+const { currentPage, lastPage, url } = page;
+const strings = t(locale);
+
+const getPageNumbers = () => {
+  const pages = [];
+  const maxVisible = 5;
+
+  if (lastPage <= maxVisible) {
+    for (let i = 1; i <= lastPage; i++) {
+      pages.push(i);
+    }
+  } else {
+    let start = Math.max(1, currentPage - 2);
+    let end = Math.min(lastPage, start + maxVisible - 1);
+
+    if (end === lastPage) {
+      start = Math.max(1, end - maxVisible + 1);
+    }
+
+    for (let i = start; i <= end; i++) {
+      pages.push(i);
+    }
+  }
+
+  return pages;
+};
+
+const pageNumbers = getPageNumbers();
+const pageHref = (n: number) => (n === 1 ? base : `${base}/${n}`);
+---
+
+<nav class="flex items-center justify-center space-x-2 mt-12" aria-label={strings.blogPagination}>
+  {
+    url.first ? (
+      <a
+        href={url.first}
+        class="inline-flex items-center justify-center min-w-11 min-h-11 px-3 py-2 text-muted hover:text-accent transition-colors"
+        aria-label={strings.goToFirstPage}
+      >
+        &laquo;
+      </a>
+    ) : (
+      <span
+        aria-hidden="true"
+        class="inline-flex items-center justify-center min-w-11 min-h-11 px-3 py-2 text-border cursor-not-allowed"
+      >
+        &laquo;
+      </span>
+    )
+  }
+
+  {
+    url.prev ? (
+      <a
+        href={url.prev}
+        class="inline-flex items-center justify-center min-w-11 min-h-11 px-3 py-2 text-muted hover:text-accent transition-colors"
+        aria-label={strings.goToPreviousPage}
+      >
+        &lsaquo;
+      </a>
+    ) : (
+      <span
+        aria-hidden="true"
+        class="inline-flex items-center justify-center min-w-11 min-h-11 px-3 py-2 text-border cursor-not-allowed"
+      >
+        &lsaquo;
+      </span>
+    )
+  }
+
+  {
+    pageNumbers.map((pageNum) =>
+      pageNum === currentPage ? (
+        <span
+          class="hidden sm:inline-flex sm:items-center sm:justify-center sm:min-w-11 sm:min-h-11 px-3 py-2 bg-accent text-on-accent rounded-lg font-medium"
+          aria-current="page"
+        >
+          {pageNum}
+        </span>
+      ) : (
+        <a
+          href={pageHref(pageNum)}
+          class="hidden sm:inline-flex sm:items-center sm:justify-center sm:min-w-11 sm:min-h-11 px-3 py-2 text-muted hover:text-accent transition-colors rounded-lg hover:bg-surface-muted"
+        >
+          {pageNum}
+        </a>
+      )
+    )
+  }
+
+  {
+    url.next ? (
+      <a
+        href={url.next}
+        class="inline-flex items-center justify-center min-w-11 min-h-11 px-3 py-2 text-muted hover:text-accent transition-colors"
+        aria-label={strings.goToNextPage}
+      >
+        &rsaquo;
+      </a>
+    ) : (
+      <span
+        aria-hidden="true"
+        class="inline-flex items-center justify-center min-w-11 min-h-11 px-3 py-2 text-border cursor-not-allowed"
+      >
+        &rsaquo;
+      </span>
+    )
+  }
+
+  {
+    url.last ? (
+      <a
+        href={url.last}
+        class="inline-flex items-center justify-center min-w-11 min-h-11 px-3 py-2 text-muted hover:text-accent transition-colors"
+        aria-label={strings.goToLastPage}
+      >
+        &raquo;
+      </a>
+    ) : (
+      <span
+        aria-hidden="true"
+        class="inline-flex items-center justify-center min-w-11 min-h-11 px-3 py-2 text-border cursor-not-allowed"
+      >
+        &raquo;
+      </span>
+    )
+  }
+</nav>
+
+<div class="text-center text-muted mt-4">
+  <p class="text-sm">
+    {strings.pageOf(currentPage, lastPage)}
+  </p>
+</div>

package/src/components/PostCard.astro

@@ -0,0 +1,72 @@
+---
+import type { BlogPostLike } from '../lib/types';
+import { t, formatDate, type Locale } from '../lib/i18n';
+
+interface Props {
+  post: BlogPostLike;
+  /** Route prefix posts live under. Defaults to "/blog". */
+  base?: string;
+  /** Locale for date formatting and UI strings. Defaults to "en". */
+  locale?: Locale;
+  /** Override text for the category badge. Defaults to post.data.category. */
+  categoryLabel?: string;
+}
+
+const { post, base = '/blog', locale = 'en', categoryLabel = post.data.category } = Astro.props;
+const href = `${base}/${post.id}`;
+const strings = t(locale);
+// Consumers must generate a matching .webp for every heroImage (see README).
+const heroImageWebp = post.data.heroImage?.replace(/\.(jpe?g|png|gif)$/i, '.webp');
+---
+
+<article
+  class="bg-surface rounded-xl shadow-lg overflow-hidden hover:shadow-xl transition-all duration-300"
+>
+  {
+    heroImageWebp && (
+      <a href={href}>
+        <img
+          src={heroImageWebp}
+          alt={post.data.title}
+          width="800"
+          height="192"
+          loading="lazy"
+          decoding="async"
+          class="w-full h-48 object-cover"
+        />
+      </a>
+    )
+  }
+  <div class="p-8">
+    <div
+      class="inline-block px-3 py-1 bg-accent-soft text-accent rounded-full text-sm font-medium mb-4"
+    >
+      {categoryLabel}
+    </div>
+    <h2 class="text-2xl md:text-3xl font-bold text-fg mb-4 hover:text-accent transition-colors">
+      <a href={href}>{post.data.title}</a>
+    </h2>
+    <p class="text-muted mb-6 leading-relaxed text-lg">{post.data.description}</p>
+    <div class="flex items-center justify-between">
+      <time datetime={post.data.pubDate.toISOString()} class="text-sm text-muted">
+        {formatDate(post.data.pubDate, locale)}
+      </time>
+      <a
+        href={href}
+        class="inline-flex items-center text-accent font-semibold hover:text-accent-strong transition-colors group"
+      >
+        {strings.readMore}
+        <svg
+          class="w-4 h-4 ml-1 transform group-hover:translate-x-1 transition-transform duration-300"
+          viewBox="0 0 20 20"
+          fill="currentColor"
+        >
+          <path
+            fill-rule="evenodd"
+            d="M10.293 3.293a1 1 0 011.414 0l6 6a1 1 0 010 1.414l-6 6a1 1 0 01-1.414-1.414L14.586 11H3a1 1 0 110-2h11.586l-4.293-4.293a1 1 0 010-1.414z"
+            clip-rule="evenodd"></path>
+        </svg>
+      </a>
+    </div>
+  </div>
+</article>

package/src/components/RelatedPosts.astro

@@ -0,0 +1,80 @@
+---
+import type { BlogPostLike } from '../lib/types';
+import { t, formatDate, type Locale } from '../lib/i18n';
+
+interface Props {
+  posts: BlogPostLike[];
+  /** Route prefix posts live under. Defaults to "/blog". */
+  base?: string;
+  /** Locale for date formatting and UI strings. Defaults to "en". */
+  locale?: Locale;
+  /** Override text for each post's category badge. Defaults to post.data.category. */
+  categoryLabel?: (post: BlogPostLike) => string;
+}
+
+const { posts, base = '/blog', locale = 'en', categoryLabel = (post) => post.data.category } =
+  Astro.props;
+const strings = t(locale);
+// Consumers must generate a matching .webp for every heroImage (see README).
+const heroImageWebp = (heroImage?: string) => heroImage?.replace(/\.(jpe?g|png|gif)$/i, '.webp');
+---
+
+<section aria-label={strings.relatedReading} class="mt-16 pt-8 border-t border-border">
+  <h2 class="text-2xl font-bold text-fg mb-8">{strings.relatedReading}</h2>
+  <div class="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+    {
+      posts.map((post) => (
+        <article class="bg-surface rounded-xl shadow-[0_1px_3px_0_rgb(0_0_0_/_0.1),0_1px_2px_-1px_rgb(0_0_0_/_0.1)] overflow-hidden hover:shadow-lg transition-all duration-300 flex flex-col">
+          {heroImageWebp(post.data.heroImage) && (
+            <a href={`${base}/${post.id}`}>
+              <img
+                src={heroImageWebp(post.data.heroImage)}
+                alt={post.data.title}
+                width="640"
+                height="160"
+                loading="lazy"
+                decoding="async"
+                class="w-full h-40 object-cover"
+              />
+            </a>
+          )}
+          <div class="p-6 flex flex-col grow">
+            <div class="inline-block self-start px-3 py-1 bg-accent-soft text-accent rounded-full text-xs font-medium mb-3">
+              {categoryLabel(post)}
+            </div>
+            <h3 class="text-lg font-bold text-fg mb-3 hover:text-accent transition-colors leading-snug">
+              <a href={`${base}/${post.id}`}>{post.data.title}</a>
+            </h3>
+            <p class="text-muted text-sm leading-relaxed mb-4 grow line-clamp-3">
+              {post.data.description}
+            </p>
+            <div class="flex items-center justify-between mt-auto">
+              <time datetime={post.data.pubDate.toISOString()} class="text-xs text-muted">
+                {formatDate(post.data.pubDate, locale, { year: 'numeric', month: 'short', day: 'numeric' })}
+              </time>
+              <a
+                href={`${base}/${post.id}`}
+                class="inline-flex items-center text-accent text-sm font-semibold hover:text-accent-strong transition-colors group"
+                aria-label={`${strings.read} ${post.data.title}`}
+              >
+                {strings.read}
+                <svg
+                  class="w-3 h-3 ml-1 transform group-hover:translate-x-1 transition-transform duration-300"
+                  viewBox="0 0 20 20"
+                  fill="currentColor"
+                  aria-hidden="true"
+                >
+                  <path
+                    fill-rule="evenodd"
+                    d="M10.293 3.293a1 1 0 011.414 0l6 6a1 1 0 010 1.414l-6 6a1 1 0 01-1.414-1.414L14.586 11H3a1 1 0 110-2h11.586l-4.293-4.293a1 1 0 010-1.414z"
+                    clip-rule="evenodd"
+                  />
+                </svg>
+              </a>
+            </div>
+          </div>
+        </article>
+      ))
+    }
+  </div>
+</section>

package/src/components/Subheading.astro

@@ -0,0 +1,28 @@
+---
+interface Props {
+  text: string;
+  align?: 'left' | 'center' | 'right';
+  color?: 'blue' | 'gray';
+}
+
+const { text, align = 'left', color = 'blue' } = Astro.props;
+
+const alignClasses = {
+  left: 'text-left',
+  center: 'text-center',
+  right: 'text-right',
+};
+
+const colorClasses = {
+  blue: 'text-accent',
+  gray: 'text-muted',
+};
+---
+
+<div class={`mb-4 ${alignClasses[align]}`}>
+  <span
+    class={`inline-block text-sm uppercase tracking-wider font-semibold ${colorClasses[color]}`}
+  >
+    {text}
+  </span>
+</div>

package/src/components/TableOfContents.astro

@@ -0,0 +1,59 @@
+---
+import { t } from '../lib/i18n';
+import type { Locale } from '../lib/i18n';
+
+export interface TocHeading {
+  depth: number;
+  slug: string;
+  text: string;
+}
+
+interface Props {
+  headings: TocHeading[];
+  /** Locale for the "On this page" label. Defaults to "en". */
+  locale?: Locale;
+  /** Minimum eligible (h2/h3) heading count before rendering anything. Defaults to 3. */
+  minHeadings?: number;
+}
+
+const { headings, locale, minHeadings = 3 } = Astro.props;
+const strings = t(locale);
+const items = headings.filter((h) => h.depth === 2 || h.depth === 3);
+const show = items.length >= minHeadings;
+---
+
+{
+  show && (
+    <>
+      <nav aria-label={strings.onThisPage} class="hidden lg:block">
+        <p class="text-xs font-semibold uppercase tracking-wide text-muted mb-3">
+          {strings.onThisPage}
+        </p>
+        <ul class="flex flex-col gap-2 text-sm">
+          {items.map((h) => (
+            <li class:list={[h.depth === 3 && 'pl-4']}>
+              <a href={`#${h.slug}`} class="text-muted hover:text-accent transition-colors">
+                {h.text}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </nav>
+
+      <details class="lg:hidden border border-border rounded-lg p-4">
+        <summary class="text-xs font-semibold uppercase tracking-wide text-muted cursor-pointer">
+          {strings.onThisPage}
+        </summary>
+        <ul class="flex flex-col gap-2 text-sm mt-4">
+          {items.map((h) => (
+            <li class:list={[h.depth === 3 && 'pl-4']}>
+              <a href={`#${h.slug}`} class="text-muted hover:text-accent transition-colors">
+                {h.text}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </details>
+    </>
+  )
+}

package/src/components/TagFilterNav.astro

@@ -0,0 +1,38 @@
+---
+import { t, type Locale } from '../lib/i18n';
+
+export interface FilterOption {
+  label: string;
+  href: string;
+  active?: boolean;
+}
+
+interface Props {
+  options: FilterOption[];
+  ariaLabel?: string;
+  /** Locale for the default aria-label. Defaults to "en". Ignored if ariaLabel is set. */
+  locale?: Locale;
+}
+
+const { options, ariaLabel, locale = 'en' } = Astro.props;
+const strings = t(locale);
+const resolvedAriaLabel = ariaLabel ?? strings.filterPosts;
+---
+
+<nav aria-label={resolvedAriaLabel} class="flex flex-wrap gap-2 mb-8">
+  {
+    options.map((opt) => (
+      <a
+        href={opt.href}
+        aria-current={opt.active ? 'page' : undefined}
+        class={`px-3 py-1.5 rounded-full text-sm font-medium border transition-colors ${
+          opt.active
+            ? 'bg-accent text-on-accent border-accent'
+            : 'border-accent/30 text-muted hover:text-accent hover:border-accent'
+        }`}
+      >
+        {opt.label}
+      </a>
+    ))
+  }
+</nav>

package/src/index.ts

@@ -0,0 +1,11 @@
+export { blogSchema, buildBlogPostingSchema } from './lib/schema';
+export type { BlogPostingSchemaOptions } from './lib/schema';
+export { scoreRelated, normalizeTag } from './lib/relatedPosts';
+export type { ScoreRelatedOptions } from './lib/relatedPosts';
+export { filterPostsByTag } from './lib/filterPosts';
+export { shikiConfig } from './lib/shiki';
+export { buildRssItems } from './lib/rss';
+export type { RssItem } from './lib/rss';
+export type { BlogPostData, BlogPostLike, HeroImageCredit } from './lib/types';
+export { t, formatDate } from './lib/i18n';
+export type { Locale } from './lib/i18n';

package/src/lib/filterPosts.ts

@@ -0,0 +1,18 @@
+import type { BlogPostLike } from './types';
+import { normalizeTag } from './relatedPosts.ts';
+
+/**
+ * Returns posts from `posts` carrying `tag` (case-insensitive, alias-aware via the
+ * same `aliases` map `scoreRelated`/`normalizeTag` use). Does not sort - callers
+ * already sort before paginating (see per-app glue in the README).
+ */
+export function filterPostsByTag<T extends BlogPostLike>(
+  posts: T[],
+  tag: string,
+  aliases: Record<string, string> = {}
+): T[] {
+  const target = normalizeTag(tag, aliases);
+  return posts.filter((post) =>
+    (post.data.tags ?? []).some((t) => normalizeTag(t, aliases) === target)
+  );
+}

package/src/lib/i18n.ts

@@ -0,0 +1,66 @@
+export type Locale = 'en' | 'es';
+
+interface Strings {
+  readMore: string;
+  read: string;
+  relatedReading: string;
+  goToFirstPage: string;
+  goToPreviousPage: string;
+  goToNextPage: string;
+  goToLastPage: string;
+  pageOf: (current: number, last: number) => string;
+  onThisPage: string;
+  minRead: (minutes: number) => string;
+  blogPagination: string;
+  filterPosts: string;
+  photoCredit: string;
+  via: string;
+}
+
+const STRINGS: Record<Locale, Strings> = {
+  en: {
+    readMore: 'Read More',
+    read: 'Read',
+    relatedReading: 'Related reading',
+    goToFirstPage: 'Go to first page',
+    goToPreviousPage: 'Go to previous page',
+    goToNextPage: 'Go to next page',
+    goToLastPage: 'Go to last page',
+    pageOf: (current, last) => `Page ${current} of ${last}`,
+    onThisPage: 'On this page',
+    minRead: (minutes) => `${minutes} min read`,
+    blogPagination: 'Blog pagination',
+    filterPosts: 'Filter posts',
+    photoCredit: 'Photo:',
+    via: 'via',
+  },
+  es: {
+    readMore: 'Leer más',
+    read: 'Leer',
+    relatedReading: 'Lecturas relacionadas',
+    goToFirstPage: 'Ir a la primera página',
+    goToPreviousPage: 'Ir a la página anterior',
+    goToNextPage: 'Ir a la página siguiente',
+    goToLastPage: 'Ir a la última página',
+    pageOf: (current, last) => `Página ${current} de ${last}`,
+    onThisPage: 'En esta página',
+    minRead: (minutes) => `${minutes} min de lectura`,
+    blogPagination: 'Paginación del blog',
+    filterPosts: 'Filtrar publicaciones',
+    photoCredit: 'Foto:',
+    via: 'vía',
+  },
+};
+
+export function t(locale: Locale = 'en'): Strings {
+  return STRINGS[locale];
+}
+
+const DATE_LOCALE: Record<Locale, string> = {
+  en: 'en-US',
+  es: 'es',
+};
+
+export function formatDate(date: Date, locale: Locale = 'en', options?: Intl.DateTimeFormatOptions): string {
+  return date.toLocaleDateString(DATE_LOCALE[locale], options ?? { year: 'numeric', month: 'long', day: 'numeric' });
+}

package/src/lib/relatedPosts.ts

@@ -0,0 +1,55 @@
+import type { BlogPostLike } from './types';
+
+export interface ScoreRelatedOptions {
+  /** Max number of related posts to return. Defaults to 3. */
+  k?: number;
+  /**
+   * Collapse known tag spelling variants to a canonical form (after lowercasing).
+   * Content-specific, so it's passed in rather than baked in. Example:
+   *   { pihole: 'pi-hole', homeassistant: 'home-assistant', ha: 'home-assistant' }
+   */
+  aliases?: Record<string, string>;
+}
+
+export function normalizeTag(tag: string, aliases: Record<string, string> = {}): string {
+  const lower = tag.toLowerCase().trim();
+  return aliases[lower] ?? lower;
+}
+
+function jaccard(a: string[], b: string[], aliases: Record<string, string>): number {
+  if (a.length === 0 || b.length === 0) return 0;
+  const sa = new Set(a.map((t) => normalizeTag(t, aliases)));
+  const sb = new Set(b.map((t) => normalizeTag(t, aliases)));
+  let overlap = 0;
+  for (const t of sa) if (sb.has(t)) overlap++;
+  return overlap / (sa.size + sb.size - overlap);
+}
+
+/**
+ * Returns up to `k` posts from `candidates` most related to `target`, ordered by
+ * tag Jaccard similarity (+0.1 same-category bonus), then recency. Only posts with
+ * score > 0 are returned.
+ */
+export function scoreRelated(
+  target: BlogPostLike,
+  candidates: BlogPostLike[],
+  options: ScoreRelatedOptions = {}
+): BlogPostLike[] {
+  const { k = 3, aliases = {} } = options;
+  const tTags = target.data.tags ?? [];
+
+  return candidates
+    .filter((c) => c.id !== target.id)
+    .map((c) => {
+      let score = jaccard(tTags, c.data.tags ?? [], aliases);
+      if (score > 0 && c.data.category === target.data.category) score += 0.1;
+      return { entry: c, score };
+    })
+    .filter((s) => s.score > 0)
+    .sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score;
+      return b.entry.data.pubDate.getTime() - a.entry.data.pubDate.getTime();
+    })
+    .slice(0, k)
+    .map((s) => s.entry);
+}

package/src/lib/remark-reading-time.ts

@@ -0,0 +1,49 @@
+const WORDS_PER_MINUTE = 200;
+
+/** Minimal shape this plugin cares about - avoids a mdast-util-* type dependency. */
+interface MdastNode {
+  type: string;
+  value?: string;
+  children?: MdastNode[];
+}
+
+interface VFileWithAstroFrontmatter {
+  data?: {
+    astro?: {
+      frontmatter?: {
+        minutesRead?: number;
+      };
+    };
+  };
+}
+
+function collectText(node: MdastNode, out: string[]) {
+  if (typeof node.value === 'string') out.push(node.value);
+  if (node.children) {
+    for (const child of node.children) collectText(child, out);
+  }
+}
+
+/**
+ * Remark plugin: counts words in the post body and writes the rounded-up
+ * reading time (at 200 wpm) to `minutesRead` in the page's frontmatter.
+ *
+ *   import { remarkReadingTime } from '@vdaluz/astro-blog/remark';
+ *
+ *   export default defineConfig({
+ *     markdown: { remarkPlugins: [remarkReadingTime] },
+ *   });
+ */
+export function remarkReadingTime() {
+  return (tree: MdastNode, file: VFileWithAstroFrontmatter) => {
+    const textParts: string[] = [];
+    collectText(tree, textParts);
+    const wordCount = textParts.join(' ').split(/\s+/).filter(Boolean).length;
+    const minutesRead = Math.max(1, Math.ceil(wordCount / WORDS_PER_MINUTE));
+
+    file.data ??= {};
+    file.data.astro ??= {};
+    file.data.astro.frontmatter ??= {};
+    file.data.astro.frontmatter.minutesRead = minutesRead;
+  };
+}

package/src/lib/rss.ts

@@ -0,0 +1,34 @@
+import type { BlogPostLike } from './types';
+
+/**
+ * Structurally assignable to @astrojs/rss's `RSSFeedItem` — this package doesn't
+ * depend on @astrojs/rss itself, so consumers pass `buildRssItems(posts)` straight
+ * into `rss({ items })` from their own app-local route.
+ */
+export interface RssItem {
+  title: string;
+  description: string;
+  pubDate: Date;
+  link: string;
+  categories?: string[];
+}
+
+/**
+ * Maps posts to RSS feed items. `link` is root-relative (`${basePath}/${post.id}`);
+ * @astrojs/rss resolves relative links against `site` itself.
+ *
+ * `author` is intentionally not mapped: the RSS spec's `author` field expects an
+ * email address, but `BlogPostData.author` is a display name.
+ */
+export function buildRssItems(posts: BlogPostLike[], opts?: { basePath?: string }): RssItem[] {
+  const prefix = (opts?.basePath ?? '/blog').replace(/\/$/, '');
+  return posts.map((post) => ({
+    title: post.data.title,
+    description: post.data.description,
+    pubDate: post.data.pubDate,
+    link: `${prefix}/${post.id}`,
+    categories: [post.data.category, ...(post.data.tags ?? [])].filter(
+      (c, i, a) => a.indexOf(c) === i,
+    ),
+  }));
+}

package/src/lib/schema.ts

@@ -0,0 +1,83 @@
+import { z } from 'astro/zod';
+import type { BlogPostLike } from './types';
+
+/**
+ * Zod schema for a blog collection. Pass `defaultAuthor` to set the per-site
+ * fallback author. Use in the consuming app's content config:
+ *
+ *   import { defineCollection } from 'astro:content';
+ *   import { glob } from 'astro/loaders';
+ *   import { blogSchema } from '@vdaluz/astro-blog';
+ *
+ *   const blog = defineCollection({
+ *     loader: glob({ pattern: '**\/*.md', base: './src/content/blog' }),
+ *     schema: blogSchema({ defaultAuthor: 'Imperfect Systems' }),
+ *   });
+ *   export const collections = { blog };
+ */
+export function blogSchema(opts: { defaultAuthor?: string } = {}) {
+  return z.object({
+    title: z.string(),
+    description: z.string(),
+    pubDate: z.coerce.date(),
+    updatedDate: z.coerce.date().optional(),
+    category: z.string(),
+    author: z.string().default(opts.defaultAuthor ?? ''),
+    tags: z.array(z.string()).optional(),
+    heroImage: z.string().optional(),
+    heroImageCredit: z
+      .object({
+        name: z.string(),
+        url: z.string().url(),
+        source: z.enum(['pexels', 'unsplash', 'openverse']),
+        licenseName: z.string().optional(),
+        licenseUrl: z.string().url().optional(),
+      })
+      .optional(),
+    /** Affiliate program keys used by this post, e.g. ["amazon"]. See @vdaluz/astro-affiliate. */
+    affiliates: z.array(z.string()).optional(),
+  });
+}
+
+export interface BlogPostingSchemaOptions {
+  post: BlogPostLike;
+  /** Origin only, e.g. "https://imperfectsystems.com" (trailing slash tolerated). */
+  siteUrl: string;
+  /** Route prefix posts live under. Defaults to "/blog". */
+  basePath?: string;
+  /** Site/brand name for the JSON-LD publisher. Falls back to the post author. */
+  publisherName?: string;
+  /** BCP 47 language tag for the `inLanguage` field, e.g. "en" or "es". Omitted if unset. */
+  locale?: string;
+}
+
+/**
+ * Builds a schema.org BlogPosting object for a post. Render it as JSON-LD via the
+ * `BlogPostMeta.astro` component, or pass it to a Layout that injects `schema`.
+ */
+export function buildBlogPostingSchema({
+  post,
+  siteUrl,
+  basePath = '/blog',
+  publisherName,
+  locale,
+}: BlogPostingSchemaOptions) {
+  const origin = siteUrl.replace(/\/$/, '');
+  const prefix = basePath.replace(/\/$/, '');
+  const postUrl = `${origin}${prefix}/${post.id}`;
+  const authorName = post.data.author || publisherName || '';
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BlogPosting',
+    headline: post.data.title,
+    description: post.data.description,
+    datePublished: post.data.pubDate.toISOString(),
+    dateModified: (post.data.updatedDate ?? post.data.pubDate).toISOString(),
+    author: { '@type': 'Person', name: authorName, url: origin },
+    publisher: { '@type': 'Person', name: publisherName || authorName, url: origin },
+    url: postUrl,
+    mainEntityOfPage: { '@type': 'WebPage', '@id': postUrl },
+    ...(post.data.heroImage ? { image: `${origin}${post.data.heroImage}` } : {}),
+    ...(locale ? { inLanguage: locale } : {}),
+  };
+}

package/src/lib/shiki.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared Shiki config for `markdown.shikiConfig` in astro.config.mjs.
+ *
+ * `defaultColor: false` makes Shiki emit `--shiki-light` / `--shiki-dark` CSS vars
+ * instead of baked-in colors. The matching CSS handoff (see styles/tokens.example.css)
+ * picks the right one based on the `.dark` class on <html>. The two MUST ship together
+ * or code blocks render with no color.
+ *
+ * Dark-only sites: keep this config and force `<html class="dark">` so the dark vars
+ * always apply (no toggle needed).
+ */
+export const shikiConfig = {
+  themes: {
+    light: 'github-light-high-contrast',
+    dark: 'github-dark-high-contrast',
+  },
+  defaultColor: false as const,
+};

package/src/lib/types.ts

@@ -0,0 +1,35 @@
+/**
+ * Structural shape the blog components and helpers operate on.
+ *
+ * Deliberately NOT `CollectionEntry<'blog'>` from `astro:content`: that ties the
+ * package to a collection literally named "blog" in the consuming app. A site's
+ * `getCollection(...)` result is structurally assignable to `BlogPostLike` as long
+ * as its frontmatter matches `blogSchema()`, so consumers pass their entries directly.
+ */
+export interface HeroImageCredit {
+  name: string;
+  url: string;
+  source: 'pexels' | 'unsplash' | 'openverse';
+  licenseName?: string;
+  licenseUrl?: string;
+}
+
+export interface BlogPostData {
+  title: string;
+  description: string;
+  pubDate: Date;
+  updatedDate?: Date;
+  category: string;
+  author?: string;
+  tags?: string[];
+  heroImage?: string;
+  heroImageCredit?: HeroImageCredit;
+  /** Affiliate program keys used by this post, e.g. ["amazon"]. See @vdaluz/astro-affiliate. */
+  affiliates?: string[];
+}
+
+export interface BlogPostLike {
+  /** Astro content-collection entry id, used to build the post URL. */
+  id: string;
+  data: BlogPostData;
+}

package/src/styles/tokens.example.css

@@ -0,0 +1,71 @@
+/* ============================================================
+   @vdaluz/astro-blog — token contract
+   ------------------------------------------------------------
+   The package components reference ONLY these token names (never
+   hard-coded colors). Each consuming site must define them. Values
+   are R G B channel triplets so Tailwind's
+   `rgb(var(--name) / <alpha-value>)` pipeline works.
+
+   Copy this file into your app (e.g. src/styles/theme.css), keep the
+   variable NAMES, and replace the VALUES with your palette.
+
+   Your tailwind.config.mjs must alias these names — see README.
+   ============================================================ */
+
+:root {
+  color-scheme: light;
+
+  --bg: 250 250 250; /* page background */
+  --surface: 255 255 255; /* card / panel surface (should read as elevated vs --bg) */
+  --surface-muted: 218 219 225; /* tag pill, dimmed card, hover */
+
+  --fg: 52 59 89; /* primary text */
+  --muted: 92 94 110; /* secondary text, dates (keep >= 4.5:1 on --bg) */
+
+  --border: 220 222 230; /* dividers, input borders */
+
+  --accent: 41 89 170; /* links, category labels */
+  --accent-strong: 27 70 145; /* link hover / active */
+  --accent-soft: 230 234 245; /* tinted bg behind accents (blockquote, pill) */
+  --on-accent: 255 255 255; /* text on a solid --accent background */
+}
+
+/* Dark theme. Sites with a light/dark toggle override under `.dark`.
+   Dark-only sites: force `<html class="dark">` and only this block applies. */
+.dark {
+  color-scheme: dark;
+
+  --bg: 26 27 38;
+  --surface: 36 37 52;
+  --surface-muted: 50 54 79;
+
+  --fg: 169 177 214;
+  --muted: 154 160 189;
+
+  --border: 54 59 84;
+
+  --accent: 122 162 247;
+  --accent-strong: 125 207 255;
+  --accent-soft: 41 47 73;
+  --on-accent: 26 27 38;
+}
+
+/* ============================================================
+   Shiki dual-theme handoff (REQUIRED for code blocks)
+   Pairs with `shikiConfig` (defaultColor: false) from the package.
+   Shiki sets --shiki-light/--shiki-dark inline on <pre> and token
+   <span>s; these rules pick one based on the `.dark` class on <html>.
+   Ship this together with the config or code blocks lose color.
+   ============================================================ */
+html pre {
+  background-color: var(--shiki-light-bg);
+}
+html pre code span {
+  color: var(--shiki-light);
+}
+html.dark pre {
+  background-color: var(--shiki-dark-bg);
+}
+html.dark pre code span {
+  color: var(--shiki-dark);
+}