@hutusi/amytis 1.15.0 → 1.17.0

package/src/components/CodeBlock.tsx

@@ -1,114 +1,52 @@
-"use client";
-
-import React, { useState } from 'react';
-import { PrismLight as SyntaxHighlighter } from 'react-syntax-highlighter';
-import tsx from 'react-syntax-highlighter/dist/esm/languages/prism/tsx';
-import typescript from 'react-syntax-highlighter/dist/esm/languages/prism/typescript';
-import javascript from 'react-syntax-highlighter/dist/esm/languages/prism/javascript';
-import bash from 'react-syntax-highlighter/dist/esm/languages/prism/bash';
-import markdown from 'react-syntax-highlighter/dist/esm/languages/prism/markdown';
-import json from 'react-syntax-highlighter/dist/esm/languages/prism/json';
-import css from 'react-syntax-highlighter/dist/esm/languages/prism/css';
-import python from 'react-syntax-highlighter/dist/esm/languages/prism/python';
-import rust from 'react-syntax-highlighter/dist/esm/languages/prism/rust';
-import go from 'react-syntax-highlighter/dist/esm/languages/prism/go';
-import c from 'react-syntax-highlighter/dist/esm/languages/prism/c';
-import cpp from 'react-syntax-highlighter/dist/esm/languages/prism/cpp';
-import java from 'react-syntax-highlighter/dist/esm/languages/prism/java';
-import ruby from 'react-syntax-highlighter/dist/esm/languages/prism/ruby';
-import sql from 'react-syntax-highlighter/dist/esm/languages/prism/sql';
-import yaml from 'react-syntax-highlighter/dist/esm/languages/prism/yaml';
-import diff from 'react-syntax-highlighter/dist/esm/languages/prism/diff';
-import markup from 'react-syntax-highlighter/dist/esm/languages/prism/markup';
-
-SyntaxHighlighter.registerLanguage('tsx', tsx);
-SyntaxHighlighter.registerLanguage('typescript', typescript);
-SyntaxHighlighter.registerLanguage('javascript', javascript);
-SyntaxHighlighter.registerLanguage('js', javascript);
-SyntaxHighlighter.registerLanguage('bash', bash);
-SyntaxHighlighter.registerLanguage('sh', bash);
-SyntaxHighlighter.registerLanguage('shell', bash);
-SyntaxHighlighter.registerLanguage('markdown', markdown);
-SyntaxHighlighter.registerLanguage('md', markdown);
-SyntaxHighlighter.registerLanguage('json', json);
-SyntaxHighlighter.registerLanguage('css', css);
-SyntaxHighlighter.registerLanguage('python', python);
-SyntaxHighlighter.registerLanguage('py', python);
-SyntaxHighlighter.registerLanguage('rust', rust);
-SyntaxHighlighter.registerLanguage('go', go);
-SyntaxHighlighter.registerLanguage('golang', go);
-SyntaxHighlighter.registerLanguage('c', c);
-SyntaxHighlighter.registerLanguage('cpp', cpp);
-SyntaxHighlighter.registerLanguage('c++', cpp);
-SyntaxHighlighter.registerLanguage('java', java);
-SyntaxHighlighter.registerLanguage('ruby', ruby);
-SyntaxHighlighter.registerLanguage('rb', ruby);
-SyntaxHighlighter.registerLanguage('sql', sql);
-SyntaxHighlighter.registerLanguage('yaml', yaml);
-SyntaxHighlighter.registerLanguage('yml', yaml);
-SyntaxHighlighter.registerLanguage('diff', diff);
-SyntaxHighlighter.registerLanguage('html', markup);
-SyntaxHighlighter.registerLanguage('xml', markup);
-SyntaxHighlighter.registerLanguage('svg', markup);
+import { toHtml } from 'hast-util-to-html';
+import CodeBlockToolbar from './CodeBlockToolbar';
+import { getLanguageDisplayName, highlightToHast } from '@/lib/shiki';
 
 interface CodeBlockProps {
   language: string;
   children: string;
-  [key: string]: unknown;
+  title?: string;
+  showLineNumbers?: boolean;
+  highlightLines?: number[];
 }
 
-export default function CodeBlock({ language, children, ...props }: CodeBlockProps) {
-  const [copied, setCopied] = useState(false);
-
-  const handleCopy = async () => {
-    await navigator.clipboard.writeText(children);
-    setCopied(true);
-    setTimeout(() => setCopied(false), 2000);
-  };
+export default async function CodeBlock({
+  language,
+  children,
+  title,
+  showLineNumbers,
+  highlightLines,
+}: CodeBlockProps) {
+  const hast = await highlightToHast(children, language, {
+    showLineNumbers,
+    highlightLines,
+    title,
+  });
+  const html = toHtml(hast);
+  const displayLang = getLanguageDisplayName(language || 'text');
 
   return (
-    <div className="relative my-6 w-full min-w-0 max-w-full rounded-lg border border-muted/20 bg-background/50 overflow-hidden shadow-sm">
-      <div className="flex items-center justify-between px-4 py-2 border-b border-muted/10 bg-muted/5">
-        <span className="text-xs font-mono text-muted uppercase tracking-wider">
-          {language || 'text'}
-        </span>
-        <button
-          onClick={handleCopy}
-          className="text-xs text-muted hover:text-accent transition-colors duration-200 flex items-center gap-1"
-          aria-label="Copy code"
-        >
-          {copied ? (
-            <>
-              <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg>
-              <span>Copied</span>
-            </>
-          ) : (
-            <>
-              <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg>
-              <span>Copy</span>
-            </>
+    <div
+      data-cb-root=""
+      className="cb-root relative my-6 w-full min-w-0 max-w-full rounded-lg border border-muted/20 bg-background/50 overflow-hidden shadow-sm"
+    >
+      <div className="cb-header flex items-center justify-between px-4 py-2 border-b border-muted/10 bg-muted/5 gap-3">
+        <div className="flex items-center gap-3 min-w-0">
+          <span className="cb-lang text-xs font-mono text-muted tracking-wider">
+            {displayLang}
+          </span>
+          {title && (
+            <span className="cb-title truncate text-xs text-foreground/80" title={title}>
+              {title}
+            </span>
           )}
-        </button>
-      </div>
-      <div className="w-full min-w-0 max-w-full overflow-x-auto overflow-y-hidden">
-        <SyntaxHighlighter
-          language={language || 'text'}
-          PreTag="div"
-          useInlineStyles={false}
-          customStyle={{
-            margin: 0,
-            padding: '1.5rem',
-            background: 'transparent',
-            fontSize: '0.9rem',
-            lineHeight: '1.6',
-            maxWidth: '100%',
-            boxSizing: 'border-box',
-          }}
-          {...props}
-        >
-          {children}
-        </SyntaxHighlighter>
+        </div>
+        <CodeBlockToolbar code={children} />
       </div>
+      <div
+        className="cb-scroll w-full min-w-0 max-w-full overflow-x-auto overflow-y-hidden"
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
     </div>
   );
 }

package/src/components/CodeBlockToolbar.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+import { useRef, useState } from 'react';
+
+interface CodeBlockToolbarProps {
+  code: string;
+}
+
+export default function CodeBlockToolbar({ code }: CodeBlockToolbarProps) {
+  const [copied, setCopied] = useState(false);
+  const [wrapped, setWrapped] = useState(false);
+  const buttonRef = useRef<HTMLButtonElement | null>(null);
+
+  const handleCopy = async () => {
+    try {
+      await navigator.clipboard.writeText(code);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // Clipboard may be unavailable (e.g. insecure context); fail silently.
+    }
+  };
+
+  const handleToggleWrap = () => {
+    const next = !wrapped;
+    setWrapped(next);
+    const root = buttonRef.current?.closest('[data-cb-root]') as HTMLElement | null;
+    if (root) {
+      if (next) {
+        root.setAttribute('data-wrap', 'true');
+      } else {
+        root.removeAttribute('data-wrap');
+      }
+    }
+  };
+
+  return (
+    <div className="flex items-center gap-3">
+      <button
+        ref={buttonRef}
+        onClick={handleToggleWrap}
+        className="text-xs text-muted hover:text-accent transition-colors duration-200 flex items-center gap-1"
+        aria-label={wrapped ? 'Disable word wrap' : 'Enable word wrap'}
+        aria-pressed={wrapped}
+        type="button"
+      >
+        {wrapped ? (
+          <>
+            <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+              <path d="M3 6h18" />
+              <path d="M3 12h15a3 3 0 0 1 0 6h-4" />
+              <path d="m16 16-2 2 2 2" />
+              <path d="M3 18h7" />
+            </svg>
+            <span>Wrap</span>
+          </>
+        ) : (
+          <>
+            <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+              <path d="M3 6h18" />
+              <path d="M3 12h18" />
+              <path d="M3 18h18" />
+            </svg>
+            <span>No wrap</span>
+          </>
+        )}
+      </button>
+      <button
+        onClick={handleCopy}
+        className="text-xs text-muted hover:text-accent transition-colors duration-200 flex items-center gap-1"
+        aria-label="Copy code"
+        type="button"
+      >
+        {copied ? (
+          <>
+            <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"><polyline points="20 6 9 17 4 12" /></svg>
+            <span>Copied</span>
+          </>
+        ) : (
+          <>
+            <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"><rect x="9" y="9" width="13" height="13" rx="2" ry="2" /><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" /></svg>
+            <span>Copy</span>
+          </>
+        )}
+      </button>
+    </div>
+  );
+}

package/src/components/CodeGroup.tsx

@@ -0,0 +1,81 @@
+import { Children, type ReactNode } from 'react';
+import { resolveCodeGroupIcon } from '@/lib/code-group-icons';
+
+interface CodeGroupProps {
+  'data-labels'?: string;
+  'data-group-id'?: string;
+  children?: ReactNode;
+}
+
+/**
+ * Tabbed code group widget. CSS-only — the radio + label sibling trick handles
+ * tab switching with zero JavaScript. The matching CSS in globals.css picks the
+ * checked input's matching panel via attribute selectors (input[data-idx=N] →
+ * .cg-panel[data-panel=N]).
+ *
+ * Children are already-highlighted CodeBlock server components from the
+ * outer MarkdownRenderer pipeline; this component just composes the tab UI
+ * around them.
+ */
+export default function CodeGroup(props: CodeGroupProps) {
+  const labelsRaw = props['data-labels'] ?? '[]';
+  const groupId = props['data-group-id'] ?? 'cg-default';
+  let labels: string[];
+  try {
+    const parsed = JSON.parse(labelsRaw);
+    labels = Array.isArray(parsed) ? parsed.map(String) : [];
+  } catch {
+    labels = [];
+  }
+
+  // Drop whitespace text nodes that remark-rehype leaves between code children.
+  const panels = Children.toArray(props.children).filter((child) => {
+    if (typeof child === 'string') return child.trim().length > 0;
+    return true;
+  });
+  const tabs = labels.length > 0 ? labels : panels.map((_, i) => `Tab ${i + 1}`);
+
+  return (
+    <div className="code-group my-6" data-group-id={groupId}>
+      {tabs.map((_, i) => (
+        <input
+          key={`r-${i}`}
+          type="radio"
+          name={`cg-${groupId}`}
+          id={`cg-${groupId}-${i}`}
+          data-idx={String(i)}
+          defaultChecked={i === 0}
+          aria-controls={`cg-${groupId}-panel-${i}`}
+          tabIndex={i === 0 ? 0 : -1}
+        />
+      ))}
+      <div className="cg-tablist" role="tablist">
+        {tabs.map((label, i) => {
+          const icon = resolveCodeGroupIcon(label);
+          return (
+            <label
+              key={`l-${i}`}
+              htmlFor={`cg-${groupId}-${i}`}
+              className="cg-tab"
+              role="tab"
+              {...(icon ? { 'data-cg-icon': icon } : {})}
+            >
+              {label}
+            </label>
+          );
+        })}
+      </div>
+      {panels.map((child, i) => (
+        <div
+          key={`p-${i}`}
+          className="cg-panel"
+          data-panel={String(i)}
+          role="tabpanel"
+          id={`cg-${groupId}-panel-${i}`}
+        >
+          {child}
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/CoverImage.tsx

@@ -101,6 +101,7 @@ export default function CoverImage({ title, slug, src, className = "h-full w-ful
       unoptimized={!useBlurPlaceholder}
       placeholder={useBlurPlaceholder ? 'blur' : 'empty'}
       loading={loading}
+      fetchPriority={loading === 'eager' ? 'high' : 'low'}
     />
   );
 }

package/src/components/CuratedSeriesSection.tsx

@@ -1,11 +1,12 @@
 'use client';
 
-import { useState, useCallback } from 'react';
+import { useState, useEffect, useCallback } from 'react';
 import Link from 'next/link';
 import HorizontalScroll from './HorizontalScroll';
 import CoverImage from './CoverImage';
 import { useLanguage } from './LanguageProvider';
-import { shuffle, shuffleSeeded } from '@/lib/shuffle';
+import { shuffle } from '@/lib/shuffle';
+import { byDateAsc, byDateDesc } from '@/lib/sort';
 import { getPostUrl, getSeriesListUrl } from '@/lib/urls';
 
 export interface SeriesItem {
@@ -16,21 +17,38 @@ export interface SeriesItem {
   url: string;
   postCount: number;
   topPosts: { slug: string; title: string }[];
+  date: string;
 }
 
+type SeriesOrder = 'shuffle' | 'date-desc' | 'date-asc';
+
 interface CuratedSeriesSectionProps {
   allSeries: SeriesItem[];
   maxItems: number;
+  order?: SeriesOrder;
+}
+
+function canonicalOrder(series: SeriesItem[], order: SeriesOrder): SeriesItem[] {
+  if (order === 'date-desc') return [...series].sort(byDateDesc);
+  if (order === 'date-asc')  return [...series].sort(byDateAsc);
+  return series;
 }
 
-export default function CuratedSeriesSection({ allSeries, maxItems }: CuratedSeriesSectionProps) {
+export default function CuratedSeriesSection({ allSeries, maxItems, order = 'shuffle' }: CuratedSeriesSectionProps) {
   const { t } = useLanguage();
-  // Use a daily seed so SSR and client hydration agree on the initial order,
-  // preventing a visible reshuffle flash on page load.
-  const [displayed, setDisplayed] = useState(() => {
-    const dailySeed = Math.floor(Date.now() / 86400000);
-    return shuffleSeeded(allSeries, dailySeed).slice(0, maxItems);
-  });
+  // SSR renders the canonical input order so server and client agree on first paint.
+  // For 'shuffle', the post-mount useEffect swaps to a fresh random permutation,
+  // so every reload re-rolls without any hydration mismatch.
+  const [displayed, setDisplayed] = useState(() => canonicalOrder(allSeries, order).slice(0, maxItems));
+
+  // Shuffle on mount so every reload re-rolls. SSR's canonical render is stable; the
+  // post-hydration swap is the intentional client-only behaviour, not a sync issue.
+  useEffect(() => {
+    if (order === 'shuffle') {
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setDisplayed(shuffle(allSeries).slice(0, maxItems));
+    }
+  }, [allSeries, maxItems, order]);
 
   const handleShuffle = useCallback(() => {
     setDisplayed(shuffle(allSeries).slice(0, maxItems));
@@ -43,7 +61,7 @@ export default function CuratedSeriesSection({ allSeries, maxItems }: CuratedSer
       <div className="flex items-center justify-between mb-8">
         <h2 className="text-2xl sm:text-3xl font-serif font-bold text-heading">{t('curated_series')}</h2>
         <div className="flex items-center gap-4">
-          {allSeries.length > maxItems && (
+          {order === 'shuffle' && allSeries.length > maxItems && (
             <button
               onClick={handleShuffle}
               className="rounded-sm text-sm text-muted transition-colors hover:text-accent focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/50 focus-visible:ring-offset-2"

package/src/components/ExternalLinkIcon.tsx

@@ -0,0 +1,15 @@
+import { LuArrowUpRight } from 'react-icons/lu';
+
+/**
+ * Inline outward-arrow indicator appended after external-link text by
+ * `MarkdownRenderer`'s `<a>` override. Sized relative to the surrounding
+ * text and aria-hidden — the link's accessible name already carries intent.
+ */
+export default function ExternalLinkIcon() {
+  return (
+    <LuArrowUpRight
+      aria-hidden="true"
+      className="inline-block align-text-top ml-0.5 text-[0.85em] opacity-70"
+    />
+  );
+}

package/src/components/FeaturedStoriesSection.tsx

@@ -1,10 +1,11 @@
 'use client';
 
-import { useState, useCallback } from 'react';
+import { useState, useEffect, useCallback } from 'react';
 import Link from 'next/link';
 import CoverImage from './CoverImage';
 import { useLanguage } from './LanguageProvider';
-import { shuffle, shuffleSeeded } from '@/lib/shuffle';
+import { shuffle } from '@/lib/shuffle';
+import { byDateAsc, byDateDesc } from '@/lib/sort';
 import { getPostUrl } from '@/lib/urls';
 
 export interface FeaturedPost {
@@ -14,62 +15,82 @@ export interface FeaturedPost {
   excerpt: string;
   date: string;
   category: string;
-  readingTime: string;
+  readingMinutes: number;
   coverImage?: string;
   series?: string;
   pinned?: boolean;
 }
 
+type PostOrder = 'shuffle' | 'date-desc' | 'date-asc';
+
 interface FeaturedStoriesSectionProps {
   allFeatured: FeaturedPost[];
   maxItems: number;
+  order?: PostOrder;
+}
+
+function canonicalOrder(posts: FeaturedPost[], order: PostOrder): FeaturedPost[] {
+  if (order === 'date-desc') return [...posts].sort(byDateDesc);
+  if (order === 'date-asc')  return [...posts].sort(byDateAsc);
+  return posts;
 }
 
-function buildDisplayed(allFeatured: FeaturedPost[], maxItems: number, shuffledNonPinned: FeaturedPost[]): FeaturedPost[] {
+function buildDisplayed(allFeatured: FeaturedPost[], maxItems: number, orderedNonPinned: FeaturedPost[]): FeaturedPost[] {
   const pinned = allFeatured.filter(p => p.pinned);
-  const nonPinned = allFeatured.filter(p => !p.pinned);
 
-  const hero = pinned[0] ?? nonPinned[0];
+  const hero = pinned[0] ?? orderedNonPinned[0];
   if (!hero) return [];
 
   const maxSecondaries = maxItems - 1;
   const fixedSecondaries = pinned.slice(1, maxSecondaries + 1); // cap to available secondary slots
-  const shuffleSlots = Math.max(0, maxSecondaries - fixedSecondaries.length);
+  const fillSlots = Math.max(0, maxSecondaries - fixedSecondaries.length);
 
   // Non-pinned pool excludes the hero if the hero is non-pinned
   const heroIsNonPinned = !hero.pinned;
-  const shufflePool = heroIsNonPinned ? nonPinned.filter(p => p.slug !== hero.slug) : nonPinned;
-  const shuffledSlice = shuffledNonPinned.filter(p => shufflePool.some(q => q.slug === p.slug)).slice(0, shuffleSlots);
+  const fillPool = heroIsNonPinned ? orderedNonPinned.filter(p => p.slug !== hero.slug) : orderedNonPinned;
+  const fillSlice = fillPool.slice(0, fillSlots);
 
-  return [hero, ...fixedSecondaries, ...shuffledSlice];
+  return [hero, ...fixedSecondaries, ...fillSlice];
 }
 
-export default function FeaturedStoriesSection({ allFeatured, maxItems }: FeaturedStoriesSectionProps) {
+export default function FeaturedStoriesSection({ allFeatured, maxItems, order = 'shuffle' }: FeaturedStoriesSectionProps) {
   const { t } = useLanguage();
 
   const nonPinned = allFeatured.filter(p => !p.pinned);
 
-  // Use a daily seed so SSR and client hydration agree on the initial order,
-  // preventing a visible reshuffle flash on page load.
-  const [shuffledNonPinned, setShuffledNonPinned] = useState<FeaturedPost[]>(() => {
-    const dailySeed = Math.floor(Date.now() / 86400000);
-    return shuffleSeeded(nonPinned, dailySeed);
-  });
+  // SSR renders the canonical input order so server and client agree on first paint.
+  // For 'shuffle', the post-mount useEffect swaps to a fresh random permutation,
+  // so every reload re-rolls without any hydration mismatch.
+  const [orderedNonPinned, setOrderedNonPinned] = useState<FeaturedPost[]>(() => canonicalOrder(nonPinned, order));
+
+  // Shuffle on mount so every reload re-rolls. SSR's canonical render is stable; the
+  // post-hydration swap is the intentional client-only behaviour, not a sync issue.
+  useEffect(() => {
+    if (order === 'shuffle') {
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setOrderedNonPinned(shuffle(nonPinned));
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [allFeatured, order]);
 
   const handleShuffle = useCallback(() => {
-    setShuffledNonPinned(shuffle(nonPinned));
+    setOrderedNonPinned(shuffle(nonPinned));
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [allFeatured]);
 
-  const displayed = buildDisplayed(allFeatured, maxItems, shuffledNonPinned);
+  const displayed = buildDisplayed(allFeatured, maxItems, orderedNonPinned);
 
   if (displayed.length === 0) return null;
 
-  // Show shuffle button only when there are more non-pinned posts than available shuffle slots
+  // Show shuffle button only when shuffling AND there's at least one non-pinned slot
+  // AND there are more non-pinned posts than available slots
   const pinned = allFeatured.filter(p => p.pinned);
   const fixedCount = 1 + Math.min(pinned.slice(1).length, maxItems - 1);
   const shuffleSlots = Math.max(0, maxItems - fixedCount);
-  const canShuffle = nonPinned.length > shuffleSlots + (pinned.length === 0 ? 1 : 0);
+  const canShuffle =
+    order === 'shuffle'
+    && shuffleSlots > 0
+    && nonPinned.length > shuffleSlots + (pinned.length === 0 ? 1 : 0);
 
   const [hero, ...secondary] = displayed;
 
@@ -110,7 +131,7 @@ export default function FeaturedStoriesSection({ allFeatured, maxItems }: Featur
                 <div className="flex items-center gap-2 text-xs font-mono text-white/60 mb-3 overflow-hidden">
                   <span className="text-accent uppercase tracking-wider truncate min-w-0">{hero.category}</span>
                   <span className="shrink-0">·</span>
-                  <span className="shrink-0 whitespace-nowrap">{hero.readingTime}</span>
+                  <span className="shrink-0 whitespace-nowrap">{hero.readingMinutes} {t('reading_time')}</span>
                   <span className="shrink-0">·</span>
                   <span className="shrink-0 whitespace-nowrap">{hero.date}</span>
                 </div>
@@ -141,7 +162,7 @@ export default function FeaturedStoriesSection({ allFeatured, maxItems }: Featur
                   <div className="flex items-center gap-2 text-xs font-mono text-muted mb-2">
                     <span className="text-accent uppercase tracking-wider truncate max-w-[4rem]">{post.category}</span>
                     <span className="shrink-0 hidden sm:inline">·</span>
-                    <span className="shrink-0 hidden sm:inline">{post.readingTime}</span>
+                    <span className="shrink-0 hidden sm:inline">{post.readingMinutes} {t('reading_time')}</span>
                     <span className="shrink-0">·</span>
                     <span className="shrink-0">{post.date}</span>
                   </div>

package/src/components/Footer.tsx

@@ -11,7 +11,7 @@ export default function Footer() {
   const { t, language } = useLanguage();
   
   return (
-    <footer className="bg-muted/5 border-t border-muted/10 mt-auto select-none">
+    <footer data-site-footer className="bg-muted/5 border-t border-muted/10 mt-auto select-none">
       <div className="max-w-6xl mx-auto px-6 py-10 lg:py-16">
         <div className="grid grid-cols-2 lg:grid-cols-4 gap-8 lg:gap-12 mb-10 lg:mb-12">
           {/* Brand */}

package/src/components/GithubAlert.tsx

@@ -0,0 +1,97 @@
+import type { ReactNode } from 'react';
+
+type AlertType = 'note' | 'tip' | 'important' | 'warning' | 'caution';
+
+const KNOWN_TYPES: ReadonlySet<AlertType> = new Set(['note', 'tip', 'important', 'warning', 'caution']);
+
+const ALERT_LABELS: Record<AlertType, string> = {
+  note: 'Note',
+  tip: 'Tip',
+  important: 'Important',
+  warning: 'Warning',
+  caution: 'Caution',
+};
+
+interface GithubAlertProps {
+  'data-alert-type'?: string;
+  /** Custom title from the directive label (e.g. `:::tip 智慧的疆界`). Falls back to ALERT_LABELS when absent. */
+  'data-alert-title'?: string;
+  children?: ReactNode;
+}
+
+function AlertIcon({ type }: { type: AlertType }) {
+  const common = {
+    width: 16,
+    height: 16,
+    viewBox: '0 0 24 24',
+    fill: 'none',
+    stroke: 'currentColor',
+    strokeWidth: 2,
+    strokeLinecap: 'round' as const,
+    strokeLinejoin: 'round' as const,
+    'aria-hidden': true,
+  };
+  switch (type) {
+    case 'note':
+      return (
+        <svg {...common}>
+          <circle cx="12" cy="12" r="10" />
+          <path d="M12 16v-4" />
+          <path d="M12 8h.01" />
+        </svg>
+      );
+    case 'tip':
+      return (
+        <svg {...common}>
+          <path d="M15 14c.2-1 .7-1.7 1.5-2.5 1-.9 1.5-2.2 1.5-3.5A6 6 0 0 0 6 8c0 1 .2 2.2 1.5 3.5.7.7 1.3 1.5 1.5 2.5" />
+          <path d="M9 18h6" />
+          <path d="M10 22h4" />
+        </svg>
+      );
+    case 'important':
+      return (
+        <svg {...common}>
+          <path d="M21 11a8 8 0 1 1-16 0 8 8 0 0 1 16 0Z" />
+          <path d="M12 8v4" />
+          <path d="M12 16h.01" />
+        </svg>
+      );
+    case 'warning':
+      return (
+        <svg {...common}>
+          <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z" />
+          <path d="M12 9v4" />
+          <path d="M12 17h.01" />
+        </svg>
+      );
+    case 'caution':
+      return (
+        <svg {...common}>
+          <polygon points="7.86 2 16.14 2 22 7.86 22 16.14 16.14 22 7.86 22 2 16.14 2 7.86 7.86 2" />
+          <path d="M12 8v4" />
+          <path d="M12 16h.01" />
+        </svg>
+      );
+  }
+}
+
+export default function GithubAlert(props: GithubAlertProps) {
+  const raw = (props['data-alert-type'] ?? '').toLowerCase();
+  if (!KNOWN_TYPES.has(raw as AlertType)) {
+    // Defensive: an unrecognized type means the plugin matched but we're missing
+    // a mapping. Fall through to a plain blockquote so content still renders.
+    return <blockquote>{props.children}</blockquote>;
+  }
+  const type = raw as AlertType;
+  const customTitle = props['data-alert-title']?.trim();
+  const title = customTitle && customTitle.length > 0 ? customTitle : ALERT_LABELS[type];
+  return (
+    <aside className={`alert alert-${type}`} role="note" aria-label={title}>
+      <div className="alert-title">
+        <AlertIcon type={type} />
+        <span>{title}</span>
+      </div>
+      <div className="alert-body">{props.children}</div>
+    </aside>
+  );
+}