create-eziwiki 0.1.1 → 0.3.0

package/README.md

@@ -16,8 +16,9 @@ A complete, static-exportable wiki:
 - **Pages from files** — every Markdown file under `content/` is published, no registration step
 - **Search** — full-text over titles, headings, and body, with a ⌘K palette; runs entirely in the browser
 - **Contents rail** with scroll tracking, generated at build time
-- **Wiki links** — `[[page]]` resolves by path, file name, or title
-- **Backlinks** on every page, and a **graph view** of how pages connect
+- **Wiki links** — `[[page]]` resolves by path, file name, or title, and hovering one previews where it goes
+- **Embeds** — `![[image.png]]` places a file, `![[page]]` includes another page's text, `![[page#section]]` just one section
+- **Backlinks** on every page, plus a graph of its **neighbourhood** — and a `/graph` view of the whole site
 - **Build-time rendering** — Markdown is compiled and syntax-highlighted during the build, so no parser ships to the browser
 - Dark mode, maths, GFM, SEO metadata, sitemap
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-eziwiki",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Scaffold a new eziwiki documentation site",
   "type": "module",
   "bin": {

package/template/app/[...slug]/page.tsx

@@ -2,7 +2,12 @@ import { MarkdownContent } from '@/components/markdown/MarkdownContent';
 import { PageTransition } from '@/components/markdown/PageTransition';
 import { TableOfContents } from '@/components/layout/TableOfContents';
 import { Backlinks } from '@/components/layout/Backlinks';
-import { getBacklinks } from '@/lib/graph/build';
+import { LocalGraph } from '@/components/layout/LocalGraph';
+import { PageNavigation } from '@/components/layout/PageNavigation';
+import { MovedPage } from '@/components/layout/MovedPage';
+import { getBacklinks, getLocalGraph } from '@/lib/graph/build';
+import { getAdjacentPages } from '@/lib/navigation/sequence';
+import { getAliasMap, aliasUrl, resolveAliasUrl } from '@/lib/content/aliases';
 import { renderDoc } from '@/lib/markdown/render';
 import { getDoc, type ContentDoc } from '@/lib/content/registry';
 import { docPathToUrl, urlToDocPath } from '@/lib/navigation/url';
@@ -35,6 +40,25 @@ function resolveSlug(slug: string[]): { path: string; url: string } | null {
   return path ? { path, url } : null;
 }
 
+/**
+ * Resolves a slug that names a page's former address.
+ *
+ * Checked only after the live map misses, so a real page always wins over an
+ * alias — an alias shadowing a page is refused when the index is built, but
+ * order here makes the intent explicit.
+ *
+ * @param slug - Route segments captured by the catch-all route
+ * @returns The document that superseded the address, and its URL, or null
+ */
+function resolveMoved(slug: string[]): { path: string; url: string } | null {
+  const { urlMap } = getSite();
+  const path = resolveAliasUrl(slug.join('/'), urlMap.strategy);
+  if (!path) return null;
+
+  const url = docPathToUrl(urlMap, path);
+  return url ? { path, url } : null;
+}
+
 /**
  * Generates per-page metadata from the document's frontmatter.
  */
@@ -44,6 +68,21 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
   const doc = resolved ? getDoc(resolved.path) : undefined;
 
   if (!resolved || !doc) {
+    const moved = resolveMoved(params.slug);
+    const target = moved ? getDoc(moved.path) : undefined;
+
+    // A former address should not compete with the page it forwards to: it is
+    // kept out of the index, and points its canonical at the destination so any
+    // ranking the old URL earned transfers rather than being split.
+    if (moved && target) {
+      return {
+        title: target.title,
+        description: target.description || global.description,
+        alternates: { canonical: pageUrl(moved.url, global.baseUrl) },
+        robots: { index: false, follow: true },
+      };
+    }
+
     return { title: global.title, description: global.description };
   }
 
@@ -89,10 +128,18 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
 export async function generateStaticParams() {
   const { urlMap, docPaths } = getSite();
 
-  return docPaths.flatMap((path) => {
+  const pages = docPaths.flatMap((path) => {
     const url = docPathToUrl(urlMap, path);
     return url ? [{ slug: url.split('/') }] : [];
   });
+
+  // Former addresses are built too, each as a page that forwards. Without this
+  // there is nothing at the old URL for a static host to serve.
+  const moved = [...getAliasMap().keys()].map((alias) => ({
+    slug: aliasUrl(alias, urlMap.strategy).split('/'),
+  }));
+
+  return [...pages, ...moved];
 }
 
 /**
@@ -135,7 +182,14 @@ function ArticleSchema({ doc, url }: { doc: ContentDoc; url: string }) {
 export default async function ContentPage({ params }: PageProps) {
   const resolved = resolveSlug(params.slug);
 
-  if (!resolved) notFound();
+  if (!resolved) {
+    const moved = resolveMoved(params.slug);
+    const target = moved ? getDoc(moved.path) : undefined;
+
+    if (moved && target) return <MovedPage url={`/${moved.url}/`} title={target.title} />;
+
+    notFound();
+  }
 
   const doc = getDoc(resolved.path);
   const rendered = await renderDoc(resolved.path);
@@ -148,7 +202,9 @@ export default async function ContentPage({ params }: PageProps) {
         <article className="prose prose-slate min-w-0 max-w-none flex-1 dark:prose-invert">
           <ArticleSchema doc={doc} url={resolved.url} />
           <MarkdownContent html={rendered.html} />
+          <PageNavigation adjacent={getAdjacentPages(resolved.path)} />
           <Backlinks links={getBacklinks(resolved.path)} />
+          <LocalGraph graph={getLocalGraph(resolved.path)} path={resolved.path} />
         </article>
 
         <aside className="hidden w-56 flex-shrink-0 xl:block">

package/template/app/layout.tsx

@@ -175,7 +175,9 @@ export default function RootLayout({ children }: { children: React.ReactNode })
         </a>
         <UrlMapProvider value={site.urlMap}>
           <TabInitializer navigation={site.navigation} />
-          <PageLayout navigation={site.navigation}>{children}</PageLayout>
+          <PageLayout navigation={site.navigation} repoUrl={site.global.repoUrl}>
+            {children}
+          </PageLayout>
           <SearchDialog />
         </UrlMapProvider>
       </body>

package/template/components/graph/GraphView.tsx

@@ -24,6 +24,10 @@ export interface GraphViewNode {
 interface GraphViewProps {
   nodes: GraphViewNode[];
   edges: LayoutEdge[];
+  /** Page to mark as the one being read, when the graph is centred on one */
+  activePath?: string;
+  /** Height utility class; the default suits a full page of its own */
+  heightClass?: string;
 }
 
 /** Nominal layout area; the SVG viewBox scales the result to fit. */
@@ -33,7 +37,7 @@ const AREA = { width: 900, height: 640 };
 const MIN_RADIUS = 5;
 const MAX_RADIUS = 14;
 
-export function GraphView({ nodes, edges }: GraphViewProps) {
+export function GraphView({ nodes, edges, activePath, heightClass = 'h-[70vh]' }: GraphViewProps) {
   const router = useRouter();
   const [hovered, setHovered] = useState<string | null>(null);
 
@@ -75,7 +79,7 @@ export function GraphView({ nodes, edges }: GraphViewProps) {
     <div className="overflow-hidden rounded-lg border border-gray-200 bg-gray-50 dark:border-gray-800 dark:bg-gray-900">
       <svg
         viewBox={`${box.x} ${box.y} ${box.width} ${box.height}`}
-        className="h-[70vh] w-full"
+        className={`${heightClass} w-full`}
         role="img"
         aria-label={`Link graph of ${nodes.length} pages and ${edges.length} links`}
       >
@@ -110,6 +114,7 @@ export function GraphView({ nodes, edges }: GraphViewProps) {
             const radius =
               MIN_RADIUS + (MAX_RADIUS - MIN_RADIUS) * Math.sqrt(node.degree / maxDegree);
             const active = !connected || connected.has(node.path);
+            const isCurrent = node.path === activePath;
 
             return (
               <g
@@ -131,18 +136,26 @@ export function GraphView({ nodes, edges }: GraphViewProps) {
                 aria-label={node.title}
               >
                 <circle
-                  r={radius}
+                  r={isCurrent ? radius + 2 : radius}
                   className={
-                    hovered === node.path
-                      ? 'fill-blue-500 stroke-white dark:stroke-gray-900'
-                      : 'fill-blue-400/80 stroke-white dark:fill-blue-500/70 dark:stroke-gray-900'
+                    isCurrent
+                      ? // The page being read is filled solid rather than tinted,
+                        // so it is findable in its own neighbourhood at a glance.
+                        'fill-blue-600 stroke-white dark:fill-blue-400 dark:stroke-gray-900'
+                      : hovered === node.path
+                        ? 'fill-blue-500 stroke-white dark:stroke-gray-900'
+                        : 'fill-blue-400/80 stroke-white dark:fill-blue-500/70 dark:stroke-gray-900'
                   }
                   strokeWidth={1.5}
                 />
                 <text
                   y={radius + 12}
                   textAnchor="middle"
-                  className="pointer-events-none fill-gray-700 text-[11px] dark:fill-gray-300"
+                  className={`pointer-events-none text-[11px] ${
+                    isCurrent
+                      ? 'fill-gray-900 font-semibold dark:fill-gray-100'
+                      : 'fill-gray-700 dark:fill-gray-300'
+                  }`}
                 >
                   {node.title}
                 </text>

package/template/components/layout/LocalGraph.tsx

@@ -0,0 +1,52 @@
+import { Share2 } from 'lucide-react';
+import { GraphView } from '@/components/graph/GraphView';
+import type { LocalGraph as LocalGraphData } from '@/lib/graph/build';
+
+/**
+ * Shows the pages immediately around the one being read.
+ *
+ * The whole-site graph on its own page answers what the wiki looks like. This
+ * answers what is next to *here*, which is the question a reader has while
+ * reading, and which the full graph stops answering once there are more than a
+ * few dozen pages to draw.
+ *
+ * It sits below the backlinks list and covers the same ground from the other
+ * side: backlinks name the pages that point here, the graph shows those and the
+ * ones this page points at, and how they relate to each other.
+ *
+ * Computed at build time, so this is a plain server component; only the SVG
+ * beneath it is interactive.
+ *
+ * @param props - Component props
+ * @param props.graph - Neighbourhood from `getLocalGraph()`
+ * @param props.path - Content path of the page at the centre
+ */
+export function LocalGraph({ graph, path }: { graph: LocalGraphData; path: string }) {
+  // A page with nothing linking either way has no neighbourhood to draw, and an
+  // empty box would only be a question the reader cannot answer.
+  if (graph.nodes.length < 2) return null;
+
+  const neighbours = graph.nodes.length - 1;
+
+  return (
+    <section
+      aria-labelledby="local-graph-heading"
+      className="mt-10 border-t border-gray-200 pt-6 dark:border-gray-800"
+    >
+      <h2
+        id="local-graph-heading"
+        className="mb-3 flex items-center gap-2 text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400"
+      >
+        <Share2 className="h-3.5 w-3.5" />
+        Connected to {neighbours} {neighbours === 1 ? 'page' : 'pages'}
+      </h2>
+
+      <GraphView
+        nodes={graph.nodes}
+        edges={graph.edges}
+        activePath={path}
+        heightClass="h-64 sm:h-72"
+      />
+    </section>
+  );
+}

package/template/components/layout/MobileMenu.tsx

@@ -7,6 +7,7 @@ import { NavigationItem } from '@/lib/payload/types';
 import { useTabStore } from '@/lib/store/tabStore';
 import { useUrlMap } from '@/components/providers/UrlMapProvider';
 import { filterHiddenItems } from '@/lib/navigation/builder';
+import { Github } from 'lucide-react';
 
 /**
  * Props for the MobileMenu component
@@ -18,6 +19,8 @@ interface MobileMenuProps {
   isOpen: boolean;
   /** Callback function to close the menu */
   onClose: () => void;
+  /** Source repository, linked from the drawer header when configured */
+  repoUrl?: string;
 }
 
 /**
@@ -221,7 +224,7 @@ function MobileNavigationItem({
  * @param props.onClose - Callback function to close the menu
  *
  */
-export function MobileMenu({ navigation, isOpen, onClose }: MobileMenuProps) {
+export function MobileMenu({ navigation, isOpen, onClose, repoUrl }: MobileMenuProps) {
   const pathname = usePathname();
   const { toPath } = useUrlMap();
 
@@ -267,6 +270,18 @@ export function MobileMenu({ navigation, isOpen, onClose }: MobileMenuProps) {
           <nav>
             <div className="flex items-center justify-between mb-1">
               <div className="flex-1" />
+              {repoUrl && (
+                <a
+                  href={repoUrl}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  aria-label="Source repository"
+                  title="Source repository"
+                  className="rounded-md p-2 text-gray-500 transition-colors hover:text-gray-700 active:bg-gray-100 dark:text-gray-400 dark:hover:text-gray-200 dark:active:bg-gray-800"
+                >
+                  <Github className="h-5 w-5" />
+                </a>
+              )}
               <button
                 onClick={onClose}
                 className="p-2 text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200 active:bg-gray-100 dark:active:bg-gray-800 rounded-md transition-colors touch-manipulation"

package/template/components/layout/MovedPage.tsx

@@ -0,0 +1,45 @@
+import Link from 'next/link';
+import { asset } from '@/lib/basePath';
+
+/**
+ * Stands in for a page that has moved, and sends the reader on.
+ *
+ * A static export has no server to answer with a 301, so the redirect is a
+ * `meta refresh` in the document itself. Search engines treat that as a
+ * permanent move when the delay is zero, and the canonical link says the same
+ * thing again for anything that reads markup rather than following it.
+ *
+ * The visible text is not decoration. A reader whose browser blocks the refresh
+ * — or who arrives with scripting and meta refresh disabled — still needs a way
+ * through, so the link is real and focusable rather than a spinner.
+ *
+ * @param props - Component props
+ * @param props.url - Href of the page that superseded this address
+ * @param props.title - Title of that page
+ */
+export function MovedPage({ url, title }: { url: string; title: string }) {
+  return (
+    <>
+      <meta httpEquiv="refresh" content={`0; url=${asset(url)}`} />
+
+      <div className="mx-auto max-w-lg px-6 py-24 text-center">
+        <p className="text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">
+          This page moved
+        </p>
+
+        <h1 className="mt-3 text-2xl font-semibold text-gray-900 dark:text-gray-100">{title}</h1>
+
+        <p className="mt-4 text-sm text-gray-600 dark:text-gray-400">
+          You are being taken there now. If nothing happens, follow the link.
+        </p>
+
+        <Link
+          href={url}
+          className="mt-6 inline-block rounded-md border border-gray-300 px-4 py-2 text-sm font-medium text-gray-900 no-underline transition-colors hover:bg-gray-50 dark:border-gray-700 dark:text-gray-100 dark:hover:bg-gray-800"
+        >
+          Continue to {title}
+        </Link>
+      </div>
+    </>
+  );
+}

package/template/components/layout/PageLayout.tsx

@@ -15,6 +15,8 @@ import { SearchTrigger } from '@/components/search/SearchTrigger';
 interface PageLayoutProps {
   /** Array of top-level navigation items */
   navigation: NavigationItem[];
+  /** Source repository, linked from the sidebar when configured */
+  repoUrl?: string;
   /** Page content to render in the main area */
   children: React.ReactNode;
 }
@@ -25,10 +27,11 @@ interface PageLayoutProps {
  *
  * @param props - Component props
  * @param props.navigation - Array of navigation items to display in sidebar/menu
+ * @param props.repoUrl - Source repository, linked from the sidebar when set
  * @param props.children - Page content to render in the main content area
  *
  */
-export function PageLayout({ navigation, children }: PageLayoutProps) {
+export function PageLayout({ navigation, repoUrl, children }: PageLayoutProps) {
   const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false);
 
   const toggleMobileMenu = () => {
@@ -63,10 +66,15 @@ export function PageLayout({ navigation, children }: PageLayoutProps) {
         </div>
       </header>
 
-      <MobileMenu navigation={navigation} isOpen={isMobileMenuOpen} onClose={closeMobileMenu} />
+      <MobileMenu
+        navigation={navigation}
+        isOpen={isMobileMenuOpen}
+        onClose={closeMobileMenu}
+        repoUrl={repoUrl}
+      />
 
       <div className="flex">
-        <Sidebar navigation={navigation} />
+        <Sidebar navigation={navigation} repoUrl={repoUrl} />
 
         <main id="main-content" tabIndex={-1} className="flex-1 min-w-0 flex flex-col">
           <div className="sticky top-0 z-20 bg-white dark:bg-gray-950">

package/template/components/layout/PageNavigation.tsx

@@ -0,0 +1,73 @@
+import Link from 'next/link';
+import { ChevronLeft, ChevronRight } from 'lucide-react';
+import type { Adjacent } from '@/lib/navigation/sequence';
+
+/**
+ * Links to the pages either side of this one in reading order.
+ *
+ * A guide is written to be read through, and until now the only way onwards was
+ * back to the sidebar to find where you had got to. The order is the sidebar's
+ * own, flattened, so the two cannot drift apart.
+ *
+ * `rel="prev"` and `rel="next"` say the same thing to a crawler, which is how a
+ * sequence of pages is declared to be one.
+ *
+ * @param props - Component props
+ * @param props.adjacent - Neighbours from `getAdjacentPages()`
+ */
+export function PageNavigation({ adjacent }: { adjacent: Adjacent }) {
+  const { previous, next } = adjacent;
+
+  // The first and last pages have one neighbour; a page outside the sequence
+  // has none, and gets nothing rather than an empty bar.
+  if (!previous && !next) return null;
+
+  return (
+    <nav
+      aria-label="Page navigation"
+      className="mt-12 flex items-stretch gap-4 border-t border-gray-200 pt-6 dark:border-gray-800"
+    >
+      {previous ? (
+        <Link
+          href={previous.url}
+          rel="prev"
+          className="group flex flex-1 items-center gap-3 rounded-lg border border-gray-200 p-4 no-underline transition-colors hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:hover:border-gray-700 dark:hover:bg-gray-800/50"
+        >
+          <ChevronLeft className="h-4 w-4 flex-shrink-0 text-gray-400 transition-transform group-hover:-translate-x-0.5" />
+          <span className="min-w-0">
+            <span className="block text-xs uppercase tracking-wide text-gray-500 dark:text-gray-400">
+              Previous
+            </span>
+            <span className="block truncate text-sm font-medium text-gray-900 dark:text-gray-100">
+              {previous.title}
+            </span>
+          </span>
+        </Link>
+      ) : (
+        // Holds the column so a lone "next" stays on the right, where it is
+        // when there is a pair.
+        <div className="flex-1" />
+      )}
+
+      {next ? (
+        <Link
+          href={next.url}
+          rel="next"
+          className="group flex flex-1 items-center justify-end gap-3 rounded-lg border border-gray-200 p-4 text-right no-underline transition-colors hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:hover:border-gray-700 dark:hover:bg-gray-800/50"
+        >
+          <span className="min-w-0">
+            <span className="block text-xs uppercase tracking-wide text-gray-500 dark:text-gray-400">
+              Next
+            </span>
+            <span className="block truncate text-sm font-medium text-gray-900 dark:text-gray-100">
+              {next.title}
+            </span>
+          </span>
+          <ChevronRight className="h-4 w-4 flex-shrink-0 text-gray-400 transition-transform group-hover:translate-x-0.5" />
+        </Link>
+      ) : (
+        <div className="flex-1" />
+      )}
+    </nav>
+  );
+}

package/template/components/layout/Sidebar.tsx

@@ -3,7 +3,7 @@
 import React, { useState, useRef, useEffect } from 'react';
 import Link from 'next/link';
 import { useRouter } from 'next/navigation';
-import { ChevronRight, ChevronsLeft, ChevronsRight, Search, Share2 } from 'lucide-react';
+import { ChevronRight, ChevronsLeft, ChevronsRight, Github, Search, Share2 } from 'lucide-react';
 import { NavigationItem } from '@/lib/payload/types';
 import { useTabStore } from '@/lib/store/tabStore';
 import { ThemeToggle } from '@/components/ThemeToggle';
@@ -18,6 +18,32 @@ import { filterHiddenItems } from '@/lib/navigation/builder';
 interface SidebarProps {
   /** Array of top-level navigation items */
   navigation: NavigationItem[];
+  /** Source repository, linked from the header when configured */
+  repoUrl?: string;
+}
+
+/**
+ * Links out to the site's source repository.
+ *
+ * Rendered only when the payload names one, so a wiki with no public source
+ * does not show a dead control. A published site otherwise gives a reader no
+ * way to reach the project it came from.
+ */
+function RepoLink({ href, collapsed }: { href: string; collapsed: boolean }) {
+  return (
+    <a
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      aria-label="Source repository"
+      title="Source repository"
+      className={`rounded-md p-2 text-gray-600 transition-colors hover:bg-gray-200 dark:text-gray-400 dark:hover:bg-gray-800 ${
+        collapsed ? '' : 'flex-shrink-0'
+      }`}
+    >
+      <Github className="h-4 w-4" />
+    </a>
+  );
 }
 
 /**
@@ -235,7 +261,7 @@ function NavigationItemComponent({
  * @param props.navigation - Array of top-level navigation items to display
  *
  */
-export function Sidebar({ navigation }: SidebarProps) {
+export function Sidebar({ navigation, repoUrl }: SidebarProps) {
   const { sidebarWidth, sidebarCollapsed, setSidebarWidth, setSidebarCollapsed } = useTabStore();
 
   const visibleNavigation = filterHiddenItems(navigation);
@@ -312,6 +338,7 @@ export function Sidebar({ navigation }: SidebarProps) {
           <>
             <SearchTrigger className="min-w-0 flex-1" />
             <ThemeToggle className="w-4 h-4" />
+            {repoUrl && <RepoLink href={repoUrl} collapsed={false} />}
             <button
               onClick={handleToggle}
               className="p-2 text-gray-600 dark:text-gray-400 hover:bg-gray-200 dark:hover:bg-gray-800 rounded-md transition-colors flex-shrink-0"
@@ -331,6 +358,7 @@ export function Sidebar({ navigation }: SidebarProps) {
             >
               <Search className="h-4 w-4" />
             </button>
+            {repoUrl && <RepoLink href={repoUrl} collapsed />}
             <button
               onClick={handleToggle}
               className="rounded-md p-2 text-gray-600 transition-colors hover:bg-gray-200 dark:text-gray-400 dark:hover:bg-gray-800"