@vdaluz/astro-blog 0.9.0 → 0.11.0

package/README.md

@@ -8,12 +8,16 @@ A blog needs a listing page, pagination, related posts, tag filters, JSON-LD, RS
 
 ## Install
 
-Pinned https tarball from a tag (no registry needed):
+```
+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.7.0.tar.gz"
+  "@vdaluz/astro-blog": "https://github.com/vdaluz/astro-blog/archive/refs/tags/v0.9.0.tar.gz"
 }
 ```
 
@@ -21,9 +25,7 @@ Pinned https tarball from a tag (no registry needed):
 > 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).
+> 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.
 
@@ -95,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.
 
@@ -117,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.9.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';
+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',
@@ -50,17 +54,36 @@ const STRINGS: Record<Locale, Strings> = {
     photoCredit: 'Foto:',
     via: 'vía',
   },
+  pt: {
+    readMore: 'Leia Mais',
+    read: 'Ler',
+    relatedReading: 'Leitura relacionada',
+    goToFirstPage: 'Ir para a primeira página',
+    goToPreviousPage: 'Ir para a página anterior',
+    goToNextPage: 'Ir para a próxima página',
+    goToLastPage: 'Ir para a última página',
+    pageOf: (current, last) => `Página ${current} de ${last}`,
+    onThisPage: 'Nesta página',
+    minRead: (minutes) => `${minutes} min de leitura`,
+    blogPagination: 'Paginação do blog',
+    filterPosts: 'Filtrar publicações',
+    photoCredit: 'Foto:',
+    via: 'via',
+  },
 };
 
-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',