@barodoc/theme-docs 5.0.0 → 6.1.0

package/src/components/mdx/ImageZoom.tsx

@@ -0,0 +1,35 @@
+import * as React from "react";
+import mediumZoom from "medium-zoom";
+import type { Zoom } from "medium-zoom";
+
+interface ImageZoomProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+  zoomSrc?: string;
+}
+
+export function ImageZoom({ zoomSrc, ...props }: ImageZoomProps) {
+  const imgRef = React.useRef<HTMLImageElement>(null);
+  const zoomRef = React.useRef<Zoom | null>(null);
+
+  React.useEffect(() => {
+    if (!imgRef.current) return;
+
+    zoomRef.current = mediumZoom(imgRef.current, {
+      margin: 24,
+      background: "var(--bd-bg)",
+      scrollOffset: 0,
+    });
+
+    return () => {
+      zoomRef.current?.detach();
+    };
+  }, []);
+
+  return (
+    <img
+      ref={imgRef}
+      data-zoom-src={zoomSrc}
+      className="bd-image-zoom"
+      {...props}
+    />
+  );
+}

package/src/components/mdx/Video.tsx

@@ -0,0 +1,71 @@
+import * as React from "react";
+import { cn } from "../../lib/utils.js";
+
+interface VideoProps {
+  url: string;
+  title?: string;
+  caption?: string;
+  className?: string;
+}
+
+function parseVideoUrl(url: string): { provider: string; embedUrl: string } | null {
+  // YouTube: youtube.com/watch?v=ID, youtu.be/ID, youtube.com/embed/ID
+  const ytMatch = url.match(
+    /(?:youtube\.com\/(?:watch\?v=|embed\/)|youtu\.be\/)([a-zA-Z0-9_-]{11})/
+  );
+  if (ytMatch) {
+    return {
+      provider: "youtube",
+      embedUrl: `https://www.youtube-nocookie.com/embed/${ytMatch[1]}?rel=0`,
+    };
+  }
+
+  // Vimeo: vimeo.com/ID, player.vimeo.com/video/ID
+  const vimeoMatch = url.match(/(?:vimeo\.com\/|player\.vimeo\.com\/video\/)(\d+)/);
+  if (vimeoMatch) {
+    return {
+      provider: "vimeo",
+      embedUrl: `https://player.vimeo.com/video/${vimeoMatch[1]}?dnt=1`,
+    };
+  }
+
+  // Loom: loom.com/share/ID, loom.com/embed/ID
+  const loomMatch = url.match(/loom\.com\/(?:share|embed)\/([a-f0-9]+)/);
+  if (loomMatch) {
+    return {
+      provider: "loom",
+      embedUrl: `https://www.loom.com/embed/${loomMatch[1]}`,
+    };
+  }
+
+  return null;
+}
+
+export function Video({ url, title, caption, className }: VideoProps) {
+  const parsed = parseVideoUrl(url);
+
+  if (!parsed) {
+    return (
+      <div className={cn("bd-video", className)} style={{ paddingTop: 0, padding: "2rem" }}>
+        <p style={{ color: "var(--bd-text-muted)", margin: 0, textAlign: "center" }}>
+          Unsupported video URL: {url}
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <figure className={className}>
+      <div className="bd-video">
+        <iframe
+          src={parsed.embedUrl}
+          title={title || `${parsed.provider} video`}
+          allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+          allowFullScreen
+          loading="lazy"
+        />
+      </div>
+      {caption && <figcaption className="bd-video-caption">{caption}</figcaption>}
+    </figure>
+  );
+}

package/src/index.ts

@@ -3,6 +3,8 @@ import type { ThemeExport, ResolvedBarodocConfig } from "@barodoc/core";
 import mdx from "@astrojs/mdx";
 import react from "@astrojs/react";
 import tailwindcss from "@tailwindcss/vite";
+import remarkMath from "remark-math";
+import rehypeKatex from "rehype-katex";
 
 export interface DocsThemeOptions {
   customCss?: string[];
@@ -79,9 +81,33 @@ function createThemeIntegration(
           entrypoint: "@barodoc/theme-docs/pages/docs/[...slug].astro",
         });
 
+        // Blog routes
+        if (config?.blog?.enabled !== false) {
+          injectRoute({
+            pattern: "/blog",
+            entrypoint: "@barodoc/theme-docs/pages/blog/index.astro",
+          });
+          injectRoute({
+            pattern: "/blog/[...slug]",
+            entrypoint: "@barodoc/theme-docs/pages/blog/[...slug].astro",
+          });
+        }
+
+        // Changelog route
+        injectRoute({
+          pattern: "/changelog",
+          entrypoint: "@barodoc/theme-docs/pages/changelog/index.astro",
+        });
+
         // Update Astro config with integrations and Vite plugins
         updateConfig({
-          integrations: [mdx(), react()],
+          integrations: [
+            mdx({
+              remarkPlugins: [remarkMath],
+              rehypePlugins: [rehypeKatex],
+            }),
+            react(),
+          ],
           vite: {
             plugins: [tailwindcss()],
             optimizeDeps: {

package/src/layouts/BaseLayout.astro

@@ -45,6 +45,9 @@ const themeCSS = config.theme?.colors ? generateThemeCSS(config.theme.colors) :
     <meta name="twitter:description" content={description} />
     {ogImageUrl && <meta name="twitter:image" content={ogImageUrl} />}
 
+    <!-- KaTeX math rendering -->
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" crossorigin="anonymous" />
+
     <title>{title}</title>
     <ThemeScript />
     <ClientRouter />

package/src/layouts/BlogLayout.astro

@@ -0,0 +1,93 @@
+---
+import BaseLayout from "./BaseLayout.astro";
+import Header from "../components/Header.astro";
+import Banner from "../components/Banner.astro";
+import { defaultLocale } from "virtual:barodoc/i18n";
+import { getLocaleFromPath } from "@barodoc/core";
+
+interface Props {
+  title: string;
+  description?: string;
+  date?: Date;
+  author?: string;
+  image?: string;
+  tags?: string[];
+  readingTime?: string;
+}
+
+const { title, description, date, author, image, tags = [], readingTime } = Astro.props;
+const currentPath = Astro.url.pathname;
+const i18nConfig = { defaultLocale, locales: [defaultLocale] };
+const currentLocale = getLocaleFromPath(currentPath, i18nConfig);
+---
+
+<BaseLayout title={title} description={description} ogImage={image}>
+  <Banner />
+  <Header currentLocale={currentLocale} currentPath={currentPath} />
+  
+  <div class="w-full min-w-0 min-h-[calc(100vh-3.5rem)] flex justify-center">
+    <article class="w-full max-w-[720px] px-4 py-10 sm:px-6 lg:px-8">
+      <!-- Blog post header -->
+      <header class="mb-10">
+        {tags.length > 0 && (
+          <div class="flex flex-wrap gap-2 mb-4">
+            {tags.map((tag) => (
+              <span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-primary-50 text-primary-700 dark:bg-primary-950 dark:text-primary-300">
+                {tag}
+              </span>
+            ))}
+          </div>
+        )}
+        <h1 class="text-3xl sm:text-4xl font-bold tracking-tight text-[var(--bd-text-heading)] leading-tight">
+          {title}
+        </h1>
+        {description && (
+          <p class="mt-3 text-lg text-[var(--bd-text-secondary)] leading-relaxed">
+            {description}
+          </p>
+        )}
+        <div class="mt-4 flex items-center gap-3 text-sm text-[var(--bd-text-muted)]">
+          {author && <span>{author}</span>}
+          {author && date && <span class="text-[var(--bd-border)]">&middot;</span>}
+          {date && (
+            <time datetime={date.toISOString()}>
+              {date.toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric" })}
+            </time>
+          )}
+          {readingTime && (
+            <>
+              <span class="text-[var(--bd-border)]">&middot;</span>
+              <span>{readingTime}</span>
+            </>
+          )}
+        </div>
+      </header>
+
+      {image && (
+        <img
+          src={image}
+          alt={title}
+          class="w-full rounded-lg mb-10 bd-no-zoom"
+          loading="eager"
+        />
+      )}
+
+      <div class="prose prose-gray dark:prose-invert max-w-none">
+        <slot />
+      </div>
+
+      <!-- Back to blog -->
+      <div class="mt-12 pt-8 border-t border-[var(--bd-border)]">
+        <a
+          href="/blog"
+          class="inline-flex items-center gap-1.5 text-sm text-[var(--bd-text-secondary)] hover:text-primary-600 dark:hover:text-primary-400 transition-colors"
+        >
+          <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 19l-7-7 7-7" />
+          </svg>
+          Back to Blog
+        </a>
+      </div>
+    </article>
+  </div>
+</BaseLayout>

package/src/layouts/DocsLayout.astro

@@ -7,6 +7,8 @@ import MobileNav from "../components/MobileNav.astro";
 import CodeCopy from "../components/CodeCopy.astro";
 import Breadcrumb from "../components/Breadcrumb.astro";
 import Banner from "../components/Banner.astro";
+import KeyboardShortcuts from "../components/KeyboardShortcuts.astro";
+import Contributors from "../components/Contributors.astro";
 import { defaultLocale } from "virtual:barodoc/i18n";
 import { getLocaleFromPath } from "@barodoc/core";
 import config from "virtual:barodoc/config";
@@ -30,9 +32,11 @@ interface Props {
   editUrl?: string | null;
   lastUpdated?: Date | null;
   breadcrumbs?: BreadcrumbItem[];
+  readingTime?: string;
+  filePath?: string;
 }
 
-const { title, description, headings = [], prevPage, nextPage, editUrl, lastUpdated, breadcrumbs = [] } = Astro.props;
+const { title, description, headings = [], prevPage, nextPage, editUrl, lastUpdated, breadcrumbs = [], readingTime, filePath } = Astro.props;
 const currentPath = Astro.url.pathname;
 
 // Get locale from path
@@ -61,6 +65,14 @@ const feedbackEndpoint = config.feedback?.endpoint;
       <main class="flex-1 min-w-0 max-w-[768px]">
         <div class="px-4 py-8 sm:px-6 sm:py-10 lg:px-10 lg:py-10">
           {breadcrumbs.length > 0 && <Breadcrumb items={breadcrumbs} />}
+          {readingTime && (
+            <div class="bd-reading-time mb-4">
+              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                <circle cx="12" cy="12" r="10" /><polyline points="12 6 12 12 16 14" />
+              </svg>
+              <span>{readingTime}</span>
+            </div>
+          )}
           <article class="prose prose-gray dark:prose-invert max-w-none min-w-0 overflow-x-auto">
             <slot />
           </article>
@@ -111,6 +123,7 @@ const feedbackEndpoint = config.feedback?.endpoint;
 
           <!-- Page footer -->
           <footer class="mt-8 pt-6 border-t border-[var(--bd-border-subtle)] flex flex-col gap-3">
+            {filePath && <Contributors filePath={filePath} />}
             <div class="flex flex-wrap items-center justify-between gap-2 text-[13px] text-[var(--bd-text-muted)]">
               {lastUpdated && (
                 <span>
@@ -166,6 +179,25 @@ const feedbackEndpoint = config.feedback?.endpoint;
   <!-- Code copy functionality -->
   <CodeCopy />
 
+  <!-- Keyboard shortcuts -->
+  <KeyboardShortcuts />
+
+  <!-- Image zoom for all prose images -->
+  <script>
+    async function initImageZoom() {
+      const images = document.querySelectorAll('.prose img:not(.bd-no-zoom):not(.medium-zoom-image)');
+      if (images.length === 0) return;
+      const { default: mediumZoom } = await import('medium-zoom');
+      mediumZoom(images as any, {
+        margin: 24,
+        background: 'var(--bd-bg)',
+        scrollOffset: 0,
+      });
+    }
+    initImageZoom();
+    document.addEventListener('astro:page-load', initImageZoom);
+  </script>
+
   <!-- Heading anchor links -->
   <script>
     function initHeadingAnchors() {

package/src/pages/blog/[...slug].astro

@@ -0,0 +1,39 @@
+---
+import { getCollection } from "astro:content";
+import BlogLayout from "../../layouts/BlogLayout.astro";
+import readingTime from "reading-time";
+
+export async function getStaticPaths() {
+  let posts: Awaited<ReturnType<typeof getCollection<"blog">>> = [];
+  try {
+    posts = await getCollection("blog");
+  } catch {
+    return [];
+  }
+
+  return posts.map((post) => ({
+    params: { slug: post.slug },
+    props: { post },
+  }));
+}
+
+interface Props {
+  post: Awaited<ReturnType<typeof getCollection<"blog">>>[number];
+}
+
+const { post } = Astro.props;
+const { Content } = await post.render();
+const readTime = readingTime(post.body ?? "");
+---
+
+<BlogLayout
+  title={post.data.title}
+  description={post.data.description || post.data.excerpt}
+  date={post.data.date ? new Date(post.data.date) : undefined}
+  author={post.data.author}
+  image={post.data.image}
+  tags={post.data.tags}
+  readingTime={readTime.text}
+>
+  <Content />
+</BlogLayout>

package/src/pages/blog/index.astro

@@ -0,0 +1,92 @@
+---
+import { getCollection } from "astro:content";
+import BaseLayout from "../../layouts/BaseLayout.astro";
+import Header from "../../components/Header.astro";
+import Banner from "../../components/Banner.astro";
+import { defaultLocale } from "virtual:barodoc/i18n";
+import { getLocaleFromPath } from "@barodoc/core";
+import config from "virtual:barodoc/config";
+
+const currentPath = Astro.url.pathname;
+const i18nConfig = { defaultLocale, locales: [defaultLocale] };
+const currentLocale = getLocaleFromPath(currentPath, i18nConfig);
+
+let posts: Awaited<ReturnType<typeof getCollection<"blog">>> = [];
+try {
+  posts = await getCollection("blog");
+} catch {
+  // blog collection may not exist
+}
+
+const sortedPosts = posts.sort((a, b) => {
+  const dateA = a.data.date ? new Date(a.data.date).getTime() : 0;
+  const dateB = b.data.date ? new Date(b.data.date).getTime() : 0;
+  return dateB - dateA;
+});
+---
+
+<BaseLayout title={`Blog - ${config.name}`} description="Latest blog posts and updates">
+  <Banner />
+  <Header currentLocale={currentLocale} currentPath={currentPath} />
+  
+  <div class="w-full min-w-0 min-h-[calc(100vh-3.5rem)] flex justify-center">
+    <div class="w-full max-w-[960px] px-4 py-10 sm:px-6 lg:px-8">
+      <header class="mb-10">
+        <h1 class="text-3xl font-bold tracking-tight text-[var(--bd-text-heading)]">Blog</h1>
+        <p class="mt-2 text-[var(--bd-text-secondary)]">Latest posts and updates</p>
+      </header>
+
+      {sortedPosts.length === 0 ? (
+        <p class="text-[var(--bd-text-muted)]">No posts yet.</p>
+      ) : (
+        <div class="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+          {sortedPosts.map((post) => (
+            <a
+              href={`/blog/${post.slug}`}
+              class="group flex flex-col rounded-lg border border-[var(--bd-border)] hover:border-primary-400/50 dark:hover:border-primary-500/40 hover:shadow-[var(--bd-shadow-sm)] transition-all overflow-hidden"
+            >
+              {post.data.image && (
+                <div class="aspect-[16/9] overflow-hidden bg-[var(--bd-bg-subtle)]">
+                  <img
+                    src={post.data.image}
+                    alt={post.data.title}
+                    class="w-full h-full object-cover group-hover:scale-105 transition-transform duration-300"
+                    loading="lazy"
+                  />
+                </div>
+              )}
+              <div class="flex flex-col gap-2 p-5">
+                {post.data.tags && post.data.tags.length > 0 && (
+                  <div class="flex flex-wrap gap-1.5">
+                    {post.data.tags.slice(0, 3).map((tag: string) => (
+                      <span class="text-[11px] font-medium px-2 py-0.5 rounded-full bg-primary-50 text-primary-700 dark:bg-primary-950 dark:text-primary-300">
+                        {tag}
+                      </span>
+                    ))}
+                  </div>
+                )}
+                <h2 class="text-base font-semibold text-[var(--bd-text)] group-hover:text-primary-600 dark:group-hover:text-primary-400 transition-colors leading-snug">
+                  {post.data.title}
+                </h2>
+                {post.data.excerpt && (
+                  <p class="text-sm text-[var(--bd-text-muted)] line-clamp-2">
+                    {post.data.excerpt}
+                  </p>
+                )}
+                <div class="mt-auto pt-2 flex items-center gap-2 text-xs text-[var(--bd-text-muted)]">
+                  {post.data.author && <span>{post.data.author}</span>}
+                  {post.data.author && post.data.date && <span>&middot;</span>}
+                  {post.data.date && (
+                    <time datetime={new Date(post.data.date).toISOString()}>
+                      {new Date(post.data.date).toLocaleDateString("en-US", { year: "numeric", month: "short", day: "numeric" })}
+                    </time>
+                  )}
+                </div>
+              </div>
+            </a>
+          ))}
+        </div>
+      )}
+    </div>
+  </div>
+</BaseLayout>

package/src/pages/changelog/index.astro

@@ -0,0 +1,72 @@
+---
+import { getCollection } from "astro:content";
+import BaseLayout from "../../layouts/BaseLayout.astro";
+import Header from "../../components/Header.astro";
+import Banner from "../../components/Banner.astro";
+import { defaultLocale } from "virtual:barodoc/i18n";
+import { getLocaleFromPath } from "@barodoc/core";
+import config from "virtual:barodoc/config";
+
+const currentPath = Astro.url.pathname;
+const i18nConfig = { defaultLocale, locales: [defaultLocale] };
+const currentLocale = getLocaleFromPath(currentPath, i18nConfig);
+
+let entries: Awaited<ReturnType<typeof getCollection<"changelog">>> = [];
+try {
+  entries = await getCollection("changelog");
+} catch {
+  // changelog collection may not exist
+}
+
+const sorted = entries.sort((a, b) => {
+  return new Date(b.data.date).getTime() - new Date(a.data.date).getTime();
+});
+---
+
+<BaseLayout title={`Changelog - ${config.name}`} description="Release history and changelog">
+  <Banner />
+  <Header currentLocale={currentLocale} currentPath={currentPath} />
+
+  <div class="w-full min-w-0 min-h-[calc(100vh-3.5rem)] flex justify-center">
+    <div class="w-full max-w-[720px] px-4 py-10 sm:px-6 lg:px-8">
+      <header class="mb-10">
+        <h1 class="text-3xl font-bold tracking-tight text-[var(--bd-text-heading)]">Changelog</h1>
+        <p class="mt-2 text-[var(--bd-text-secondary)]">Release history and notable changes</p>
+      </header>
+
+      {sorted.length === 0 ? (
+        <p class="text-[var(--bd-text-muted)]">No changelog entries yet.</p>
+      ) : (
+        <div class="bd-changelog-timeline">
+          {sorted.map(async (entry) => {
+            const { Content } = await entry.render();
+            return (
+              <article class="bd-changelog-entry">
+                <div class="bd-changelog-marker">
+                  <div class="bd-changelog-dot" />
+                  <div class="bd-changelog-line" />
+                </div>
+                <div class="bd-changelog-content">
+                  <div class="bd-changelog-header">
+                    <span class="bd-changelog-version">{entry.data.version}</span>
+                    <time class="bd-changelog-date" datetime={new Date(entry.data.date).toISOString()}>
+                      {new Date(entry.data.date).toLocaleDateString("en-US", {
+                        year: "numeric", month: "long", day: "numeric",
+                      })}
+                    </time>
+                  </div>
+                  {entry.data.title && (
+                    <h2 class="bd-changelog-title">{entry.data.title}</h2>
+                  )}
+                  <div class="prose prose-sm prose-gray dark:prose-invert max-w-none bd-changelog-body">
+                    <Content />
+                  </div>
+                </div>
+              </article>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  </div>
+</BaseLayout>

package/src/pages/docs/[...slug].astro

@@ -4,6 +4,7 @@ import DocsLayout from "../../layouts/DocsLayout.astro";
 import config from "virtual:barodoc/config";
 import { defaultLocale, locales } from "virtual:barodoc/i18n";
 import { getLocalizedNavGroup } from "@barodoc/core";
+import readingTime from "reading-time";
 
 export async function getStaticPaths() {
   const docs = await getCollection("docs");
@@ -41,6 +42,7 @@ interface Props {
 
 const { doc, locale, cleanSlug } = Astro.props;
 const { Content, headings } = await doc.render();
+const readTime = readingTime(doc.body ?? "");
 
 // Find the category (navigation group) for this page
 function findCategory(slug: string): string | null {
@@ -122,6 +124,8 @@ breadcrumbs.push({ label: doc.data.title });
   editUrl={editUrl}
   lastUpdated={lastUpdated}
   breadcrumbs={breadcrumbs}
+  readingTime={readTime.text}
+  filePath={doc.id}
 >
   {category && (
     <p class="text-xs font-semibold uppercase tracking-widest text-primary-600 dark:text-primary-400 mb-3">