create-eziwiki 0.1.0

package/template/lib/payload/types.ts

@@ -0,0 +1,105 @@
+import type { UrlStrategy } from '../navigation/url';
+
+/**
+ * Navigation item in the sidebar hierarchy
+ */
+export interface NavigationItem {
+  /** Display name of the navigation item */
+  name: string;
+  /** Optional path to content file (without .md extension) */
+  path?: string;
+  /** Optional nested navigation items */
+  children?: NavigationItem[];
+  /** Optional icon identifier */
+  icon?: string;
+  /** Optional background color for the navigation item */
+  color?: string;
+  /** Hide this item from navigation (accessible only via direct URL) */
+  hidden?: boolean;
+}
+
+/**
+ * Global site configuration
+ */
+export interface GlobalConfig {
+  /** Site title displayed in browser tab */
+  title: string;
+  /** Site description for SEO */
+  description: string;
+  /** Path to favicon */
+  favicon?: string;
+  /** Base URL for the site */
+  baseUrl?: string;
+  /**
+   * How content paths are expressed in URLs.
+   *
+   * `path` produces readable, indexable URLs mirroring the content tree.
+   * `hash` produces opaque hashes that conceal the structure at the cost of
+   * SEO and shareability. Defaults to `path`.
+   */
+  urlStrategy?: UrlStrategy;
+  /**
+   * Discover documents under `content/` and add any that navigation does not
+   * already reference. Enabled by default, so a new Markdown file appears in
+   * the sidebar without touching this config.
+   */
+  autoNavigation?: boolean;
+  /** SEO metadata */
+  seo?: {
+    openGraph?: {
+      title?: string;
+      description?: string;
+      images?: Array<{
+        url: string;
+        width?: number;
+        height?: number;
+        alt?: string;
+      }>;
+    };
+    twitter?: {
+      card?: 'summary' | 'summary_large_image' | 'app' | 'player';
+      site?: string;
+      creator?: string;
+      title?: string;
+      description?: string;
+      images?: string[];
+    };
+  };
+}
+
+/**
+ * Theme color configuration
+ */
+export interface ThemeConfig {
+  /** Primary brand color */
+  primary: string;
+  /** Secondary accent color */
+  secondary: string;
+  /** Background color */
+  background: string;
+  /** Text color */
+  text: string;
+  /** Sidebar background color */
+  sidebarBg: string;
+  /** Code block background */
+  codeBg: string;
+}
+
+/**
+ * Complete payload structure
+ */
+export interface Payload {
+  /** Global site configuration */
+  global: GlobalConfig;
+  /**
+   * Curated navigation structure.
+   *
+   * Optional: when omitted, navigation is derived entirely from the content
+   * directory. When present, these entries control naming and ordering, and
+   * undeclared documents are appended automatically unless
+   * {@link GlobalConfig.autoNavigation} is disabled.
+   */
+  navigation?: NavigationItem[];
+  /** Theme customization */
+  theme?: Partial<ThemeConfig>;
+}

package/template/lib/payload/validator.ts

@@ -0,0 +1,56 @@
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { payloadSchema } from './schema';
+
+/**
+ * Result of payload validation
+ */
+export interface ValidationResult {
+  /** Whether the payload is valid */
+  valid: boolean;
+  /** Array of error messages if validation failed */
+  errors?: string[];
+}
+
+/**
+ * Validates payload configuration against JSON Schema
+ *
+ * This function ensures that the user-provided payload matches the required
+ * structure for the landing page generator. It validates:
+ * - Required fields (global.title, global.description, navigation)
+ * - Data types and formats (URLs, hex colors)
+ * - Navigation structure and nesting
+ * - Theme color values
+ *
+ * @param payload - User-provided payload object to validate
+ * @returns Validation result with detailed error messages if invalid
+ *
+ * @example
+ * ```typescript
+ * import { validatePayload } from './lib/payload/validator';
+ * import payload from './payload/config';
+ *
+ * const result = validatePayload(payload);
+ * if (!result.valid) {
+ *   console.error('Payload validation failed:');
+ *   result.errors?.forEach(err => console.error(`  - ${err}`));
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export function validatePayload(payload: unknown): ValidationResult {
+  const ajv = new Ajv({ allErrors: true });
+  addFormats(ajv);
+
+  const validate = ajv.compile(payloadSchema);
+  const valid = validate(payload);
+
+  if (!valid && validate.errors) {
+    return {
+      valid: false,
+      errors: validate.errors.map((err) => `${err.instancePath || 'root'} ${err.message}`),
+    };
+  }
+
+  return { valid: true };
+}

package/template/lib/search/build.ts

@@ -0,0 +1,204 @@
+import { getContentRegistry } from '../content/registry';
+import { renderDoc } from '../markdown/render';
+import { docPathToUrl } from '../navigation/url';
+import { getSite } from '../site';
+import { SEARCH_INDEX_VERSION, type SearchDoc, type SearchIndex } from './types';
+
+/**
+ * Builds the search index from the content registry.
+ *
+ * Documents are split into one entry per section so a hit can link directly to
+ * the relevant heading rather than dropping the reader at the top of a long
+ * page. Server-only; the output is written to `public/` before the build.
+ */
+
+/** Heading depths that start a new indexed section. */
+const SECTION_DEPTHS = new Set([2, 3, 4]);
+
+/** Characters of body text kept per entry, to bound the index size. */
+const MAX_BODY_CHARS = 1200;
+
+/**
+ * Converts Markdown to plain text suitable for indexing and previews.
+ *
+ * Code content is deliberately kept — searching for an API name or a flag is
+ * one of the main things people do in developer documentation — but the fence
+ * markers, link targets, and emphasis characters are stripped so they cannot
+ * pollute matches.
+ *
+ * @param markdown - Markdown source for a document or section
+ * @returns Collapsed plain text
+ *
+ * @example
+ * ```typescript
+ * markdownToText('See [the guide](/guides/x) for `--flag`.');
+ * // 'See the guide for --flag.'
+ * ```
+ */
+export function markdownToText(markdown: string): string {
+  return (
+    markdown
+      // Fenced code: drop the fence lines, keep the code itself.
+      .replace(/^ {0,3}(`{3,}|~{3,}).*$/gm, '')
+      // HTML tags and comments.
+      .replace(/<!--[\s\S]*?-->/g, ' ')
+      .replace(/<[^>]+>/g, ' ')
+      // Images before links, so alt text survives and the src does not.
+      .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+      .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+      // Reference-style links and bare autolinks.
+      .replace(/\[([^\]]*)\]\[[^\]]*\]/g, '$1')
+      .replace(/<(https?:\/\/[^>]+)>/g, '$1')
+      // Heading markers. Depths 2-4 start their own section, but an h1 or an h5
+      // stays inline and would otherwise leave a stray '#' in the indexed text.
+      .replace(/^ {0,3}#{1,6} +/gm, '')
+      // Emphasis, inline code, blockquote and list markers, table pipes.
+      .replace(/[*_~`]+/g, '')
+      .replace(/^ {0,3}>+ ?/gm, '')
+      .replace(/^ {0,3}([-*+]|\d+\.) +/gm, '')
+      .replace(/^ {0,3}\|/gm, ' ')
+      .replace(/\|/g, ' ')
+      // Horizontal rules and table delimiter rows.
+      .replace(/^ {0,3}([-*_])(\s*\1){2,}\s*$/gm, ' ')
+      .replace(/^[\s:|-]+$/gm, ' ')
+      .replace(/\s+/g, ' ')
+      .trim()
+  );
+}
+
+/** A slice of a document between two headings. */
+interface Section {
+  /** Heading text, absent for the text preceding the first heading */
+  heading?: string;
+  /** Raw Markdown of the section body */
+  markdown: string;
+}
+
+/**
+ * Splits Markdown into sections at ATX headings of indexable depth.
+ *
+ * Fence state is tracked so that a `#` comment inside a code block is not
+ * mistaken for a heading — which would otherwise split a document at arbitrary
+ * points and misalign sections from their anchors.
+ *
+ * @param markdown - Markdown source with frontmatter removed
+ * @returns Sections in document order, the first being any preamble
+ */
+export function splitSections(markdown: string): Section[] {
+  const sections: Section[] = [{ markdown: '' }];
+  let fence: string | null = null;
+
+  for (const line of markdown.split('\n')) {
+    const fenceMatch = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+
+    if (fenceMatch) {
+      const marker = fenceMatch[1][0];
+      if (fence === null) {
+        fence = marker;
+      } else if (fence === marker) {
+        fence = null;
+      }
+    }
+
+    const headingMatch = fence === null ? /^ {0,3}(#{1,6}) +(.*?)#*\s*$/.exec(line) : null;
+
+    if (headingMatch && SECTION_DEPTHS.has(headingMatch[1].length)) {
+      sections.push({ heading: headingMatch[2].trim(), markdown: '' });
+      continue;
+    }
+
+    sections[sections.length - 1].markdown += `${line}\n`;
+  }
+
+  return sections;
+}
+
+/**
+ * Pairs each section with the anchor id of its heading.
+ *
+ * Sections come from the Markdown source and anchors from the rendered HTML, so
+ * the two are ordered alike but not guaranteed to correspond one-to-one — a
+ * heading written as raw HTML, for instance, appears in the render but not in
+ * the source scan. Matching on heading text and only advancing on a hit keeps
+ * one such discrepancy from shifting every subsequent anchor, which would
+ * silently point search results at the wrong sections.
+ *
+ * @param sections - Sections after the preamble, in document order
+ * @param anchors - Rendered headings, in document order
+ * @returns Anchor id per section, or undefined where none could be matched
+ */
+function matchAnchors(
+  sections: Section[],
+  anchors: Array<{ id: string; text: string }>,
+): Array<string | undefined> {
+  const normalize = (value: string) => markdownToText(value).toLowerCase();
+  let cursor = 0;
+
+  return sections.map((section) => {
+    const target = normalize(section.heading ?? '');
+
+    for (let i = cursor; i < anchors.length; i++) {
+      if (normalize(anchors[i].text) === target) {
+        cursor = i + 1;
+        return anchors[i].id;
+      }
+    }
+
+    return undefined;
+  });
+}
+
+/**
+ * Builds the search index for every published document.
+ *
+ * Hidden documents are excluded: they are unlisted by intent, and surfacing
+ * them in search would defeat that.
+ *
+ * @returns The index, ready to serialise
+ */
+export async function buildSearchIndex(): Promise<SearchIndex> {
+  const { docs } = getContentRegistry();
+  const { urlMap, hiddenPaths } = getSite();
+  const entries: SearchDoc[] = [];
+
+  for (const doc of docs) {
+    if (hiddenPaths.has(doc.path)) continue;
+
+    const url = docPathToUrl(urlMap, doc.path);
+    if (!url) continue;
+
+    const href = `/${url}`;
+    const rendered = await renderDoc(doc.path);
+
+    // Anchors come from the rendered document, so they are exactly the ids
+    // rehype-slug produced and the links will resolve.
+    const [preamble, ...sections] = splitSections(doc.content);
+    const anchors = matchAnchors(sections, rendered?.headings ?? []);
+
+    entries.push({
+      id: doc.path,
+      path: doc.path,
+      url: href,
+      title: doc.title,
+      description: doc.description,
+      body: markdownToText(preamble.markdown).slice(0, MAX_BODY_CHARS),
+    });
+
+    sections.forEach((section, index) => {
+      const anchor = anchors[index];
+
+      entries.push({
+        id: anchor ? `${doc.path}#${anchor}` : `${doc.path}#${index}`,
+        path: doc.path,
+        url: anchor ? `${href}#${anchor}` : href,
+        title: doc.title,
+        section: section.heading,
+        anchor,
+        description: doc.description,
+        body: markdownToText(section.markdown).slice(0, MAX_BODY_CHARS),
+      });
+    });
+  }
+
+  return { version: SEARCH_INDEX_VERSION, docs: entries };
+}

package/template/lib/search/client.ts

@@ -0,0 +1,190 @@
+import type MiniSearch from 'minisearch';
+import { tokenize } from './tokenizer';
+import { SEARCH_INDEX_PATH, type SearchDoc, type SearchIndex } from './types';
+
+/**
+ * Browser-side search.
+ *
+ * The index is fetched and built on first use rather than at page load, so a
+ * reader who never opens search never pays for it.
+ */
+
+/** A search hit, with the excerpt to display. */
+export interface SearchResult {
+  /** Stable identifier of the matched entry */
+  id: string;
+  /** Href to navigate to, including the section anchor when there is one */
+  url: string;
+  /** Page title */
+  title: string;
+  /** Section heading, when the hit is a section rather than a whole page */
+  section?: string;
+  /** Body excerpt centred on the match */
+  excerpt: string;
+}
+
+/** Characters of context shown around a match. */
+const EXCERPT_CHARS = 160;
+
+/** Maximum hits returned to the UI. */
+const MAX_RESULTS = 20;
+
+/**
+ * Field weights.
+ *
+ * A query naming a section should surface that section above pages that merely
+ * mention the words in passing, so headings outrank body text substantially.
+ */
+const BOOST = { title: 4, section: 3, description: 2, body: 1 };
+
+/**
+ * Extra weight given to whole-page entries over the sections within them.
+ *
+ * A section entry carries its page's title as well as its own heading, so it
+ * matches both boosted fields and would otherwise always outrank the page it
+ * belongs to. Searching "dark mode" should land on the Dark Mode page, not on
+ * its "Disable Dark Mode" subsection.
+ */
+const PAGE_BOOST = 1.6;
+
+/**
+ * Scales a hit's score according to whether it is a page or a section.
+ *
+ * @param _id - Document id, unused
+ * @param _term - Matched term, unused
+ * @param stored - The fields stored alongside the document
+ * @returns Multiplier applied to the hit's score
+ */
+function boostPages(_id: string, _term: string, stored?: Record<string, unknown>): number {
+  return stored?.section ? 1 : PAGE_BOOST;
+}
+
+let loading: Promise<MiniSearch<SearchDoc>> | null = null;
+
+/**
+ * Builds the MiniSearch instance from index data.
+ *
+ * The library is imported dynamically so it lands in its own chunk, fetched
+ * alongside the index on first search rather than on every page load.
+ *
+ * @param index - Parsed index file
+ * @returns A populated searcher
+ */
+export async function createSearcher(index: SearchIndex): Promise<MiniSearch<SearchDoc>> {
+  const { default: MiniSearchCtor } = await import('minisearch');
+
+  const searcher = new MiniSearchCtor<SearchDoc>({
+    idField: 'id',
+    fields: ['title', 'section', 'description', 'body'],
+    storeFields: ['title', 'section', 'url', 'body'],
+    // The same tokeniser must run over queries and documents, or a CJK query
+    // would be split differently from the terms stored for a document.
+    tokenize,
+  });
+
+  searcher.addAll(index.docs);
+  return searcher;
+}
+
+/**
+ * Fetches and prepares the search index, once per page load.
+ *
+ * Concurrent callers share a single request: opening the dialog, typing
+ * immediately, and a keyboard shortcut firing can all land within the same tick.
+ *
+ * @returns The ready searcher
+ * @throws Error if the index cannot be fetched or is of an unexpected version
+ */
+export function loadSearcher(): Promise<MiniSearch<SearchDoc>> {
+  loading ??= (async () => {
+    const basePath = process.env.NEXT_PUBLIC_BASE_PATH || '';
+    const response = await fetch(`${basePath}${SEARCH_INDEX_PATH}`);
+
+    if (!response.ok) {
+      throw new Error(`Search index unavailable (${response.status})`);
+    }
+
+    return await createSearcher((await response.json()) as SearchIndex);
+  })().catch((error) => {
+    // Allow a later attempt to retry rather than caching the failure forever.
+    loading = null;
+    throw error;
+  });
+
+  return loading;
+}
+
+/**
+ * Builds an excerpt centred on the first matched term.
+ *
+ * Showing the start of a long section is rarely useful — the reason a result
+ * matched is usually somewhere in the middle.
+ *
+ * @param body - Full body text of the entry
+ * @param terms - Terms MiniSearch matched
+ * @returns A trimmed excerpt, with ellipses where text was cut
+ */
+export function buildExcerpt(body: string, terms: string[]): string {
+  if (!body) return '';
+
+  const lower = body.toLowerCase();
+  let at = -1;
+
+  for (const term of terms) {
+    const found = lower.indexOf(term.toLowerCase());
+    if (found !== -1 && (at === -1 || found < at)) at = found;
+  }
+
+  if (at === -1 || body.length <= EXCERPT_CHARS) {
+    return body.slice(0, EXCERPT_CHARS) + (body.length > EXCERPT_CHARS ? '…' : '');
+  }
+
+  const start = Math.max(0, at - EXCERPT_CHARS / 3);
+  const end = Math.min(body.length, start + EXCERPT_CHARS);
+
+  return (start > 0 ? '…' : '') + body.slice(start, end).trim() + (end < body.length ? '…' : '');
+}
+
+/**
+ * Runs a query against the loaded index.
+ *
+ * @param query - Raw user input
+ * @returns Ranked results, empty for a blank query
+ *
+ * @example
+ * ```typescript
+ * const results = await search('dark mode');
+ * results[0].url; // '/features/dark-mode'
+ * ```
+ */
+export async function search(query: string): Promise<SearchResult[]> {
+  const trimmed = query.trim();
+  if (!trimmed) return [];
+
+  const searcher = await loadSearcher();
+
+  const options = {
+    boost: BOOST,
+    prefix: true,
+    // Fuzziness is proportional to term length, so short terms stay exact and
+    // long ones tolerate a typo or two.
+    fuzzy: 0.2,
+    boostDocument: boostPages,
+  };
+
+  const hits = searcher.search(trimmed, { ...options, combineWith: 'AND' as const });
+
+  // An AND query that matches nothing is usually one stray word away from a
+  // useful result, so fall back to OR rather than showing an empty list.
+  const results = hits.length
+    ? hits
+    : searcher.search(trimmed, { ...options, combineWith: 'OR' as const });
+
+  return results.slice(0, MAX_RESULTS).map((hit) => ({
+    id: String(hit.id),
+    url: hit.url as string,
+    title: hit.title as string,
+    section: hit.section as string | undefined,
+    excerpt: buildExcerpt((hit.body as string) ?? '', hit.terms),
+  }));
+}

package/template/lib/search/tokenizer.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { bigrams, tokenize } from './tokenizer';
+
+describe('bigrams', () => {
+  it('produces overlapping character pairs', () => {
+    expect(bigrams('위키문서')).toEqual(['위키', '키문', '문서']);
+  });
+
+  it('keeps a single character as-is', () => {
+    expect(bigrams('한')).toEqual(['한']);
+  });
+
+  it('returns nothing for empty input', () => {
+    expect(bigrams('')).toEqual([]);
+  });
+});
+
+describe('tokenize', () => {
+  it('splits Latin text on non-word characters and lower-cases it', () => {
+    expect(tokenize('Quick Start Guide')).toEqual(['quick', 'start', 'guide']);
+    expect(tokenize('dark-mode, enabled!')).toEqual(['dark', 'mode', 'enabled']);
+  });
+
+  it('keeps digits as terms', () => {
+    expect(tokenize('Next.js 14')).toEqual(['next', 'js', '14']);
+  });
+
+  it('expands CJK runs into bigrams alongside the whole term', () => {
+    expect(tokenize('시작하기')).toEqual(['시작하기', '시작', '작하', '하기']);
+  });
+
+  it('handles mixed scripts in one string', () => {
+    expect(tokenize('Quick Start 시작하기')).toEqual([
+      'quick',
+      'start',
+      '시작하기',
+      '시작',
+      '작하',
+      '하기',
+    ]);
+  });
+
+  it('does not bigram a term that merely contains CJK', () => {
+    // Mixed-script terms are left whole; splitting them would produce bigrams
+    // that straddle the script boundary and match nothing.
+    expect(tokenize('API키')).toEqual(['api키']);
+  });
+
+  it('lets a CJK query match the terms stored for a document', () => {
+    const indexed = new Set(tokenize('한국어 위키문서를 만들어 봅시다'));
+    const query = tokenize('위키');
+
+    expect(query.every((term) => indexed.has(term))).toBe(true);
+  });
+
+  it('returns nothing for whitespace or punctuation alone', () => {
+    expect(tokenize('   ')).toEqual([]);
+    expect(tokenize('--- ...')).toEqual([]);
+  });
+});

package/template/lib/search/tokenizer.ts

@@ -0,0 +1,83 @@
+/**
+ * Tokenisation shared by the index builder and the browser-side searcher.
+ *
+ * Both sides must tokenise identically or a query will never match the terms
+ * stored for a document.
+ */
+
+/** Latin, digit, and other non-CJK word characters. */
+const WORD = /[^\p{L}\p{N}]+/u;
+
+/**
+ * Characters that CJK scripts write without spaces between words.
+ * Covers Hangul syllables and jamo, CJK ideographs, and kana.
+ */
+const CJK = /[ᄀ-ᇿ぀-ヿ㄰-㆏㐀-䶿一-鿿가-힯豈-﫿]/;
+
+/**
+ * Whether a string consists entirely of CJK characters.
+ */
+function isCjk(term: string): boolean {
+  return [...term].every((char) => CJK.test(char));
+}
+
+/**
+ * Splits a CJK run into overlapping character bigrams.
+ *
+ * Korean, Chinese, and Japanese are written without spaces, so whitespace
+ * tokenisation yields one enormous token per phrase and a search for a word
+ * inside it never matches. Indexing bigrams — 위키문서 becomes 위키, 키문, 문서 —
+ * makes substring queries work without a morphological analyser. A single
+ * character is kept as-is so one-character queries still resolve.
+ *
+ * @param term - A run of CJK characters
+ * @returns The bigrams covering that run
+ *
+ * @example
+ * ```typescript
+ * bigrams('위키문서'); // ['위키', '키문', '문서']
+ * bigrams('한'); // ['한']
+ * ```
+ */
+export function bigrams(term: string): string[] {
+  const chars = [...term];
+  if (chars.length < 2) return chars;
+
+  const result: string[] = [];
+  for (let i = 0; i < chars.length - 1; i++) {
+    result.push(chars[i] + chars[i + 1]);
+  }
+  return result;
+}
+
+/**
+ * Splits text into searchable terms.
+ *
+ * Latin text is split on non-word characters; CJK runs are additionally
+ * expanded into bigrams. The whole CJK term is kept alongside its bigrams so
+ * that an exact phrase still scores highest.
+ *
+ * @param text - Text to tokenise
+ * @returns Lower-cased terms
+ *
+ * @example
+ * ```typescript
+ * tokenize('Quick Start 시작하기');
+ * // ['quick', 'start', '시작하기', '시작', '작하', '하기']
+ * ```
+ */
+export function tokenize(text: string): string[] {
+  const raw = text.split(WORD).filter(Boolean);
+  const terms: string[] = [];
+
+  for (const term of raw) {
+    const lower = term.toLowerCase();
+    terms.push(lower);
+
+    if (isCjk(lower) && lower.length > 1) {
+      terms.push(...bigrams(lower));
+    }
+  }
+
+  return terms;
+}