@vdaluz/astro-blog 0.10.0 → 0.11.0

package/README.md

@@ -97,7 +97,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 +119,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.

package/package.json

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