@xexr/blog-platform 1.0.7 → 1.0.9

package/dist/lib/mdx.ts

@@ -0,0 +1,73 @@
+import remarkGfm from "remark-gfm";
+import remarkToc from "remark-toc";
+import rehypeSlug from "rehype-slug";
+
+interface HastNode {
+  type?: string;
+  tagName?: string;
+  value?: string;
+  children?: HastNode[];
+}
+
+export const articleMdxOptions = {
+  mdxOptions: {
+    remarkPlugins: [remarkToc, remarkGfm],
+    rehypePlugins: [rehypeUnwrapStandaloneImages, rehypeSlug],
+  },
+};
+
+export function rehypeUnwrapStandaloneImages() {
+  return (tree: HastNode) => {
+    unwrapStandaloneImages(tree);
+  };
+}
+
+function unwrapStandaloneImages(node: HastNode) {
+  if (!node.children) {
+    return;
+  }
+
+  node.children = node.children.flatMap((child) => {
+    unwrapStandaloneImages(child);
+
+    if (isStandaloneImageParagraph(child)) {
+      return child.children?.filter(isMeaningfulNode) ?? [child];
+    }
+
+    return [child];
+  });
+}
+
+function isStandaloneImageParagraph(node: HastNode): boolean {
+  if (node.type !== "element" || node.tagName !== "p" || !node.children) {
+    return false;
+  }
+
+  const meaningfulChildren = node.children.filter(isMeaningfulNode);
+  return (
+    meaningfulChildren.length === 1 && isImageLikeNode(meaningfulChildren[0])
+  );
+}
+
+function isImageLikeNode(node: HastNode | undefined): boolean {
+  if (node?.type !== "element") {
+    return false;
+  }
+
+  if (node.tagName === "img") {
+    return true;
+  }
+
+  if (node.tagName !== "a" || !node.children) {
+    return false;
+  }
+
+  const meaningfulChildren = node.children.filter(isMeaningfulNode);
+  return (
+    meaningfulChildren.length === 1 && meaningfulChildren[0]?.tagName === "img"
+  );
+}
+
+function isMeaningfulNode(node: HastNode): boolean {
+  return node.type !== "text" || Boolean(node.value?.trim());
+}

package/dist/lib/metadata.ts

@@ -0,0 +1,558 @@
+/**
+ * Metadata generation utilities for SEO meta tags, OpenGraph, and Twitter Cards.
+ *
+ * These utilities create comprehensive metadata for blog articles and pages,
+ * optimizing for search engines and social media sharing platforms.
+ */
+
+import type { PublishedArticle, PublishedSite } from '../types/contracts';
+import { generateCanonicalUrl, type CanonicalUrlOptions } from './seo';
+
+/**
+ * Configuration options for metadata generation.
+ */
+export interface MetadataOptions {
+  /** Canonical URL generation options */
+  canonical?: CanonicalUrlOptions;
+
+  /** OpenGraph configuration */
+  openGraph?: {
+    /** Site name for OpenGraph */
+    siteName?: string;
+    /** Default OpenGraph image URL */
+    defaultImage?: string;
+    /** OpenGraph locale (defaults to site locale) */
+    locale?: string;
+    /** OpenGraph type (defaults to 'article') */
+    type?: 'article' | 'website';
+  };
+
+  /** Twitter Card configuration */
+  twitter?: {
+    /** Twitter site handle (e.g., '@blogname') */
+    site?: string;
+    /** Twitter creator handle (e.g., '@authorname') */
+    creator?: string;
+    /** Default Twitter card type */
+    cardType?: 'summary' | 'summary_large_image' | 'app' | 'player';
+  };
+
+  /** Additional meta tag configuration */
+  meta?: {
+    /** Robots meta tag directive */
+    robots?: string;
+    /** Viewport meta tag content */
+    viewport?: string;
+    /** Theme color for mobile browsers */
+    themeColor?: string;
+    /** Application name */
+    applicationName?: string;
+  };
+}
+
+/**
+ * Generated metadata for HTML head section.
+ */
+export interface GeneratedMetadata {
+  /** Basic HTML meta tags */
+  meta: MetaTag[];
+
+  /** OpenGraph meta tags */
+  openGraph: MetaTag[];
+
+  /** Twitter Card meta tags */
+  twitter: MetaTag[];
+
+  /** Link tags (canonical, etc.) */
+  links: LinkTag[];
+
+  /** Title tag content */
+  title: string;
+
+  /** Meta description content */
+  description: string;
+
+  /** Canonical URL */
+  canonicalUrl: string;
+}
+
+/**
+ * HTML meta tag representation.
+ */
+export interface MetaTag {
+  name?: string;
+  property?: string;
+  content: string;
+  httpEquiv?: string;
+}
+
+/**
+ * HTML link tag representation.
+ */
+export interface LinkTag {
+  rel: string;
+  href: string;
+  type?: string;
+  title?: string;
+}
+
+/**
+ * Generates comprehensive metadata for an article page.
+ *
+ * @param article - The published article
+ * @param options - Metadata generation options
+ * @returns Complete metadata for HTML head section
+ *
+ * @example
+ * ```typescript
+ * const metadata = generateArticleMetadata(article, {
+ *   openGraph: {
+ *     siteName: 'My Blog',
+ *     defaultImage: 'https://example.com/og-default.jpg'
+ *   },
+ *   twitter: {
+ *     site: '@myblog',
+ *     cardType: 'summary_large_image'
+ *   }
+ * });
+ * ```
+ */
+export function generateArticleMetadata(
+  article: PublishedArticle,
+  options: MetadataOptions = {}
+): GeneratedMetadata {
+  const canonicalUrl = generateCanonicalUrl(article, options.canonical);
+  const title = article.meta.title ?? article.title;
+  const description = article.meta.description ?? article.excerpt;
+  const siteName = options.openGraph?.siteName ?? article.site.name;
+
+  // Basic meta tags
+  const meta: MetaTag[] = [
+    { name: 'description', content: description },
+    { name: 'keywords', content: article.meta.keywords.join(', ') },
+    { name: 'author', content: article.author?.name ?? siteName },
+    { name: 'published_time', content: article.publishedAt },
+    { name: 'modified_time', content: article.updatedAt },
+    { name: 'article:reading_time', content: Math.ceil(article.readingSeconds / 60).toString() },
+  ];
+
+  // Add robots meta if specified
+  if (options.meta?.robots) {
+    meta.push({ name: 'robots', content: options.meta.robots });
+  }
+
+  // Add viewport meta if specified
+  if (options.meta?.viewport) {
+    meta.push({ name: 'viewport', content: options.meta.viewport });
+  }
+
+  // Add theme color if specified
+  if (options.meta?.themeColor) {
+    meta.push({ name: 'theme-color', content: options.meta.themeColor });
+  }
+
+  // Add application name if specified
+  if (options.meta?.applicationName) {
+    meta.push({ name: 'application-name', content: options.meta.applicationName });
+  }
+
+  // Generate OpenGraph metadata
+  const openGraph = generateOpenGraphMetadata(article, canonicalUrl, {
+    siteName,
+    defaultImage: options.openGraph?.defaultImage,
+    locale: options.openGraph?.locale ?? article.site.locale,
+    type: options.openGraph?.type ?? 'article',
+  });
+
+  // Generate Twitter Card metadata
+  const twitter = generateTwitterCardMetadata(article, {
+    site: options.twitter?.site,
+    creator: options.twitter?.creator,
+    cardType: options.twitter?.cardType ?? 'summary_large_image',
+  });
+
+  // Generate link tags
+  const links: LinkTag[] = [
+    { rel: 'canonical', href: canonicalUrl },
+  ];
+
+  return {
+    meta,
+    openGraph,
+    twitter,
+    links,
+    title,
+    description,
+    canonicalUrl,
+  };
+}
+
+/**
+ * Generates metadata for a blog home page or listing page.
+ *
+ * @param site - The published site information
+ * @param options - Metadata generation options
+ * @param pageInfo - Optional page-specific information
+ * @returns Complete metadata for HTML head section
+ *
+ * @example
+ * ```typescript
+ * const metadata = generateSiteMetadata(site, {
+ *   openGraph: {
+ *     defaultImage: 'https://example.com/og-home.jpg'
+ *   }
+ * }, {
+ *   title: 'Latest Articles',
+ *   description: 'Browse our latest blog posts',
+ *   path: '/blog'
+ * });
+ * ```
+ */
+export function generateSiteMetadata(
+  site: PublishedSite,
+  options: MetadataOptions = {},
+  pageInfo?: {
+    title?: string;
+    description?: string;
+    path?: string;
+    pageNumber?: number;
+  }
+): GeneratedMetadata {
+  const path = pageInfo?.path ?? '/blog';
+  const domain = options.canonical?.domain ?? site.domain;
+  const canonicalUrl = `https://${domain}${path}`;
+
+  const title = pageInfo?.title
+    ? `${pageInfo.title} | ${site.name}`
+    : site.name;
+
+  const description = pageInfo?.description ?? site.description;
+  const siteName = options.openGraph?.siteName ?? site.name;
+
+  // Basic meta tags
+  const meta: MetaTag[] = [
+    { name: 'description', content: description },
+    { name: 'author', content: siteName },
+  ];
+
+  // Add page number for pagination
+  if (pageInfo?.pageNumber && pageInfo.pageNumber > 1) {
+    meta.push({ name: 'page', content: pageInfo.pageNumber.toString() });
+  }
+
+  // Add robots meta if specified
+  if (options.meta?.robots) {
+    meta.push({ name: 'robots', content: options.meta.robots });
+  }
+
+  // Add viewport meta if specified
+  if (options.meta?.viewport) {
+    meta.push({ name: 'viewport', content: options.meta.viewport });
+  }
+
+  // Add theme color if specified
+  if (options.meta?.themeColor) {
+    meta.push({ name: 'theme-color', content: options.meta.themeColor });
+  }
+
+  // Add application name if specified
+  if (options.meta?.applicationName) {
+    meta.push({ name: 'application-name', content: options.meta.applicationName });
+  }
+
+  // Generate OpenGraph metadata for site
+  const openGraph: MetaTag[] = [
+    { property: 'og:title', content: title },
+    { property: 'og:description', content: description },
+    { property: 'og:url', content: canonicalUrl },
+    { property: 'og:site_name', content: siteName },
+    { property: 'og:locale', content: options.openGraph?.locale ?? site.locale },
+    { property: 'og:type', content: options.openGraph?.type ?? 'website' },
+  ];
+
+  // Add default OpenGraph image if provided
+  if (options.openGraph?.defaultImage) {
+    openGraph.push(
+      { property: 'og:image', content: options.openGraph.defaultImage },
+      { property: 'og:image:alt', content: `${siteName} - ${site.tagline}` }
+    );
+  }
+
+  // Generate Twitter Card metadata
+  const twitter = generateTwitterCardMetadata(
+    null, // No article for site pages
+    {
+      site: options.twitter?.site,
+      creator: options.twitter?.creator,
+      cardType: options.twitter?.cardType ?? 'summary',
+    },
+    {
+      title,
+      description,
+      image: options.openGraph?.defaultImage,
+    }
+  );
+
+  // Generate link tags
+  const links: LinkTag[] = [
+    { rel: 'canonical', href: canonicalUrl },
+  ];
+
+  return {
+    meta,
+    openGraph,
+    twitter,
+    links,
+    title,
+    description,
+    canonicalUrl,
+  };
+}
+
+/**
+ * Generates OpenGraph metadata for an article.
+ */
+function generateOpenGraphMetadata(
+  article: PublishedArticle,
+  canonicalUrl: string,
+  options: {
+    siteName: string;
+    defaultImage?: string;
+    locale: string;
+    type: string;
+  }
+): MetaTag[] {
+  const title = article.meta.title ?? article.title;
+  const description = article.meta.description ?? article.excerpt;
+  const image = article.meta.ogImage ?? article.featuredImage ?? options.defaultImage;
+
+  const openGraph: MetaTag[] = [
+    { property: 'og:title', content: title },
+    { property: 'og:description', content: description },
+    { property: 'og:url', content: canonicalUrl },
+    { property: 'og:site_name', content: options.siteName },
+    { property: 'og:locale', content: options.locale },
+    { property: 'og:type', content: options.type },
+    { property: 'article:published_time', content: article.publishedAt },
+    { property: 'article:modified_time', content: article.updatedAt },
+  ];
+
+  // Add image if available
+  if (image) {
+    const imageAlt = article.featuredImageAlt ?? `${article.title} - ${options.siteName}`;
+    openGraph.push(
+      { property: 'og:image', content: image },
+      { property: 'og:image:alt', content: imageAlt }
+    );
+  }
+
+  // Add author information
+  if (article.author) {
+    openGraph.push({ property: 'article:author', content: article.author.name });
+
+    // Add author profile URL if we can construct one
+    if (article.author.slug) {
+      const authorUrl = canonicalUrl.replace(/\/[^/]+$/, `/authors/${article.author.slug}`);
+      openGraph.push({ property: 'article:author:url', content: authorUrl });
+    }
+  }
+
+  // Add article tags from keywords
+  article.meta.keywords.forEach(keyword => {
+    openGraph.push({ property: 'article:tag', content: keyword });
+  });
+
+  // Add reading time
+  const readingMinutes = Math.ceil(article.readingSeconds / 60);
+  openGraph.push({ property: 'article:reading_time', content: readingMinutes.toString() });
+
+  return openGraph;
+}
+
+/**
+ * Generates Twitter Card metadata.
+ */
+function generateTwitterCardMetadata(
+  article: PublishedArticle | null,
+  options: {
+    site?: string;
+    creator?: string;
+    cardType: string;
+  },
+  overrides?: {
+    title?: string;
+    description?: string;
+    image?: string;
+  }
+): MetaTag[] {
+  const title = overrides?.title ?? article?.meta.title ?? article?.title ?? '';
+  const description = overrides?.description ?? article?.meta.description ?? article?.excerpt ?? '';
+  const image = overrides?.image ?? article?.meta.ogImage ?? article?.featuredImage;
+
+  const twitter: MetaTag[] = [
+    { name: 'twitter:card', content: options.cardType },
+    { name: 'twitter:title', content: title },
+    { name: 'twitter:description', content: description },
+  ];
+
+  // Add site handle if provided
+  if (options.site) {
+    twitter.push({ name: 'twitter:site', content: options.site });
+  }
+
+  // Add creator handle if provided (for articles) or from options
+  if (article?.author && options.creator) {
+    twitter.push({ name: 'twitter:creator', content: options.creator });
+  } else if (options.creator) {
+    twitter.push({ name: 'twitter:creator', content: options.creator });
+  }
+
+  // Add image if available
+  if (image) {
+    twitter.push({ name: 'twitter:image', content: image });
+
+    if (article?.featuredImageAlt) {
+      twitter.push({ name: 'twitter:image:alt', content: article.featuredImageAlt });
+    }
+  }
+
+  return twitter;
+}
+
+/**
+ * Converts metadata to HTML string for server-side rendering.
+ *
+ * @param metadata - Generated metadata object
+ * @returns HTML string for head section
+ *
+ * @example
+ * ```typescript
+ * const metadata = generateArticleMetadata(article);
+ * const htmlHead = metadataToHtml(metadata);
+ * // Use in server-side rendering
+ * ```
+ */
+export function metadataToHtml(metadata: GeneratedMetadata): string {
+  const elements: string[] = [];
+
+  // Title
+  elements.push(`<title>${escapeHtml(metadata.title)}</title>`);
+
+  // Meta tags
+  metadata.meta.forEach(tag => {
+    const attrs: string[] = [];
+
+    if (tag.name) attrs.push(`name="${escapeHtml(tag.name)}"`);
+    if (tag.property) attrs.push(`property="${escapeHtml(tag.property)}"`);
+    if (tag.httpEquiv) attrs.push(`http-equiv="${escapeHtml(tag.httpEquiv)}"`);
+    attrs.push(`content="${escapeHtml(tag.content)}"`);
+
+    elements.push(`<meta ${attrs.join(' ')} />`);
+  });
+
+  // OpenGraph tags
+  metadata.openGraph.forEach(tag => {
+    elements.push(`<meta property="${escapeHtml(tag.property!)}" content="${escapeHtml(tag.content)}" />`);
+  });
+
+  // Twitter tags
+  metadata.twitter.forEach(tag => {
+    elements.push(`<meta name="${escapeHtml(tag.name!)}" content="${escapeHtml(tag.content)}" />`);
+  });
+
+  // Link tags
+  metadata.links.forEach(link => {
+    const attrs: string[] = [];
+    attrs.push(`rel="${escapeHtml(link.rel)}"`);
+    attrs.push(`href="${escapeHtml(link.href)}"`);
+    if (link.type) attrs.push(`type="${escapeHtml(link.type)}"`);
+    if (link.title) attrs.push(`title="${escapeHtml(link.title)}"`);
+
+    elements.push(`<link ${attrs.join(' ')} />`);
+  });
+
+  return elements.join('\n');
+}
+
+/**
+ * Escapes HTML special characters for safe inclusion in HTML attributes.
+ */
+function escapeHtml(text: string): string {
+  const htmlEscapes: Record<string, string> = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#x27;',
+  };
+
+  return text.replace(/[&<>"']/g, char => htmlEscapes[char] ?? char);
+}
+
+/**
+ * Validates that metadata meets SEO best practices.
+ *
+ * @param metadata - Generated metadata to validate
+ * @returns Validation results with warnings and errors
+ *
+ * @example
+ * ```typescript
+ * const metadata = generateArticleMetadata(article);
+ * const validation = validateMetadata(metadata);
+ *
+ * if (validation.errors.length > 0) {
+ *   console.error('Metadata errors:', validation.errors);
+ * }
+ * ```
+ */
+export function validateMetadata(metadata: GeneratedMetadata): {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+} {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Title validation
+  if (!metadata.title) {
+    errors.push('Title is required');
+  } else if (metadata.title.length > 60) {
+    warnings.push('Title longer than 60 characters may be truncated in search results');
+  } else if (metadata.title.length < 30) {
+    warnings.push('Title shorter than 30 characters may not be descriptive enough');
+  }
+
+  // Description validation
+  if (!metadata.description) {
+    errors.push('Meta description is required');
+  } else if (metadata.description.length > 160) {
+    warnings.push('Meta description longer than 160 characters may be truncated');
+  } else if (metadata.description.length < 120) {
+    warnings.push('Meta description shorter than 120 characters may not be descriptive enough');
+  }
+
+  // Canonical URL validation
+  if (!metadata.canonicalUrl) {
+    errors.push('Canonical URL is required');
+  } else if (!metadata.canonicalUrl.startsWith('https://')) {
+    warnings.push('Canonical URL should use HTTPS for better SEO');
+  }
+
+  // OpenGraph validation
+  const ogImage = metadata.openGraph.find(tag => tag.property === 'og:image');
+  if (!ogImage) {
+    warnings.push('OpenGraph image missing - social media sharing will not show image preview');
+  }
+
+  // Twitter Card validation
+  const twitterCard = metadata.twitter.find(tag => tag.name === 'twitter:card');
+  if (!twitterCard) {
+    warnings.push('Twitter Card type missing - Twitter sharing may not display properly');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}