@hutusi/amytis 1.6.0 → 1.8.0

package/src/layouts/PostLayout.tsx

@@ -1,13 +1,17 @@
 import Link from 'next/link';
-import { getAuthorSlug, PostData } from '@/lib/markdown';
+import { getAuthorSlug, PostData, BacklinkSource, SlugRegistryEntry } from '@/lib/markdown';
 import MarkdownRenderer from '@/components/MarkdownRenderer';
 import RelatedPosts from '@/components/RelatedPosts';
 import SeriesList from '@/components/SeriesList';
 import PostSidebar from '@/components/PostSidebar';
 import Comments from '@/components/Comments';
 import ExternalLinks from '@/components/ExternalLinks';
+import Backlinks from '@/components/Backlinks';
 import Tag from '@/components/Tag';
 import ReadingProgressBar from '@/components/ReadingProgressBar';
+import PostNavigation from '@/components/PostNavigation';
+import AuthorCard from '@/components/AuthorCard';
+import ShareBar from '@/components/ShareBar';
 import { siteConfig } from '../../site.config';
 import { t } from '@/lib/i18n';
 
@@ -16,15 +20,20 @@ interface PostLayoutProps {
   relatedPosts?: PostData[];
   seriesPosts?: PostData[];
   seriesTitle?: string;
+  prevPost?: PostData | null;
+  nextPost?: PostData | null;
+  backlinks?: BacklinkSource[];
+  slugRegistry?: Map<string, SlugRegistryEntry>;
 }
 
-export default function PostLayout({ post, relatedPosts, seriesPosts, seriesTitle }: PostLayoutProps) {
-  const showToc = siteConfig.toc !== false && post.toc !== false && post.headings && post.headings.length > 0;
+export default function PostLayout({ post, relatedPosts, seriesPosts, seriesTitle, prevPost, nextPost, backlinks, slugRegistry }: PostLayoutProps) {
+  const showToc = siteConfig.posts?.toc !== false && post.toc !== false && post.headings && post.headings.length > 0;
   const hasSeries = !!(post.series && seriesPosts && seriesPosts.length > 0);
   const showSidebar = showToc || hasSeries;
+  const postUrl = `${siteConfig.baseUrl}/posts/${post.slug}`;
 
   return (
-    <div className={`layout-container ${showSidebar ? 'lg:max-w-7xl' : 'lg:max-w-6xl'}`}>
+    <div className="layout-container">
       <ReadingProgressBar />
       <div className={showSidebar
         ? 'grid grid-cols-1 lg:grid-cols-[280px_minmax(0,1fr)] gap-8 items-start'
@@ -38,11 +47,13 @@ export default function PostLayout({ post, relatedPosts, seriesPosts, seriesTitl
             posts={hasSeries ? seriesPosts : undefined}
             currentSlug={post.slug}
             headings={showToc ? post.headings : []}
+            shareUrl={postUrl}
+            shareTitle={post.title}
           />
         )}
 
-        <article className="min-w-0 max-w-3xl">
-          <header className="mb-16 border-b border-muted/10 pb-12">
+        <article className="min-w-0 max-w-3xl mx-auto">
+          <header className="mb-16 border-b border-muted/10 pb-8">
             {post.draft && (
               <div className="mb-4">
                 <span className="text-xs font-bold text-red-500 bg-red-100 dark:bg-red-900/30 px-2 py-1 rounded tracking-widest inline-block">
@@ -102,15 +113,36 @@ export default function PostLayout({ post, relatedPosts, seriesPosts, seriesTitl
             </div>
           )}
 
-          <MarkdownRenderer content={post.content} latex={post.latex} slug={post.slug} />
+          <MarkdownRenderer content={post.content} latex={post.latex} slug={post.slug} slugRegistry={slugRegistry} />
+
+          {post.tags && post.tags.length > 0 && (
+            <div className="mt-12 pt-12 border-t border-muted/20 flex flex-wrap items-center gap-2">
+              <span className="text-[10px] font-sans font-bold uppercase tracking-widest text-muted mr-1">{t('tags')}</span>
+              {post.tags.map((tag) => (
+                <Tag key={tag} tag={tag} variant="default" />
+              ))}
+            </div>
+          )}
 
           {post.externalLinks && post.externalLinks.length > 0 && (
             <ExternalLinks links={post.externalLinks} />
           )}
 
-          <RelatedPosts posts={relatedPosts || []} />
+          <Backlinks backlinks={backlinks ?? []} />
+
+          <ShareBar
+            url={postUrl}
+            title={post.title}
+            className={showSidebar ? 'mt-8 lg:hidden' : 'mt-8'}
+          />
+
+          <AuthorCard authors={post.authors} />
+
+          <PostNavigation prev={prevPost ?? null} next={nextPost ?? null} />
 
           <Comments slug={post.slug} />
+
+          <RelatedPosts posts={relatedPosts || []} />
         </article>
       </div>
     </div>

package/src/layouts/SimpleLayout.tsx

@@ -1,31 +1,69 @@
 import { PostData } from '@/lib/markdown';
 import MarkdownRenderer from '@/components/MarkdownRenderer';
 import SimpleLayoutHeader from '@/components/SimpleLayoutHeader';
+import LocaleSwitch from '@/components/LocaleSwitch';
+import PostSidebar from '@/components/PostSidebar';
 import { TranslationKey } from '@/i18n/translations';
+import { siteConfig } from '../../site.config';
 
 interface SimpleLayoutProps {
   post: PostData;
   titleKey?: TranslationKey;
   subtitleKey?: TranslationKey;
-  titleOverride?: string | Record<string, string>;
-  subtitleOverride?: string | Record<string, string>;
 }
 
-export default function SimpleLayout({ post, titleKey, subtitleKey, titleOverride, subtitleOverride }: SimpleLayoutProps) {
-  return (
-    <div className="layout-main">
-      <article className="max-w-3xl mx-auto">
-        <SimpleLayoutHeader
-          title={post.title}
-          excerpt={post.excerpt}
-          titleKey={titleKey}
-          subtitleKey={subtitleKey}
-          titleOverride={titleOverride}
-          subtitleOverride={subtitleOverride}
-        />
+export default function SimpleLayout({ post, titleKey, subtitleKey }: SimpleLayoutProps) {
+  const defaultLocale = siteConfig.i18n.defaultLocale;
+  const localeEntries = Object.entries(post.contentLocales ?? {});
+  const showToc = siteConfig.posts?.toc !== false && post.toc !== false && post.headings?.length > 0;
+  const localeHeadings = post.contentLocales
+    ? Object.fromEntries(
+        Object.entries(post.contentLocales)
+          .filter(([, data]) => data.headings && data.headings.length > 0)
+          .map(([locale, data]) => [locale, data.headings!])
+      )
+    : undefined;
 
+  const articleContent = (
+    <>
+      <SimpleLayoutHeader
+        title={post.title}
+        excerpt={post.excerpt}
+        titleKey={titleKey}
+        subtitleKey={subtitleKey}
+        contentLocales={post.contentLocales}
+      />
+      {localeEntries.length > 0 ? (
+        <LocaleSwitch>
+          <div data-locale={defaultLocale}>
+            <MarkdownRenderer content={post.content} latex={post.latex} slug={post.slug} />
+          </div>
+          {localeEntries.map(([locale, data]) => (
+            <div key={locale} data-locale={locale} style={{ display: 'none' }}>
+              <MarkdownRenderer content={data.content} latex={post.latex} slug={post.slug} />
+            </div>
+          ))}
+        </LocaleSwitch>
+      ) : (
         <MarkdownRenderer content={post.content} latex={post.latex} slug={post.slug} />
-      </article>
+      )}
+    </>
+  );
+
+  return (
+    <div className="layout-main">
+      {showToc ? (
+        <div className="grid grid-cols-1 lg:grid-cols-[280px_minmax(0,1fr)] gap-8 items-start">
+          <PostSidebar currentSlug={post.slug} headings={post.headings} localeHeadings={localeHeadings} />
+          <article className="min-w-0 max-w-3xl">
+            {articleContent}
+          </article>
+        </div>
+      ) : (
+        <article className="max-w-3xl mx-auto">
+          {articleContent}
+        </article>
+      )}
     </div>
   );
 }

package/src/lib/markdown.ts

@@ -10,6 +10,7 @@ const pagesDirectory = path.join(process.cwd(), 'content');
 const seriesDirectory = path.join(process.cwd(), 'content', 'series');
 const booksDirectory = path.join(process.cwd(), 'content', 'books');
 const flowsDirectory = path.join(process.cwd(), 'content', 'flows');
+const notesDirectory = path.join(process.cwd(), 'content', 'notes');
 
 const ExternalLinkSchema = z.object({
   name: z.string(),
@@ -68,6 +69,7 @@ export interface PostData {
   readingTime: string;
   content: string;
   headings: Heading[];
+  contentLocales?: Record<string, { content: string; title?: string; excerpt?: string; headings?: Heading[] }>;
 }
 
 export function calculateReadingTime(content: string): string {
@@ -97,7 +99,7 @@ export function generateExcerpt(content: string): string {
   plain = plain.replace(/!\[[^\]]*\]\([^)]+\)/g, '');
   plain = plain.replace(/\*\[([^\]]+)\*\]\([^)]+\)/g, '$1');
   plain = plain.replace(/(\$\*\*|__|\*|_)/g, '');
-  plain = plain.replace(/`[^`]*`/g, '');
+  plain = plain.replace(/`([^`]+)`/g, '$1');
   plain = plain.replace(/^>\s+/gm, '');
   plain = plain.replace(/\s+/g, ' ').trim();
   
@@ -238,7 +240,7 @@ export function getAllPosts(): PostData[] {
       
       if (match) {
         dateFromFileName = match[1];
-        if (siteConfig.includeDateInUrl) {
+        if (siteConfig.posts?.includeDateInUrl) {
           slug = rawName;
         } else {
           slug = match[2];
@@ -266,7 +268,7 @@ export function getAllPosts(): PostData[] {
                let sDate = undefined;
                if (sMatch) {
                  sDate = sMatch[1];
-                 sSlug = siteConfig.includeDateInUrl ? sRawName : sMatch[2];
+                 sSlug = siteConfig.posts?.includeDateInUrl ? sRawName : sMatch[2];
                }
                
                allPostsData.push(parseMarkdownFile(
@@ -294,7 +296,7 @@ export function getAllPosts(): PostData[] {
                      
                      if (sMatch) {
                        sDate = sMatch[1];
-                       sSlug = siteConfig.includeDateInUrl ? sItem.name : sMatch[2];
+                       sSlug = siteConfig.posts?.includeDateInUrl ? sItem.name : sMatch[2];
                      }
 
                      allPostsData.push(parseMarkdownFile(
@@ -338,7 +340,7 @@ export function getAllPosts(): PostData[] {
         return false;
       }
 
-      if (!siteConfig.showFuturePosts) {
+      if (!siteConfig.posts?.showFuturePosts) {
         const postDate = new Date(post.date);
         const now = new Date();
         if (postDate > now) return false;
@@ -396,7 +398,7 @@ function findPostFile(name: string, targetSlug: string): PostData | null {
 export function getPostBySlug(slug: string): PostData | null {
   let post: PostData | null = null;
 
-  if (siteConfig.includeDateInUrl) {
+  if (siteConfig.posts?.includeDateInUrl) {
     post = findPostFile(slug, slug);
   } else {
     post = findPostFile(slug, slug);
@@ -445,7 +447,7 @@ export function getPostBySlug(slug: string): PostData | null {
     return null;
   }
 
-  if (!siteConfig.showFuturePosts) {
+  if (!siteConfig.posts?.showFuturePosts) {
       const postDate = new Date(post.date);
       const now = new Date();
       if (postDate > now) return null;
@@ -453,18 +455,53 @@ export function getPostBySlug(slug: string): PostData | null {
   return post;
 }
 
+/**
+ * Load the content and frontmatter of a locale variant file, e.g. about.zh.mdx.
+ * Returns null when the file does not exist or cannot be parsed.
+ */
+function loadLocaleContent(slug: string, locale: string): { content: string; title?: string; excerpt?: string; headings?: Heading[] } | null {
+  for (const ext of ['.mdx', '.md']) {
+    const filePath = path.join(pagesDirectory, `${slug}.${locale}${ext}`);
+    if (fs.existsSync(filePath)) {
+      try {
+        const { data, content } = matter(fs.readFileSync(filePath, 'utf8'));
+        const body = content.replace(/^\s*#\s+[^\n]+/, '').trim();
+        return {
+          content: body,
+          title: typeof data.title === 'string' ? data.title : undefined,
+          excerpt: typeof data.excerpt === 'string' ? data.excerpt : undefined,
+          headings: getHeadings(body),
+        };
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Collect contentLocales for all non-default locales that have a variant file.
+ */
+function attachContentLocales(page: PostData, slug: string): PostData {
+  const defaultLocale = siteConfig.i18n.defaultLocale;
+  const otherLocales = siteConfig.i18n.locales.filter(l => l !== defaultLocale);
+  const contentLocales: NonNullable<PostData['contentLocales']> = {};
+  for (const locale of otherLocales) {
+    const localeData = loadLocaleContent(slug, locale);
+    if (localeData !== null) contentLocales[locale] = localeData;
+  }
+  return Object.keys(contentLocales).length > 0 ? { ...page, contentLocales } : page;
+}
+
 export function getPageBySlug(slug: string): PostData | null {
   try {
     let fullPath = path.join(pagesDirectory, `${slug}.mdx`);
     if (!fs.existsSync(fullPath)) {
       fullPath = path.join(pagesDirectory, `${slug}.md`);
     }
-    
-    if (!fs.existsSync(fullPath)) {
-      return null;
-    }
-
-    return parseMarkdownFile(fullPath, slug);
+    if (!fs.existsSync(fullPath)) return null;
+    return attachContentLocales(parseMarkdownFile(fullPath, slug), slug);
   } catch {
     return null;
   }
@@ -473,11 +510,21 @@ export function getPageBySlug(slug: string): PostData | null {
 export function getAllPages(): PostData[] {
   const items = fs.readdirSync(pagesDirectory, { withFileTypes: true });
   return items
-    .filter(item => item.isFile() && (item.name.endsWith('.mdx') || item.name.endsWith('.md')))
+    .filter(item => {
+      if (!item.isFile()) return false;
+      if (!item.name.endsWith('.mdx') && !item.name.endsWith('.md')) return false;
+      // Exclude locale variant files (e.g. about.zh.mdx, about.en.mdx) — they are not standalone routes
+      const base = item.name.replace(/\.mdx?$/, '');
+      const parts = base.split('.');
+      if (parts.length > 1 && siteConfig.i18n.locales.includes(parts[parts.length - 1])) {
+        return false;
+      }
+      return true;
+    })
     .map(item => {
       const slug = item.name.replace(/\.mdx?$/, '');
       const fullPath = path.join(pagesDirectory, item.name);
-      return parseMarkdownFile(fullPath, slug);
+      return attachContentLocales(parseMarkdownFile(fullPath, slug), slug);
     });
 }
 
@@ -503,6 +550,7 @@ export function getFlowTags(): Record<string, number> {
 export function getAllTags(): Record<string, number> {
   const allPosts = getAllPosts();
   const allFlows = getAllFlows();
+  const allNotes = getAllNotes();
   const tags: Record<string, number> = {};
 
   allPosts.forEach((post) => {
@@ -519,6 +567,13 @@ export function getAllTags(): Record<string, number> {
     });
   });
 
+  allNotes.forEach((note) => {
+    note.tags.forEach((tag) => {
+      const normalizedTag = tag.toLowerCase();
+      tags[normalizedTag] = (tags[normalizedTag] || 0) + 1;
+    });
+  });
+
   return tags;
 }
 
@@ -658,6 +713,16 @@ export function getFeaturedPosts(): PostData[] {
   return allPosts.filter(post => post.featured);
 }
 
+export function getAdjacentPosts(slug: string): { prev: PostData | null; next: PostData | null } {
+  const allPosts = getAllPosts(); // sorted desc by date (newest first)
+  const index = allPosts.findIndex(p => p.slug === slug);
+  if (index === -1) return { prev: null, next: null };
+  return {
+    prev: index < allPosts.length - 1 ? allPosts[index + 1] : null, // older post
+    next: index > 0 ? allPosts[index - 1] : null,                   // newer post
+  };
+}
+
 export function getFeaturedSeries(): Record<string, PostData[]> {
   const allSeries = getAllSeries();
   const featuredSeries: Record<string, PostData[]> = {};
@@ -909,7 +974,7 @@ export function getBooksByAuthor(author: string): BookData[] {
 // ─── Flows (Daily Notes) ────────────────────────────────────────────────────
 
 const FlowSchema = z.object({
-  title: z.string(),
+  title: z.string().optional(),
   date: z.union([z.string(), z.date()]).transform(val => new Date(val).toISOString().split('T')[0]).optional(),
   tags: z.array(z.string()).optional().default([]),
   draft: z.boolean().optional().default(false),
@@ -945,7 +1010,7 @@ function parseFlowFile(fullPath: string, slug: string): FlowData {
   return {
     slug,
     date,
-    title: data.title,
+    title: data.title ?? date, // fall back to date string if no title in frontmatter
     tags: data.tags,
     draft: data.draft,
     content: contentWithoutH1,
@@ -1001,7 +1066,7 @@ export function getAllFlows(): FlowData[] {
   return flows
     .filter(flow => {
       if (process.env.NODE_ENV === 'production' && flow.draft) return false;
-      if (!siteConfig.showFuturePosts) {
+      if (!siteConfig.posts?.showFuturePosts) {
         const flowDate = new Date(flow.date);
         const now = new Date();
         if (flowDate > now) return false;
@@ -1065,3 +1130,267 @@ export function getAdjacentFlows(slug: string): { prev: FlowData | null; next: F
 export function getRecentFlows(limit: number = 5): FlowData[] {
   return getAllFlows().slice(0, limit);
 }
+
+// ─── Notes (Knowledge Base) ──────────────────────────────────────────────────
+
+const NoteSchema = z.object({
+  title: z.string(),
+  date: z.union([z.string(), z.date()]).transform(val => new Date(val).toISOString().split('T')[0]).optional(),
+  tags: z.array(z.string()).optional().default([]),
+  draft: z.boolean().optional().default(false),
+  aliases: z.array(z.string()).optional().default([]),
+  toc: z.boolean().optional().default(true),
+  backlinks: z.boolean().optional().default(true),
+});
+
+export interface NoteData {
+  slug: string;
+  title: string;
+  date: string;
+  tags: string[];
+  draft: boolean;
+  aliases: string[];
+  toc: boolean;
+  backlinks: boolean;
+  content: string;
+  excerpt: string;
+  headings: Heading[];
+  readingTime: string;
+}
+
+function parseNoteFile(fullPath: string, slug: string): NoteData {
+  const fileContents = fs.readFileSync(fullPath, 'utf8');
+  const { data: rawData, content } = matter(fileContents);
+
+  const parsed = NoteSchema.safeParse(rawData);
+  if (!parsed.success) {
+    console.error(`Invalid note frontmatter in ${fullPath}:`, parsed.error.format());
+    throw new Error(`Invalid note frontmatter in ${fullPath}`);
+  }
+  const data = parsed.data;
+
+  const contentWithoutH1 = content.replace(/^\s*#\s+[^\n]+/, '').trim();
+  const date = data.date || fs.statSync(fullPath).mtime.toISOString().split('T')[0];
+  const excerpt = generateExcerpt(contentWithoutH1);
+  const headings = getHeadings(content);
+  const readingTime = calculateReadingTime(contentWithoutH1);
+
+  return {
+    slug,
+    title: data.title,
+    date,
+    tags: data.tags,
+    draft: data.draft,
+    aliases: data.aliases,
+    toc: data.toc,
+    backlinks: data.backlinks,
+    content: contentWithoutH1,
+    excerpt,
+    headings,
+    readingTime,
+  };
+}
+
+let _allNotes: NoteData[] | null = null;
+
+export function getAllNotes(): NoteData[] {
+  if (_allNotes && process.env.NODE_ENV === 'production') return _allNotes;
+
+  if (!fs.existsSync(notesDirectory)) {
+    _allNotes = [];
+    return _allNotes;
+  }
+
+  const notes: NoteData[] = [];
+  const items = fs.readdirSync(notesDirectory, { withFileTypes: true });
+
+  for (const item of items) {
+    if (!item.isFile()) continue;
+    if (!item.name.endsWith('.md') && !item.name.endsWith('.mdx')) continue;
+    const slug = item.name.replace(/\.mdx?$/, '');
+    const fullPath = path.join(notesDirectory, item.name);
+    try {
+      notes.push(parseNoteFile(fullPath, slug));
+    } catch (e) {
+      console.error(`Error parsing note ${fullPath}:`, e);
+    }
+  }
+
+  _allNotes = notes
+    .filter(note => process.env.NODE_ENV !== 'production' || !note.draft)
+    .sort((a, b) => (a.date < b.date ? 1 : -1));
+
+  return _allNotes;
+}
+
+export function getNoteBySlug(slug: string): NoteData | null {
+  if (!fs.existsSync(notesDirectory)) return null;
+
+  const mdxPath = path.join(notesDirectory, `${slug}.mdx`);
+  const mdPath = path.join(notesDirectory, `${slug}.md`);
+
+  let fullPath = '';
+  if (fs.existsSync(mdxPath)) fullPath = mdxPath;
+  else if (fs.existsSync(mdPath)) fullPath = mdPath;
+  else return null;
+
+  try {
+    const note = parseNoteFile(fullPath, slug);
+    if (process.env.NODE_ENV === 'production' && note.draft) return null;
+    return note;
+  } catch {
+    return null;
+  }
+}
+
+export function getAdjacentNotes(slug: string): { prev: NoteData | null; next: NoteData | null } {
+  const allNotes = getAllNotes(); // sorted newest-first
+  const index = allNotes.findIndex(n => n.slug === slug);
+  if (index === -1) return { prev: null, next: null };
+  return {
+    prev: index < allNotes.length - 1 ? allNotes[index + 1] : null, // older
+    next: index > 0 ? allNotes[index - 1] : null, // newer
+  };
+}
+
+export function getRecentNotes(limit: number = 5): NoteData[] {
+  return getAllNotes().slice(0, limit);
+}
+
+export function getNoteTags(): Record<string, number> {
+  const tags: Record<string, number> = {};
+  getAllNotes().forEach(note => {
+    note.tags.forEach(tag => {
+      const normalized = tag.toLowerCase();
+      tags[normalized] = (tags[normalized] || 0) + 1;
+    });
+  });
+  return tags;
+}
+
+export function getNotesByTag(tag: string): NoteData[] {
+  return getAllNotes().filter(n =>
+    n.tags.map(t => t.toLowerCase()).includes(tag.toLowerCase())
+  );
+}
+
+// ─── Slug Registry ───────────────────────────────────────────────────────────
+
+export interface SlugRegistryEntry {
+  url: string;
+  type: 'post' | 'note' | 'flow' | 'series';
+  title: string;
+}
+
+let _slugRegistry: Map<string, SlugRegistryEntry> | null = null;
+
+export function buildSlugRegistry(): Map<string, SlugRegistryEntry> {
+  if (_slugRegistry && process.env.NODE_ENV === 'production') return _slugRegistry;
+
+  const map = new Map<string, SlugRegistryEntry>();
+
+  getAllPosts().forEach(p =>
+    map.set(p.slug, { url: `/posts/${p.slug}`, type: 'post', title: p.title })
+  );
+
+  getAllFlows().forEach(f =>
+    map.set(f.slug, { url: `/flows/${f.slug}`, type: 'flow', title: f.title })
+  );
+
+  getAllNotes().forEach(n => {
+    if (map.has(n.slug)) {
+      console.warn(`[slugRegistry] Note slug "${n.slug}" conflicts with an existing entry.`);
+    }
+    map.set(n.slug, { url: `/notes/${n.slug}`, type: 'note', title: n.title });
+    n.aliases.forEach(a => {
+      if (map.has(a)) {
+        console.warn(`[slugRegistry] Note alias "${a}" (→ ${n.slug}) conflicts with existing slug; skipping.`);
+      } else {
+        map.set(a, { url: `/notes/${n.slug}`, type: 'note', title: n.title });
+      }
+    });
+  });
+
+  if (fs.existsSync(seriesDirectory)) {
+    fs.readdirSync(seriesDirectory, { withFileTypes: true }).forEach(entry => {
+      if (!entry.isDirectory()) return;
+      const slug = entry.name;
+      const seriesData = getSeriesData(slug);
+      map.set(slug, {
+        url: `/series/${slug}`,
+        type: 'series',
+        title: seriesData?.title || slug,
+      });
+    });
+  }
+
+  _slugRegistry = map;
+  return map;
+}
+
+// ─── Backlink Index ──────────────────────────────────────────────────────────
+
+export interface BacklinkSource {
+  slug: string;
+  title: string;
+  type: 'post' | 'note' | 'flow' | 'series';
+  url: string;
+  context: string;
+}
+
+function extractWikilinkContext(text: string, matchStart: number, matchEnd: number): string {
+  const RADIUS = 120;
+  const start = Math.max(0, matchStart - RADIUS);
+  const end = Math.min(text.length, matchEnd + RADIUS);
+  let ctx = text.slice(start, end);
+
+  // Replace wikilinks in context with just display text for readability
+  ctx = ctx.replace(/\[\[([^\]|]+?)(?:\|([^\]]+?))?\]\]/g, (_, slug, display) => display || slug);
+
+  if (start > 0) ctx = ctx.replace(/^[^\s.!?]{1,30}/, '').trimStart();
+  if (end < text.length) ctx = ctx.replace(/[^\s.!?]{1,30}$/, '').trimEnd();
+
+  return ctx.trim().slice(0, 200);
+}
+
+function buildBacklinkIndex(): Map<string, BacklinkSource[]> {
+  const index = new Map<string, BacklinkSource[]>();
+
+  const addBacklinks = (
+    content: string,
+    sourceSlug: string,
+    sourceTitle: string,
+    sourceType: BacklinkSource['type'],
+    sourceUrl: string
+  ) => {
+    // Create a fresh RegExp per call to avoid lastIndex issues with 'g' flag
+    const WIKILINK = /\[\[([^\]|]+?)(?:\|([^\]]+?))?\]\]/g;
+    let match;
+    while ((match = WIKILINK.exec(content)) !== null) {
+      const targetSlug = match[1].trim();
+      if (targetSlug === sourceSlug) continue; // skip self-references
+      const context = extractWikilinkContext(content, match.index, match.index + match[0].length);
+      let sources = index.get(targetSlug);
+      if (!sources) {
+        sources = [];
+        index.set(targetSlug, sources);
+      }
+      if (!sources.some(b => b.slug === sourceSlug && b.type === sourceType)) {
+        sources.push({ slug: sourceSlug, title: sourceTitle, type: sourceType, url: sourceUrl, context });
+      }
+    }
+  };
+
+  getAllPosts().forEach(p => addBacklinks(p.content, p.slug, p.title, 'post', `/posts/${p.slug}`));
+  getAllNotes().forEach(n => addBacklinks(n.content, n.slug, n.title, 'note', `/notes/${n.slug}`));
+  getAllFlows().forEach(f => addBacklinks(f.content, f.slug, f.title, 'flow', `/flows/${f.slug}`));
+
+  return index;
+}
+
+let _backlinkIndex: Map<string, BacklinkSource[]> | null = null;
+
+export function getBacklinks(slug: string): BacklinkSource[] {
+  if (!_backlinkIndex || process.env.NODE_ENV !== 'production') _backlinkIndex = buildBacklinkIndex();
+  return _backlinkIndex.get(slug) ?? [];
+}