create-eziwiki 0.1.0

package/template/README.md

@@ -0,0 +1,39 @@
+# My Wiki
+
+Built with [eziwiki](https://github.com/i3months/eziwiki).
+
+## Develop
+
+```bash
+npm install
+npm run dev
+```
+
+Open <http://localhost:3000>.
+
+## Write
+
+Drop Markdown files into `content/`. Every file becomes a page automatically —
+folders become sidebar sections. See `content/guides/writing.md` for what a page
+can contain.
+
+Set the site title, theme, and URL style in `payload/config.ts`.
+
+## Build
+
+```bash
+npm run build
+```
+
+The result is a fully static site in `out/`, deployable to GitHub Pages,
+Netlify, Vercel, S3, or any static host.
+
+## Commands
+
+```bash
+npm run dev              # Development server
+npm run build            # Static production build
+npm run check:links      # Report links that point at no page
+npm run show-urls        # List every page and its URL
+npm test                 # Run the test suite
+```

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

@@ -0,0 +1,162 @@
+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 { renderDoc } from '@/lib/markdown/render';
+import { getDoc, type ContentDoc } from '@/lib/content/registry';
+import { docPathToUrl, urlToDocPath } from '@/lib/navigation/url';
+import { getSite } from '@/lib/site';
+import { asset, fileUrl, pageUrl } from '@/lib/basePath';
+import { notFound } from 'next/navigation';
+import type { Metadata } from 'next';
+
+interface PageProps {
+  params: {
+    slug: string[];
+  };
+}
+
+/**
+ * Resolves a route's slug segments to a document in the content registry.
+ *
+ * Under the `path` strategy a slug has one segment per directory level; under
+ * `hash` it is a single opaque segment. Joining first and resolving through the
+ * URL map handles both without the route needing to know which is in effect.
+ *
+ * @param slug - Route segments captured by the catch-all route
+ * @returns The content path and its canonical URL segment, or null
+ */
+function resolveSlug(slug: string[]): { path: string; url: string } | null {
+  const { urlMap } = getSite();
+  const url = slug.join('/');
+  const path = urlToDocPath(urlMap, url);
+
+  return path ? { path, url } : null;
+}
+
+/**
+ * Generates per-page metadata from the document's frontmatter.
+ */
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { global, hiddenPaths } = getSite();
+  const resolved = resolveSlug(params.slug);
+  const doc = resolved ? getDoc(resolved.path) : undefined;
+
+  if (!resolved || !doc) {
+    return { title: global.title, description: global.description };
+  }
+
+  const title = doc.title;
+  const description = doc.description || global.description;
+  const rawOgImage = doc.frontmatter.ogImage as string | undefined;
+  const ogImage = rawOgImage ? fileUrl(rawOgImage, global.baseUrl) : undefined;
+  const canonicalUrl = pageUrl(resolved.url, global.baseUrl);
+
+  return {
+    title,
+    description,
+    alternates: {
+      canonical: canonicalUrl,
+    },
+    icons: {
+      icon: asset((doc.frontmatter.favicon as string) || global.favicon || '/favicon.ico'),
+    },
+    // Hidden pages stay reachable by direct link but should not be indexed.
+    robots: hiddenPaths.has(resolved.path) ? { index: false, follow: false } : undefined,
+    openGraph: {
+      title,
+      description,
+      url: canonicalUrl,
+      images: ogImage ? [ogImage] : undefined,
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title,
+      description,
+      images: ogImage ? [ogImage] : undefined,
+    },
+  };
+}
+
+/**
+ * Enumerates every document for static generation.
+ *
+ * The list comes from the content registry, so a Markdown file is built whether
+ * or not navigation references it. That is what lets hidden and unlisted pages
+ * work without a parallel registration step.
+ */
+export async function generateStaticParams() {
+  const { urlMap, docPaths } = getSite();
+
+  return docPaths.flatMap((path) => {
+    const url = docPathToUrl(urlMap, path);
+    return url ? [{ slug: url.split('/') }] : [];
+  });
+}
+
+/**
+ * Emits Article structured data for a document.
+ */
+function ArticleSchema({ doc, url }: { doc: ContentDoc; url: string }) {
+  const { global } = getSite();
+  const baseUrl = global.baseUrl || 'https://example.com';
+  const published = doc.frontmatter.date ?? null;
+  const modified = doc.frontmatter.updated ?? published;
+
+  return (
+    <script
+      type="application/ld+json"
+      dangerouslySetInnerHTML={{
+        __html: JSON.stringify({
+          '@context': 'https://schema.org',
+          '@type': 'Article',
+          headline: doc.title,
+          description: doc.description || global.description,
+          url: `${baseUrl}/${url}`,
+          // Dates are omitted when absent rather than stamped with the build
+          // time: a fabricated date misleads both readers and crawlers.
+          ...(published ? { datePublished: published } : {}),
+          ...(modified ? { dateModified: modified } : {}),
+          author: {
+            '@type': 'Organization',
+            name: global.title,
+          },
+        }),
+      }}
+    />
+  );
+}
+
+/**
+ * Renders a content page: the document body, plus its table of contents on
+ * screens wide enough to carry a second column.
+ */
+export default async function ContentPage({ params }: PageProps) {
+  const resolved = resolveSlug(params.slug);
+
+  if (!resolved) notFound();
+
+  const doc = getDoc(resolved.path);
+  const rendered = await renderDoc(resolved.path);
+
+  if (!doc || !rendered) notFound();
+
+  return (
+    <PageTransition>
+      <div className="flex gap-8">
+        <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} />
+          <Backlinks links={getBacklinks(resolved.path)} />
+        </article>
+
+        <aside className="hidden w-56 flex-shrink-0 xl:block">
+          <div className="sticky top-24 max-h-[calc(100vh-8rem)] overflow-y-auto">
+            <TableOfContents headings={rendered.headings} />
+          </div>
+        </aside>
+      </div>
+    </PageTransition>
+  );
+}

package/template/app/error.tsx

@@ -0,0 +1,77 @@
+'use client';
+
+import { useEffect } from 'react';
+
+interface ErrorProps {
+  error: Error & { digest?: string };
+  reset: () => void;
+}
+
+/**
+ * Error boundary component for runtime error handling
+ */
+export default function Error({ error, reset }: ErrorProps) {
+  useEffect(() => {
+    console.error('Application error:', error);
+  }, [error]);
+
+  return (
+    <div className="min-h-screen flex items-center justify-center px-4">
+      <div className="max-w-md w-full text-center">
+        <div className="mb-8">
+          <svg
+            className="mx-auto h-16 w-16 text-red-500"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"
+            />
+          </svg>
+        </div>
+
+        <h1 className="text-3xl font-bold text-gray-900 dark:text-gray-100 mb-4">
+          Oops! Something went wrong
+        </h1>
+
+        <p className="text-gray-600 dark:text-gray-400 mb-6">
+          We encountered an unexpected error while loading this page.
+        </p>
+
+        {error.message && (
+          <div className="bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg p-4 mb-6">
+            <p className="text-sm text-red-800 dark:text-red-200 font-mono break-words">
+              {error.message}
+            </p>
+          </div>
+        )}
+
+        <div className="flex flex-col sm:flex-row gap-3 justify-center">
+          <button
+            onClick={reset}
+            className="px-6 py-3 bg-blue-600 hover:bg-blue-700 text-white font-medium rounded-lg transition-colors"
+          >
+            Try again
+          </button>
+
+          <a
+            href="/"
+            className="px-6 py-3 bg-gray-200 hover:bg-gray-300 dark:bg-gray-700 dark:hover:bg-gray-600 text-gray-900 dark:text-gray-100 font-medium rounded-lg transition-colors"
+          >
+            Go home
+          </a>
+        </div>
+
+        {process.env.NODE_ENV === 'development' && error.digest && (
+          <p className="mt-6 text-xs text-gray-500 dark:text-gray-500">
+            Error digest: {error.digest}
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}

package/template/app/global-error.tsx

@@ -0,0 +1,76 @@
+'use client';
+
+import { useEffect } from 'react';
+
+interface GlobalErrorProps {
+  error: Error & { digest?: string };
+  reset: () => void;
+}
+
+/**
+ * Global error boundary component
+ * Catches errors that occur outside of the normal error boundary
+ */
+export default function GlobalError({ error, reset }: GlobalErrorProps) {
+  useEffect(() => {
+    console.error('Global application error:', error);
+  }, [error]);
+
+  return (
+    <html lang="en">
+      <body>
+        <div className="min-h-screen flex items-center justify-center px-4 bg-gray-50 dark:bg-gray-900">
+          <div className="max-w-md w-full text-center">
+            <div className="mb-8">
+              <svg
+                className="mx-auto h-16 w-16 text-red-500"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"
+                />
+              </svg>
+            </div>
+
+            <h1 className="text-3xl font-bold text-gray-900 dark:text-gray-100 mb-4">
+              Critical Error
+            </h1>
+
+            <p className="text-gray-600 dark:text-gray-400 mb-6">
+              A critical error occurred. Please try refreshing the page.
+            </p>
+
+            {error.message && (
+              <div className="bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg p-4 mb-6">
+                <p className="text-sm text-red-800 dark:text-red-200 font-mono break-words">
+                  {error.message}
+                </p>
+              </div>
+            )}
+
+            <div className="flex flex-col sm:flex-row gap-3 justify-center">
+              <button
+                onClick={reset}
+                className="px-6 py-3 bg-blue-600 hover:bg-blue-700 text-white font-medium rounded-lg transition-colors"
+              >
+                Try again
+              </button>
+
+              <a
+                href="/"
+                className="px-6 py-3 bg-gray-200 hover:bg-gray-300 dark:bg-gray-700 dark:hover:bg-gray-600 text-gray-900 dark:text-gray-100 font-medium rounded-lg transition-colors"
+              >
+                Go home
+              </a>
+            </div>
+          </div>
+        </div>
+      </body>
+    </html>
+  );
+}

package/template/app/globals.css

@@ -0,0 +1,44 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* Import theme CSS variables */
+@import '../styles/theme.css';
+
+/* Styles for build-time rendered Markdown */
+@import '../styles/markdown.css';
+
+/*
+ * `@font-face` for Pretendard and SUITE is declared in `app/layout.tsx`, not
+ * here: the font URLs need the deployment base path prefixed, which a
+ * stylesheet cannot read. See FONT_FACES there.
+ */
+
+body {
+  font-family:
+    'Pretendard',
+    'SUITE',
+    -apple-system,
+    BlinkMacSystemFont,
+    'Segoe UI',
+    sans-serif;
+  color: var(--color-text);
+  background: var(--color-background);
+  -webkit-overflow-scrolling: touch;
+}
+
+* {
+  -webkit-tap-highlight-color: rgba(0, 0, 0, 0.05);
+}
+
+html {
+  scroll-behavior: smooth;
+}
+
+@media (max-width: 768px) {
+  button,
+  a {
+    min-height: 44px;
+    min-width: 44px;
+  }
+}

package/template/app/graph/page.tsx

@@ -0,0 +1,62 @@
+import { GraphView } from '@/components/graph/GraphView';
+import { PageTransition } from '@/components/markdown/PageTransition';
+import { getLinkGraph } from '@/lib/graph/build';
+import { getSite } from '@/lib/site';
+import type { Metadata } from 'next';
+
+/**
+ * The link graph view.
+ *
+ * A static route, so it takes precedence over the catch-all content route and
+ * cannot be shadowed by a page named `graph`.
+ */
+
+export function generateMetadata(): Metadata {
+  const { global } = getSite();
+
+  return {
+    title: `Graph · ${global.title}`,
+    description: 'How the pages in this wiki link to one another.',
+    // The graph is navigation, not content; there is nothing here for a search
+    // engine to index that the pages themselves do not already provide.
+    robots: { index: false, follow: true },
+  };
+}
+
+export default function GraphPage() {
+  const { nodes, edges, broken } = getLinkGraph();
+  const linked = nodes.filter((node) => node.degree > 0).length;
+
+  return (
+    <PageTransition>
+      <div className="mb-6">
+        <h1 className="mb-2 text-2xl font-semibold text-gray-900 dark:text-gray-100">Graph</h1>
+        <p className="text-sm text-gray-600 dark:text-gray-400">
+          {nodes.length} pages, {edges.length} links. {linked} pages are connected to at least one
+          other. Hover a node to isolate its neighbours; click to open the page.
+        </p>
+      </div>
+
+      <GraphView nodes={nodes} edges={edges} />
+
+      {broken.length > 0 && (
+        <section className="mt-8">
+          <h2 className="mb-2 text-sm font-semibold text-gray-900 dark:text-gray-100">
+            Unresolved links ({broken.length})
+          </h2>
+          <ul className="space-y-1 text-sm text-gray-600 dark:text-gray-400">
+            {broken.map((link, index) => (
+              <li key={`${link.from}-${link.target}-${index}`}>
+                <code className="text-red-600 dark:text-red-400">[[{link.target}]]</code> in{' '}
+                <span className="text-gray-900 dark:text-gray-200">{link.from}</span>
+                {link.reason === 'ambiguous' && link.candidates && (
+                  <> — matches {link.candidates.join(', ')}</>
+                )}
+              </li>
+            ))}
+          </ul>
+        </section>
+      )}
+    </PageTransition>
+  );
+}

package/template/app/layout.tsx

@@ -0,0 +1,164 @@
+import type { Metadata } from 'next';
+import './globals.css';
+import 'katex/dist/katex.min.css';
+import { PageLayout } from '@/components/layout/PageLayout';
+import { TabInitializer } from '@/components/layout/TabInitializer';
+import { UrlMapProvider } from '@/components/providers/UrlMapProvider';
+import { SearchDialog } from '@/components/search/SearchDialog';
+import { payload } from '@/payload/config';
+import { validatePayload } from '@/lib/payload/validator';
+import { getSite } from '@/lib/site';
+import { asset, fileUrl, pageUrl } from '@/lib/basePath';
+
+// Validate payload at build time
+const validation = validatePayload(payload);
+if (!validation.valid) {
+  console.error('❌ Payload validation failed:');
+  validation.errors?.forEach((err) => console.error(`  - ${err}`));
+  throw new Error('Invalid payload configuration. Please fix the errors above.');
+}
+
+/**
+ * Rewrites configured social images to absolute URLs.
+ *
+ * A crawler fetching `og:image` has no page to resolve a relative path
+ * against, so the value has to carry the origin and the base path. Entries
+ * already absolute are left alone, which is how an image on a CDN keeps
+ * working.
+ *
+ * @param images - `images` as written in the payload, in any form Next accepts
+ * @returns The same shape with every local path made absolute
+ */
+function absoluteImages<T>(images: T): T {
+  const toAbsolute = (image: unknown): unknown => {
+    if (typeof image === 'string') return fileUrl(image, payload.global.baseUrl);
+    if (image && typeof image === 'object' && 'url' in image) {
+      const { url } = image as { url: string };
+      return { ...image, url: fileUrl(url, payload.global.baseUrl) };
+    }
+    return image;
+  };
+
+  if (Array.isArray(images)) return images.map(toAbsolute) as T;
+  return toAbsolute(images) as T;
+}
+
+// Generate metadata from payload
+export const metadata: Metadata = {
+  metadataBase: new URL(pageUrl('', payload.global.baseUrl)),
+  title: payload.global.title,
+  description: payload.global.description,
+  icons: {
+    icon: asset(payload.global.favicon || '/favicon.ico'),
+  },
+  alternates: {
+    canonical: pageUrl('', payload.global.baseUrl),
+  },
+  openGraph: payload.global.seo?.openGraph
+    ? {
+        title: payload.global.seo.openGraph.title || payload.global.title,
+        description: payload.global.seo.openGraph.description || payload.global.description,
+        url: pageUrl('', payload.global.baseUrl),
+        images: absoluteImages(payload.global.seo.openGraph.images),
+      }
+    : undefined,
+  twitter: payload.global.seo?.twitter
+    ? {
+        card: payload.global.seo.twitter.card || 'summary_large_image',
+        site: payload.global.seo.twitter.site,
+        creator: payload.global.seo.twitter.creator,
+        title: payload.global.seo.twitter.title || payload.global.title,
+        description: payload.global.seo.twitter.description || payload.global.description,
+        images: absoluteImages(payload.global.seo.twitter.images),
+      }
+    : undefined,
+};
+
+/**
+ * Web fonts, declared here rather than in `globals.css`.
+ *
+ * A stylesheet has no way to read the deployment base path, so a hardcoded
+ * `url('/fonts/…')` keeps pointing at the domain root and 404s once the site is
+ * served from a subdirectory — leaving every visitor on fallback fonts. Emitting
+ * the declarations from here puts them through `asset()` like every other file
+ * in `public/`.
+ *
+ * `preload` marks the weights the first paint needs; the rest load on demand.
+ */
+const FONT_FACES = [
+  { family: 'SUITE', weight: 400, file: '/fonts/SUITE/SUITE-Regular.woff2' },
+  { family: 'SUITE', weight: 600, file: '/fonts/SUITE/SUITE-SemiBold.woff2' },
+  { family: 'SUITE', weight: 700, file: '/fonts/SUITE/SUITE-Bold.woff2' },
+  {
+    family: 'Pretendard',
+    weight: 400,
+    file: '/fonts/Pretandard/Pretendard-Regular.woff2',
+    preload: true,
+  },
+  {
+    family: 'Pretendard',
+    weight: 600,
+    file: '/fonts/Pretandard/Pretendard-SemiBold.woff2',
+    preload: true,
+  },
+  { family: 'Pretendard', weight: 700, file: '/fonts/Pretandard/Pretendard-Bold.woff2' },
+];
+
+const fontFaceCss = FONT_FACES.map(
+  ({ family, weight, file }) =>
+    `@font-face{font-family:'${family}';font-weight:${weight};` +
+    `src:url('${asset(file)}') format('woff2');font-display:swap}`,
+).join('');
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  const site = getSite();
+  const homeUrl = pageUrl('', site.global.baseUrl);
+
+  return (
+    <html lang="en">
+      <head>
+        {FONT_FACES.filter((font) => font.preload).map((font) => (
+          <link
+            key={font.file}
+            rel="preload"
+            href={asset(font.file)}
+            as="font"
+            type="font/woff2"
+            crossOrigin="anonymous"
+          />
+        ))}
+        <style dangerouslySetInnerHTML={{ __html: fontFaceCss }} />
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{
+            __html: JSON.stringify({
+              '@context': 'https://schema.org',
+              '@type': 'WebSite',
+              name: site.global.title,
+              description: site.global.description,
+              url: homeUrl,
+            }),
+          }}
+        />
+      </head>
+      <body>
+        {/*
+          Reaching the article by keyboard otherwise means tabbing past the
+          whole navigation tree — thirty-six stops on this site, on every page.
+          Visible only while focused, so it costs nothing to a mouse user.
+        */}
+        <a
+          href="#main-content"
+          className="sr-only focus:not-sr-only focus:fixed focus:left-4 focus:top-4 focus:z-50 focus:rounded-md focus:bg-white focus:px-4 focus:py-2 focus:text-sm focus:font-medium focus:text-gray-900 focus:shadow-lg focus:outline focus:outline-2 focus:outline-blue-600 dark:focus:bg-gray-900 dark:focus:text-gray-100"
+        >
+          Skip to content
+        </a>
+        <UrlMapProvider value={site.urlMap}>
+          <TabInitializer navigation={site.navigation} />
+          <PageLayout navigation={site.navigation}>{children}</PageLayout>
+          <SearchDialog />
+        </UrlMapProvider>
+      </body>
+    </html>
+  );
+}

package/template/app/not-found.tsx

@@ -0,0 +1,48 @@
+import Link from 'next/link';
+
+/**
+ * 404 Not Found page
+ */
+export default function NotFound() {
+  return (
+    <div className="min-h-[60vh] flex items-center justify-center px-4">
+      <div className="max-w-md w-full text-center">
+        <div className="mb-8">
+          <svg
+            className="mx-auto h-24 w-24 text-gray-300 dark:text-gray-700"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={1.5}
+              d="M9.172 16.172a4 4 0 015.656 0M9 10h.01M15 10h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
+            />
+          </svg>
+        </div>
+
+        <h1 className="text-6xl font-bold text-gray-900 dark:text-gray-100 mb-2">404</h1>
+        <h2 className="text-2xl font-semibold text-gray-700 dark:text-gray-300 mb-4">
+          Page not found
+        </h2>
+
+        <p className="text-gray-600 dark:text-gray-400 mb-2">
+          The page you&apos;re looking for doesn&apos;t exist or has been moved.
+        </p>
+
+        <p className="text-sm text-gray-500 dark:text-gray-500 mb-8">
+          Try using the navigation sidebar to find what you&apos;re looking for.
+        </p>
+
+        <Link
+          href="/"
+          className="inline-block px-6 py-3 bg-blue-600 hover:bg-blue-700 text-white font-medium rounded-lg transition-colors shadow-sm"
+        >
+          Go back home
+        </Link>
+      </div>
+    </div>
+  );
+}