create-eziwiki 0.1.0

package/template/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "my-wiki",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Documentation site built with eziwiki",
+  "scripts": {
+    "dev": "npm run build:search && next dev",
+    "build": "npm run validate:payload && npm run check:links && npm run build:search && next build",
+    "export": "npm run build",
+    "start": "next start",
+    "lint": "eslint . --ext .ts,.tsx",
+    "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md}\"",
+    "type-check": "tsc --noEmit",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "validate:payload": "tsx scripts/validate-payload.ts",
+    "show-urls": "tsx scripts/show-urls.ts",
+    "build:search": "tsx scripts/build-search-index.ts",
+    "check:links": "tsx scripts/check-links.ts",
+    "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md,css}\""
+  },
+  "dependencies": {
+    "@shikijs/rehype": "^4.3.1",
+    "ajv": "^8.12.0",
+    "ajv-formats": "^3.0.1",
+    "gray-matter": "^4.0.3",
+    "hast-util-to-string": "^3.0.1",
+    "katex": "^0.16.47",
+    "lucide-react": "^0.554.0",
+    "minisearch": "^7.2.0",
+    "next": "^14.2.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "rehype-katex": "^7.0.1",
+    "rehype-raw": "^7.0.0",
+    "rehype-slug": "^6.0.0",
+    "rehype-stringify": "^10.0.1",
+    "remark-gfm": "^4.0.0",
+    "remark-math": "^6.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "shiki": "^4.3.1",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0",
+    "zustand": "^5.0.8"
+  },
+  "devDependencies": {
+    "@tailwindcss/typography": "^0.5.10",
+    "@types/hast": "^3.0.5",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^20.11.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "autoprefixer": "^10.4.17",
+    "eslint": "^8.56.0",
+    "eslint-config-next": "^14.2.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "postcss": "^8.4.35",
+    "prettier": "^3.2.5",
+    "tailwindcss": "^3.4.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.9"
+  }
+}

package/template/payload/config.ts

@@ -0,0 +1,34 @@
+import { Payload } from '@/lib/payload/types';
+
+/**
+ * Site configuration.
+ *
+ * Navigation is optional: pages under `content/` are discovered automatically,
+ * ordered by their frontmatter `order` and grouped by folder. Add a
+ * `navigation` array here only when you want to override that.
+ */
+export const payload: Payload = {
+  global: {
+    title: 'My Wiki',
+    description: 'A documentation site built with eziwiki',
+    favicon: '/favicon.svg',
+    baseUrl: 'https://example.com',
+
+    /**
+     * 'path' gives readable, indexable URLs (/guides/writing).
+     * 'hash' gives opaque ones (/a3f2e9d1-...), hiding the structure at the
+     * cost of SEO and shareable links.
+     */
+    urlStrategy: 'path',
+
+    /** Publish pages found under content/ without listing them below. */
+    autoNavigation: true,
+  },
+
+  theme: {
+    primary: '#2563eb',
+    secondary: '#7c3aed',
+  },
+};
+
+export default payload;

package/template/postcss.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/template/prettierignore

@@ -0,0 +1,7 @@
+node_modules
+.next
+out
+reference
+*.config.js
+package-lock.json
+packages/*/template

package/template/prettierrc

@@ -0,0 +1,8 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "arrowParens": "always",
+  "semi": true,
+  "tabWidth": 2
+}

package/template/public/favicon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <defs>
+    <linearGradient id="grad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#6366f1;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#8b5cf6;stop-opacity:1" />
+    </linearGradient>
+  </defs>
+  <rect width="100" height="100" rx="22" fill="url(#grad)"/>
+  <text x="50" y="68" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="48" font-weight="700" fill="#ffffff" text-anchor="middle" letter-spacing="-2">ezi</text>
+</svg>

package/template/scripts/build-search-index.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env tsx
+
+/**
+ * Generates the client search index into `public/`.
+ *
+ * Runs before `next dev` and `next build`. Writing a static JSON file — rather
+ * than exposing a route — keeps search working on any static host, with no
+ * server to query.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { buildSearchIndex } from '../lib/search/build';
+import { SEARCH_INDEX_PATH } from '../lib/search/types';
+
+async function main() {
+  console.log('🔍 Building search index...');
+
+  const index = await buildSearchIndex();
+  const outputPath = path.join(process.cwd(), 'public', SEARCH_INDEX_PATH);
+  const json = JSON.stringify(index);
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, json, 'utf-8');
+
+  const pages = new Set(index.docs.map((doc) => doc.path)).size;
+  const kb = (Buffer.byteLength(json) / 1024).toFixed(1);
+
+  console.log(`✅ Indexed ${index.docs.length} entries across ${pages} pages (${kb} kB)\n`);
+}
+
+main().catch((error) => {
+  console.error('❌ Failed to build search index:');
+  console.error(error);
+  process.exit(1);
+});

package/template/scripts/check-links.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env tsx
+
+/**
+ * Reports links that point at no page.
+ *
+ * Runs as part of the build and reports rather than fails: a dangling link in
+ * one page is not a reason to block a deploy of the other twenty, and content
+ * is often written before the page it references exists. Pass `--strict` in CI
+ * to make it an error.
+ */
+
+import { getLinkGraph } from '../lib/graph/build';
+
+const strict = process.argv.includes('--strict');
+const { broken, nodes, edges } = getLinkGraph();
+
+if (broken.length === 0) {
+  console.log(`🔗 Links OK — ${edges.length} links across ${nodes.length} pages\n`);
+  process.exit(0);
+}
+
+console.log(`\n🔗 ${broken.length} unresolved link${broken.length === 1 ? '' : 's'}:\n`);
+
+for (const link of broken) {
+  console.log(`  content/${link.from}.md`);
+
+  if (link.reason === 'ambiguous') {
+    console.log(`    [[${link.target}]] is ambiguous — matches ${link.candidates?.join(', ')}`);
+    console.log('    Use the full path to disambiguate.');
+  } else {
+    console.log(`    [[${link.target}]] matches no page`);
+  }
+}
+
+console.log();
+
+if (strict) {
+  console.error('❌ Failing because --strict was passed.\n');
+  process.exit(1);
+}

package/template/scripts/show-urls.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env tsx
+
+/**
+ * Lists the URL of every page the site will build.
+ *
+ * Useful for finding the address of a hidden page, and for confirming what the
+ * configured URL strategy actually produces before deploying.
+ *
+ * Run with: npm run show-urls
+ */
+
+import { payload } from '../payload/config';
+import { getContentRegistry } from '../lib/content/registry';
+import { getUrlMap } from '../lib/navigation/urlMap';
+
+const { docs } = getContentRegistry();
+const urlMap = getUrlMap();
+const baseUrl = payload.global.baseUrl || 'http://localhost:3000';
+
+console.log(`\n📋 Page URLs  (strategy: ${urlMap.strategy})\n`);
+console.log('='.repeat(80));
+
+for (const doc of docs) {
+  const url = urlMap.toUrl[doc.path];
+  if (!url) continue;
+
+  console.log(`${doc.hidden ? '🔒 [HIDDEN]' : '📄'} ${doc.title}`);
+  console.log(`   source → content/${doc.path}.md`);
+  console.log(`   url    → ${baseUrl}/${url}`);
+  console.log();
+}
+
+const hiddenCount = docs.filter((doc) => doc.hidden).length;
+
+console.log('='.repeat(80));
+console.log(`\nTotal pages: ${docs.length}`);
+console.log(`Hidden pages: ${hiddenCount}`);
+
+if (hiddenCount > 0) {
+  console.log('\n💡 Hidden pages are absent from navigation but reachable at the URL above.');
+}
+
+if (urlMap.strategy === 'hash') {
+  console.log(
+    "\n💡 URLs are hashed. Set global.urlStrategy to 'path' in payload/config.ts for\n" +
+      '   readable, indexable URLs.',
+  );
+}

package/template/scripts/validate-payload.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env tsx
+
+/**
+ * Build-time payload validation script
+ * This script validates the payload configuration against the JSON Schema
+ * and exits with an error code if validation fails.
+ */
+
+import { validatePayload } from '../lib/payload/validator';
+import payload from '../payload/config';
+
+function main() {
+  console.log('🔍 Validating payload configuration...\n');
+
+  const validation = validatePayload(payload);
+
+  if (!validation.valid) {
+    console.error('❌ Payload validation failed:\n');
+    validation.errors?.forEach((err) => {
+      console.error(`  • ${err}`);
+    });
+    console.error('\nPlease fix the errors in payload/config.ts and try again.\n');
+    process.exit(1);
+  }
+
+  console.log('✅ Payload validation passed!\n');
+  process.exit(0);
+}
+
+main();

package/template/styles/markdown.css

@@ -0,0 +1,167 @@
+/**
+ * Styles for build-time rendered Markdown.
+ *
+ * The document body is plain HTML produced by the unified pipeline, so these
+ * rules replace the per-element Tailwind classes the old runtime renderer
+ * applied. Typography comes from @tailwindcss/typography via `.prose`; what
+ * follows covers the parts it does not know about — Shiki output, code-block
+ * chrome, and anchor targets.
+ */
+
+/* ---------------------------------------------------------------- code ---- */
+
+.ezw-code {
+  margin: 1.5rem 0;
+  border-radius: 0.5rem;
+  overflow: hidden;
+  border: 1px solid var(--color-border);
+}
+
+.ezw-code__bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.5rem 1rem;
+  background: var(--color-code-bg);
+  border-bottom: 1px solid var(--color-border);
+}
+
+.ezw-code__lang {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  color: var(--color-text-muted);
+}
+
+.ezw-code__copy {
+  font-size: 0.75rem;
+  padding: 0.25rem 0.5rem;
+  border-radius: 0.25rem;
+  color: var(--color-text-muted);
+  background: transparent;
+  transition:
+    color 0.15s ease,
+    background-color 0.15s ease;
+}
+
+.ezw-code__copy:hover {
+  color: var(--color-text);
+  background: var(--color-sidebar-hover);
+}
+
+.ezw-code__copy[data-copied] {
+  color: #16a34a;
+}
+
+/* Shiki emits its own background and padding; strip the prose defaults so the
+   two do not fight over the same box. */
+.ezw-code pre {
+  margin: 0;
+  padding: 1rem;
+  border-radius: 0;
+  overflow-x: auto;
+  font-size: 0.875rem;
+  line-height: 1.6;
+}
+
+.ezw-code pre code {
+  background: transparent;
+  padding: 0;
+  font-size: inherit;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+}
+
+/* Typography adds quotation marks around inline code; they read as noise in
+   technical prose. */
+.ezw-prose :where(code):not(:where(pre code))::before,
+.ezw-prose :where(code):not(:where(pre code))::after {
+  content: none;
+}
+
+.ezw-prose :where(code):not(:where(pre code)) {
+  background: var(--color-code-bg);
+  color: var(--color-code-text);
+  padding: 0.15em 0.4em;
+  border-radius: 0.25rem;
+  font-weight: 400;
+  font-size: 0.9em;
+}
+
+/* --------------------------------------------------------- shiki themes ---- */
+
+/* Shiki is configured with `defaultColor: false`, so it writes both themes as
+   CSS variables on each token and neither is applied until one is selected
+   here. This is what makes theme switching instant and flash-free. */
+.shiki,
+.shiki span {
+  color: var(--shiki-light);
+}
+
+.shiki {
+  background-color: var(--shiki-light-bg);
+}
+
+html.dark .shiki,
+html.dark .shiki span {
+  color: var(--shiki-dark);
+}
+
+html.dark .shiki {
+  background-color: var(--shiki-dark-bg);
+}
+
+/* ----------------------------------------------------------- wikilinks ---- */
+
+.ezw-wikilink {
+  text-decoration: none;
+  border-bottom: 1px solid color-mix(in srgb, var(--color-primary) 40%, transparent);
+}
+
+.ezw-wikilink:hover {
+  border-bottom-color: var(--color-primary);
+}
+
+/* An unresolved link is styled as visibly broken rather than left to look like
+   working text — a dangling reference is a content bug worth surfacing. */
+.ezw-broken-link {
+  font-style: normal;
+  color: #b91c1c;
+  border-bottom: 1px dashed currentColor;
+  cursor: help;
+}
+
+html.dark .ezw-broken-link {
+  color: #f87171;
+}
+
+/* ------------------------------------------------------------- anchors ---- */
+
+/* The header is sticky, so an anchored heading would otherwise land underneath
+   it. */
+.ezw-prose :where(h1, h2, h3, h4, h5, h6)[id] {
+  scroll-margin-top: 6rem;
+}
+
+/* -------------------------------------------------------------- images ---- */
+
+.ezw-img {
+  max-width: 100%;
+  height: auto;
+  border-radius: 0.5rem;
+}
+
+/* --------------------------------------------------------------- misc ----- */
+
+.ezw-prose table {
+  display: block;
+  overflow-x: auto;
+  white-space: nowrap;
+}
+
+@media (min-width: 640px) {
+  .ezw-prose table {
+    display: table;
+    white-space: normal;
+  }
+}

package/template/styles/theme.css

@@ -0,0 +1,65 @@
+/**
+ * Theme CSS Custom Properties
+ * Notion/Obsidian-inspired color palette with light and dark mode support
+ */
+
+:root {
+  /* Primary colors - Blue accent for links and interactive elements */
+  --color-primary: #2563eb;
+  --color-primary-hover: #1d4ed8;
+
+  /* Secondary colors - Purple accent for highlights */
+  --color-secondary: #7c3aed;
+  --color-secondary-hover: #6d28d9;
+
+  /* Background colors */
+  --color-background: #ffffff;
+
+  /* Text colors */
+  --color-text: #1f2937;
+  --color-text-muted: #6b7280;
+
+  /* Sidebar colors */
+  --color-sidebar-bg: #f9fafb;
+  --color-sidebar-text: #374151;
+  --color-sidebar-hover: #f3f4f6;
+  --color-sidebar-active: #e5e7eb;
+
+  /* Code block colors */
+  --color-code-bg: #f3f4f6;
+  --color-code-text: #1f2937;
+
+  /* Border colors */
+  --color-border: #e5e7eb;
+}
+
+/* Dark mode color scheme - using .dark class */
+.dark {
+  /* Primary colors - Lighter blue for better contrast */
+  --color-primary: #3b82f6;
+  --color-primary-hover: #60a5fa;
+
+  /* Secondary colors - Lighter purple */
+  --color-secondary: #8b5cf6;
+  --color-secondary-hover: #a78bfa;
+
+  /* Background colors */
+  --color-background: #111827;
+
+  /* Text colors */
+  --color-text: #f9fafb;
+  --color-text-muted: #9ca3af;
+
+  /* Sidebar colors */
+  --color-sidebar-bg: #1f2937;
+  --color-sidebar-text: #e5e7eb;
+  --color-sidebar-hover: #374151;
+  --color-sidebar-active: #4b5563;
+
+  /* Code block colors */
+  --color-code-bg: #374151;
+  --color-code-text: #f9fafb;
+
+  /* Border colors */
+  --color-border: #374151;
+}