@xexr/blog-platform 1.0.7 → 1.0.9

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.0.8
+
+### Patch Changes
+
+- Add reading progress and active table-of-contents state to public article pages.
+- Include route runtime dependencies in the package build output for subpath app imports.
+
 ## 1.0.1
 
 ### Patch Changes

package/README.md

@@ -170,9 +170,23 @@ export default async function BlogPage({
 
 ```tsx
 import "@/lib/blog-platform";
-import { BlogArticlePage, getStorage } from "@xexr/blog-platform";
+import {
+  BlogArticlePage,
+  getStorage,
+  generateArticleMetadata,
+} from "@xexr/blog-platform";
 import { notFound } from "next/navigation";
 
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const article = await getStorage().getArticle(slug);
+  return article ? generateArticleMetadata(article) : {};
+}
+
 export default async function ArticlePage({
   params,
 }: {
@@ -195,8 +209,10 @@ export default async function ArticlePage({
 
   // Find current article index
   const currentIndex = articles.findIndex((a) => a.slug === slug);
-  const previousArticle = currentIndex > 0 ? articles[currentIndex - 1] : undefined;
-  const nextArticle = currentIndex < articles.length - 1 ? articles[currentIndex + 1] : undefined;
+  const previousArticle =
+    currentIndex > 0 ? articles[currentIndex - 1] : undefined;
+  const nextArticle =
+    currentIndex < articles.length - 1 ? articles[currentIndex + 1] : undefined;
 
   return (
     <BlogArticlePage
@@ -223,6 +239,51 @@ export default async function ArticlePage({
 
 > **Note**: The `navigation` prop is optional. You can omit `previousArticle` and `nextArticle` if you don't want article navigation links.
 
+**`app/blog/authors/[slug]/page.tsx`** - Author profile pages:
+
+```tsx
+import "@/lib/blog-platform";
+import {
+  BlogAuthorPage,
+  generateAuthorPageMetadata,
+  loadAuthorArchive,
+} from "@xexr/blog-platform";
+import { notFound } from "next/navigation";
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const archive = await loadAuthorArchive(slug);
+  return archive
+    ? generateAuthorPageMetadata(archive.author, archive.articles[0]!.site)
+    : {};
+}
+
+export default async function AuthorPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const archive = await loadAuthorArchive(slug);
+  if (!archive) {
+    notFound();
+  }
+
+  return (
+    <BlogAuthorPage
+      author={archive.author}
+      articles={archive.articles}
+      site={archive.articles[0]!.site}
+      navigation={{ backToHome: { url: "/blog" } }}
+    />
+  );
+}
+```
+
 ### 2. Set Up Publishing API
 
 **`app/api/blog/publish/route.ts`**:
@@ -362,8 +423,8 @@ const nextConfig = {
   images: {
     remotePatterns: [
       {
-        protocol: 'https',
-        hostname: 'bloggy.poyzer.download', // Replace with your Bloggy instance domain
+        protocol: "https",
+        hostname: "bloggy.poyzer.download", // Replace with your Bloggy instance domain
       },
     ],
   },
@@ -454,11 +515,11 @@ Before you can publish articles, ensure you have:
 
 **Troubleshooting Connection Test**:
 
-| Issue | Solution |
-|-------|----------|
-| ❌ Invalid credentials | Check that `BLOG_PLATFORM_API_KEYS` in your .env matches the token you entered |
-| ❌ Connection failed | Verify your Blog Platform API URL is correct and accessible |
-| ❌ Version incompatible | Upgrade your blog platform package to match Bloggy's version |
+| Issue                   | Solution                                                                       |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| ❌ Invalid credentials  | Check that `BLOG_PLATFORM_API_KEYS` in your .env matches the token you entered |
+| ❌ Connection failed    | Verify your Blog Platform API URL is correct and accessible                    |
+| ❌ Version incompatible | Upgrade your blog platform package to match Bloggy's version                   |
 
 ### Step 2: Publish an Article
 
@@ -473,7 +534,6 @@ Before you can publish articles, ensure you have:
 
 3. **Configure Publication Settings**:
    The publish modal opens with pre-filled fields:
-
    - **URL Slug**: Auto-generated from the title (lowercase, hyphens)
      - Preview: `https://yourblog.com/blog/your-article-slug`
      - Editable: Change to your preferred slug
@@ -523,6 +583,7 @@ Before you can publish articles, ensure you have:
    - `dateModified` updates in JSON-LD, `datePublished` remains unchanged
 
 **What Gets Updated**:
+
 - ✅ Article content (title, body, images)
 - ✅ Meta description
 - ✅ `dateModified` timestamp
@@ -551,38 +612,44 @@ Before you can publish articles, ensure you have:
 
 ### Publishing Status Reference
 
-| Status | Description | Available Actions |
-|--------|-------------|-------------------|
-| **Never Published** | Article has never been published | ✅ Publish |
-| **Published** | Article is live on blog | ✅ Republish (update)<br>✅ Unpublish |
-| **Failed** | Publishing failed due to error | ✅ Retry publish |
-| **Publishing** | Publish in progress | ⏳ Wait (typically < 5s) |
+| Status              | Description                      | Available Actions                     |
+| ------------------- | -------------------------------- | ------------------------------------- |
+| **Never Published** | Article has never been published | ✅ Publish                            |
+| **Published**       | Article is live on blog          | ✅ Republish (update)<br>✅ Unpublish |
+| **Failed**          | Publishing failed due to error   | ✅ Retry publish                      |
+| **Publishing**      | Publish in progress              | ⏳ Wait (typically < 5s)              |
 
 ### Error Handling & Troubleshooting
 
 #### Common Publishing Errors
 
 **PUB003: Slug Already Exists**
+
 - **Cause**: Another article is already using this slug
 - **Solution**: Choose a different slug (add date, number, or variation)
 
 **PUB005: Invalid Credentials**
+
 - **Cause**: Authentication token doesn't match
 - **Solution**: Update token in platform settings and re-test connection
 
 **PUB006: Content Validation Failed**
+
 - **Cause**: Article doesn't meet publishing requirements
 - **Solution**: Check error details (usually min 50 words required)
 
 **PUB007: Platform Unavailable**
+
 - **Cause**: Blog platform is down or unreachable
 - **Solution**: Check your blog is running, then retry publish
 
 **PUB008: No Platform Configured**
+
 - **Cause**: Publishing platform not set up for this site
 - **Solution**: Go to Blog → Edit → Publishing and configure platform
 
 **PUB009: Version Incompatible**
+
 - **Cause**: Bloggy version doesn't match blog platform version (major mismatch)
 - **Solution**: Upgrade your `@xexr/blog-platform` package
 
@@ -601,11 +668,13 @@ If publishing fails:
 The blog platform displays author information based on Bloggy's author settings:
 
 **Author Resolution Order**:
+
 1. **Article Author**: If article has an assigned author, use that author
 2. **Site Default Author**: If no article author, use site's default author
 3. **No Author**: If neither available, publish without author byline
 
 **Guest Author Display**:
+
 - Guest authors (marked with `isGuest: true`) show **Guest Author** badge
 - Author bio card displays if `author.bio` is present
 - Author profile links are not included (post-MVP feature)
@@ -628,22 +697,26 @@ The blog platform displays author information based on Bloggy's author settings:
 When publishing articles, the blog platform automatically handles:
 
 **Meta Tags**:
+
 - `<title>`: Article title
 - `<meta name="description">`: Your custom meta description
 - `<link rel="canonical">`: Self-canonical URL
 
 **Structured Data (JSON-LD)**:
+
 - BlogPosting schema with full article metadata
 - Author Person schema (if author present)
 - Organization schema for publisher
 - BreadcrumbList for navigation
 
 **OpenGraph Tags**:
+
 - `og:title`, `og:description`, `og:url`
 - `og:type="article"`
 - Featured image as `og:image` (if available)
 
 **Image Optimization**:
+
 - Images served via Cloudflare CDN
 - Automatic WebP conversion
 - Responsive sizing
@@ -656,11 +729,13 @@ The blog platform uses **semantic versioning** to ensure compatibility:
 **Version Format**: `MAJOR.MINOR.PATCH`
 
 **Compatibility Rules**:
+
 - ✅ **Patch Differences** (1.0.0 ↔ 1.0.3): Always compatible
 - ⚠️ **Minor Differences** (1.0.0 ↔ 1.1.0): Compatible with warnings
 - ❌ **Major Differences** (1.0.0 ↔ 2.0.0): Incompatible, blocks publishing
 
 **Checking Compatibility**:
+
 1. Go to Blog → Edit → Publishing
 2. Click **Test Connection**
 3. View compatibility status in test results
@@ -674,12 +749,14 @@ The blog platform uses **semantic versioning** to ensure compatibility:
 Publishing API is rate-limited to **5 requests per minute per authentication token**.
 
 **Rate Limit Behavior**:
+
 - Each publish/unpublish counts as 1 request
 - Version check counts as 1 request
 - Limit resets every 60 seconds
 - Exceeded limits return HTTP 429 with `Retry-After` header
 
 **If Rate Limited**:
+
 1. Wait for reset (shown in error message)
 2. System automatically retries after delay
 3. Avoid rapid republishing during testing
@@ -687,12 +764,14 @@ Publishing API is rate-limited to **5 requests per minute per authentication tok
 ### Security & Privacy
 
 **Credential Security**:
+
 - All tokens encrypted with AES-256-GCM before storage
 - Tokens never displayed after save (shown as "••••")
 - HTTPS required for all API communication
 - Authentication required on all blog platform endpoints
 
 **Content Privacy**:
+
 - Only accepted articles can be published
 - Draft articles remain private in Bloggy
 - Unpublished articles return 404 on blog
@@ -884,8 +963,8 @@ border-border            /* Border colors */
 ```css
 /* globals.css - Tailwind v4 */
 @theme inline {
-  --color-primary: oklch(0.6 0.2 250);  /* Custom blue */
-  --color-foreground: oklch(0.2 0.02 250);  /* Dark text */
+  --color-primary: oklch(0.6 0.2 250); /* Custom blue */
+  --color-foreground: oklch(0.2 0.02 250); /* Dark text */
   /* ... other theme variables */
 }
 ```
@@ -911,9 +990,9 @@ module.exports = {
       typography: {
         DEFAULT: {
           css: {
-            maxWidth: '80ch',  // Wider content
+            maxWidth: "80ch", // Wider content
             h1: {
-              fontSize: '3rem',  // Larger headings
+              fontSize: "3rem", // Larger headings
             },
             // ... custom prose styles
           },
@@ -1014,7 +1093,9 @@ Dark mode is automatically supported via Tailwind's `dark:` variant:
 // app/layout.tsx
 export default function RootLayout({ children }) {
   return (
-    <html lang="en" className="dark">  {/* Add 'dark' class */}
+    <html lang="en" className="dark">
+      {" "}
+      {/* Add 'dark' class */}
       <body>{children}</body>
     </html>
   );
@@ -1056,8 +1137,8 @@ The blog platform follows these design principles:
 ```css
 /* globals.css */
 @theme inline {
-  --color-primary: oklch(0.6 0.25 140);  /* Green primary */
-  --color-primary-foreground: oklch(1 0 0);  /* White text on primary */
+  --color-primary: oklch(0.6 0.25 140); /* Green primary */
+  --color-primary-foreground: oklch(1 0 0); /* White text on primary */
 }
 ```
 
@@ -1069,7 +1150,9 @@ Result: All blog links, CTAs, and accent colors become green.
 // app/blog/[slug]/page.tsx
 export default function ArticlePage({ params }) {
   return (
-    <div className="container mx-auto max-w-5xl">  {/* Wider than default */}
+    <div className="container mx-auto max-w-5xl">
+      {" "}
+      {/* Wider than default */}
       <BlogArticlePage article={article} />
     </div>
   );
@@ -1085,12 +1168,10 @@ import { AuthorByline as DefaultByline } from "@xexr/blog-platform";
 function CustomAuthorByline({ author }) {
   return (
     <div className="flex items-center gap-4">
-      <img src={author.avatar} className="w-16 h-16 rounded-full" />
+      <img src={author.avatar} className="h-16 w-16 rounded-full" />
       <div>
         <DefaultByline author={author} />
-        <p className="text-sm text-muted-foreground">
-          @{author.twitter}
-        </p>
+        <p className="text-muted-foreground text-sm">@{author.twitter}</p>
       </div>
     </div>
   );

package/dist/app/blog/[slug]/page.d.ts

@@ -0,0 +1,68 @@
+import type { ReactElement } from "react";
+import type { PublishedArticle } from "../../../types/contracts";
+import type { BlogTheme } from "../../../lib/article-ui";
+
+interface ArticlePageProps {
+  article: PublishedArticle;
+  className?: string;
+  navigation?: {
+    backToHome?: {
+      url: string;
+      label?: string;
+    };
+    previousArticle?: {
+      url: string;
+      title: string;
+      featuredImage?: string;
+      featuredImageAlt?: string;
+    };
+    nextArticle?: {
+      url: string;
+      title: string;
+      featuredImage?: string;
+      featuredImageAlt?: string;
+    };
+  };
+  basePath?: string;
+  theme?: BlogTheme;
+  postArticleCta?: {
+    title: string;
+    description?: string;
+    href: string;
+    label: string;
+  };
+  relatedArticles?: PublishedArticle[];
+  showShareLinks?: boolean;
+}
+
+export default function ArticlePage(props: ArticlePageProps): ReactElement;
+
+export function generateArticleMetadata(
+  article: PublishedArticle,
+  basePath?: string,
+): {
+  title: string;
+  description: string;
+  keywords: string;
+  authors: { name: string }[] | undefined;
+  openGraph: {
+    title: string;
+    description: string;
+    type: string;
+    url: string;
+    images: { url: string; alt: string }[] | undefined;
+    publishedTime: string;
+    modifiedTime: string;
+    authors: string[] | undefined;
+    siteName: string;
+  };
+  twitter: {
+    card: string;
+    title: string;
+    description: string;
+    images: string[] | undefined;
+  };
+  alternates: {
+    canonical: string;
+  };
+};