@vdaluz/astro-blog 0.10.0 → 0.12.0

package/README.md

@@ -1,6 +1,8 @@
 # @vdaluz/astro-blog
 
+[![npm version](https://img.shields.io/npm/v/@vdaluz/astro-blog.svg)](https://www.npmjs.com/package/@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)
+[![license](https://img.shields.io/npm/l/@vdaluz/astro-blog.svg)](LICENSE)
 
 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).
 
@@ -12,21 +14,6 @@ A blog needs a listing page, pagination, related posts, tag filters, JSON-LD, RS
 npm install @vdaluz/astro-blog
 ```
 
-Alternatively, a pinned https tarball from a tag works too, with no registry involved:
-
-```jsonc
-// package.json
-"dependencies": {
-  "@vdaluz/astro-blog": "https://github.com/vdaluz/astro-blog/archive/refs/tags/v0.9.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.
-
 Peer dependency: `astro` >= 6. For post body styling you'll also want `@tailwindcss/typography` in the app.
 
 ## Four things every consumer MUST do
@@ -97,7 +84,7 @@ Peer dependency: `astro` >= 6. For post body styling you'll also want `@tailwind
 
 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`, `RelatedPosts`, `Pagination`, and `BlogPostMeta` accept an optional `locale` prop (default `'en'`) that localizes their built-in UI strings (dates, "Read More", pagination labels) and `BlogPostMeta`'s JSON-LD `inLanguage` field. `Locale` ships built-in strings for `'en' | 'es' | 'pt'` (autocompleted in editors) but accepts any string - an unrecognized locale falls back to the `en` strings and passes the raw string through to `Intl.DateTimeFormat` for date formatting. Call `t(locale, overrides)` directly with a `Partial<Strings>` to supply your own strings for a locale the package doesn't ship. 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.
 
@@ -119,6 +106,10 @@ import HeroImageCredit from '@vdaluz/astro-blog/HeroImageCredit.astro';
 
 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.
 
+### Trailing slash
+
+`buildBlogPostingSchema`/`BlogPostMeta` build the JSON-LD `url`/`mainEntityOfPage.@id` fields without a trailing slash by default. If your site's actual canonical post URL is slash-terminated, pass `trailingSlash={true}` - otherwise the JSON-LD `url` disagrees with your page's own `<link rel="canonical">`, which can cause search engines to pick the wrong canonical form. Check your real canonical output before setting this, not just your app's `trailingSlash` config: prerendered routes on some hosts are served slash-terminated regardless of that config (confirm with `curl -sI` on a bare post URL - a `307`/`308` to the slash form means you need `trailingSlash={true}`).
+
 ### 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.
@@ -236,3 +227,7 @@ Issues welcome. PRs by discussion - open an issue first for anything beyond a ty
 
 - [vdaluz.com](https://vdaluz.com)
 - [imperfectsystems.com](https://imperfectsystems.com)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vdaluz/astro-blog",
-  "version": "0.10.0",
+  "version": "0.12.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",

package/src/components/BlogPostMeta.astro

@@ -13,10 +13,19 @@ interface Props {
   publisherName?: string;
   /** Locale for the JSON-LD `inLanguage` field. Omitted if unset. */
   locale?: Locale;
+  /** Whether this site's canonical post URL ends in a trailing slash. Defaults to false. */
+  trailingSlash?: boolean;
 }
 
-const { post, siteUrl, basePath = '/blog', publisherName, locale } = Astro.props;
-const schema = buildBlogPostingSchema({ post, siteUrl, basePath, publisherName, locale });
+const { post, siteUrl, basePath = '/blog', publisherName, locale, trailingSlash } = Astro.props;
+const schema = buildBlogPostingSchema({
+  post,
+  siteUrl,
+  basePath,
+  publisherName,
+  locale,
+  trailingSlash,
+});
 ---
 
 {/* JSON-LD is valid in <body>; render this anywhere inside the post page. */}

package/src/index.ts

@@ -7,5 +7,5 @@ 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';
+export { t, formatDate, BUILT_IN_LOCALES } from './lib/i18n';
+export type { Locale, Strings } from './lib/i18n';

package/src/lib/i18n.ts

@@ -1,6 +1,10 @@
-export type Locale = 'en' | 'es' | 'pt';
+export const BUILT_IN_LOCALES = ['en', 'es', 'pt'] as const;
+type BuiltInLocale = (typeof BUILT_IN_LOCALES)[number];
 
-interface Strings {
+/** Any string is accepted; 'en' | 'es' | 'pt' still autocomplete since they're valid members. */
+export type Locale = BuiltInLocale | (string & {});
+
+export interface Strings {
   readMore: string;
   read: string;
   relatedReading: string;
@@ -17,7 +21,7 @@ interface Strings {
   via: string;
 }
 
-const STRINGS: Record<Locale, Strings> = {
+const STRINGS: Record<BuiltInLocale, Strings> = {
   en: {
     readMore: 'Read More',
     read: 'Read',
@@ -68,16 +72,18 @@ const STRINGS: Record<Locale, Strings> = {
   },
 };
 
-export function t(locale: Locale = 'en'): Strings {
-  return STRINGS[locale];
+export function t(locale: Locale = 'en', overrides?: Partial<Strings>): Strings {
+  const base = STRINGS[locale as BuiltInLocale] ?? STRINGS.en;
+  return overrides ? { ...base, ...overrides } : base;
 }
 
-const DATE_LOCALE: Record<Locale, string> = {
+const DATE_LOCALE: Record<BuiltInLocale, string> = {
   en: 'en-US',
   es: 'es',
   pt: 'pt-BR',
 };
 
 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' });
+  const dateLocale = DATE_LOCALE[locale as BuiltInLocale] ?? locale;
+  return date.toLocaleDateString(dateLocale, options ?? { year: 'numeric', month: 'long', day: 'numeric' });
 }

package/src/lib/schema.ts

@@ -49,6 +49,16 @@ export interface BlogPostingSchemaOptions {
   publisherName?: string;
   /** BCP 47 language tag for the `inLanguage` field, e.g. "en" or "es". Omitted if unset. */
   locale?: string;
+  /**
+   * Whether this site's actual served/canonical post URL ends in a trailing slash.
+   * Defaults to false. Check your own `<link rel="canonical">` output (and served-URL
+   * behavior - prerendered routes on some hosts are slash-terminated regardless of the
+   * app's own trailingSlash config) before setting this; don't assume it from the app
+   * config alone. Mismatching this from the real canonical produces a self-inconsistent
+   * page (JSON-LD `url` disagreeing with the declared canonical), which can cause search
+   * engines to pick the wrong canonical form.
+   */
+  trailingSlash?: boolean;
 }
 
 /**
@@ -61,10 +71,11 @@ export function buildBlogPostingSchema({
   basePath = '/blog',
   publisherName,
   locale,
+  trailingSlash = false,
 }: BlogPostingSchemaOptions) {
   const origin = siteUrl.replace(/\/$/, '');
   const prefix = basePath.replace(/\/$/, '');
-  const postUrl = `${origin}${prefix}/${post.id}`;
+  const postUrl = `${origin}${prefix}/${post.id}${trailingSlash ? '/' : ''}`;
   const authorName = post.data.author || publisherName || '';
   return {
     '@context': 'https://schema.org',