feat(pages): add Docs page with search, markdown rendering, and i18n support

[hezheng-max]

• Add DocsPage with full-text search modal and keyboard shortcuts (⌘K)
• Add MarkdownRenderer with DOMPurify sanitization and mermaid support
• Add bilingual docs content (en/zh) for all sections
• Add shared headingId utility with deduplication for consistent TOC anchors
• Add search keyboard hints with i18n support
• Update Navbar with Docs navigation link
• Configure webpack for markdown imports
• Extract parseFrontmatter helper to eliminate DRY violation
• Move copy button and toast inline styles to CSS classes
• Adjust HeroSection terminal section height and bottom padding

[github-actions]

🔍 OpenCodeReview found 9 issue(s) in this PR.

• ✅ 9 posted as inline comment(s)
• 📝 0 posted as summary

⚠️ 1 warning(s) occurred during review.

[github-actions]

Potential type conflict: dompurify v3.x ships its own built-in TypeScript type definitions. Installing @types/dompurify alongside it may cause duplicate or conflicting type declarations. Consider removing @types/dompurify from devDependencies since the bundled types in dompurify@^3.4.11 should be sufficient.

[github-actions]

Minor inconsistency: The navbar uses 'Quick Start' (with a space) for navbar.quickstart, but here it's 'QuickStart' (no space). Consider using 'Quick Start' for consistency across the UI.

Suggestion:

Suggested change

	'docs.sidebar.quickstart': 'QuickStart',
	'docs.sidebar.quickstart': 'Quick Start',

[github-actions]

Duplicate Code / DRY Violation: The frontmatter detection logic here (startsWith('---') + indexOf('---', 3)) is duplicated from stripFrontmatter. If the frontmatter format changes or a bug is found in the parsing, both locations need to be updated consistently.

Consider extracting a shared helper like parseFrontmatter(raw: string): { frontmatter: string; body: string } | null and using it in both stripFrontmatter and getDocTitle. For example:

function parseFrontmatter(md: string): { frontmatter: string; body: string } | null {
  if (!md.startsWith('---')) return null;
  const end = md.indexOf('---', 3);
  if (end === -1) return null;
  return {
    frontmatter: md.slice(3, end),
    body: md.slice(end + 3).trim(),
  };
}

function stripFrontmatter(md: string): string {
  return parseFrontmatter(md)?.body ?? md;
}

export function getDocTitle(slug: DocSlug, language: string): string {
  const parsed = parseFrontmatter(getRawContent(slug, language));
  if (parsed) {
    const match = parsed.frontmatter.match(/title:\s*(.+)/);
    if (match) return match[1].trim();
  }
  return slug;
}

[github-actions]

Dead Code: useId is imported but never used anywhere in this component. Remove it from the import statement.

Suggestion:

Suggested change

	import React, { useMemo, useEffect, useRef, useState, useCallback, useId } from 'react';
	import React, { useMemo, useEffect, useRef, useState, useCallback } from 'react';

[github-actions]

Async Handling Issue: The renderPromises array of promises is created but never awaited or handled with Promise.all. This means:

1. The cleanup function (cancelled = true) executes synchronously before any mermaid.render() calls resolve, so the cancelled flag check inside the async callbacks may not work reliably if the effect re-runs quickly.
2. If mermaid.render() throws outside the try/catch (e.g., during DOM insertion), it would become an unhandled promise rejection.
3. There's no way to properly cancel in-flight renders on cleanup.

Use Promise.all and handle errors at the aggregate level, or at minimum ensure proper cleanup coordination.

Suggestion:

Suggested change

	const renderPromises = Array.from(mermaidBlocks).map(async (block) => {
	const pre = block.parentElement;
	if (!pre) return;
	const code = block.textContent || '';
	try {
	const id = `mermaid-diagram-${crypto.randomUUID()}`;
	const { svg } = await mermaid.render(id, code);
	if (cancelled) return;
	// Replace the <pre> with rendered SVG
	const wrapper = document.createElement('div');
	wrapper.className = 'mermaid-rendered';
	wrapper.innerHTML = svg;
	pre.replaceWith(wrapper);
	} catch (e) {
	if (cancelled) return;
	// If rendering fails, show the code block normally
	(block as HTMLElement).style.display = 'block';
	console.warn('[Mermaid] render failed:', e);
	}
	});
	return () => { cancelled = true; };
	Promise.all(Array.from(mermaidBlocks).map(async (block) => {
	const pre = block.parentElement;
	if (!pre) return;
	const code = block.textContent || '';
	try {
	const id = `mermaid-diagram-${crypto.randomUUID()}`;
	const { svg } = await mermaid.render(id, code);
	if (cancelled) return;
	// Replace the <pre> with rendered SVG
	const wrapper = document.createElement('div');
	wrapper.className = 'mermaid-rendered';
	wrapper.innerHTML = svg;
	pre.replaceWith(wrapper);
	} catch (e) {
	if (cancelled) return;
	// If rendering fails, show the code block normally
	(block as HTMLElement).style.display = 'block';
	console.warn('[Mermaid] render failed:', e);
	}
	})).catch((e) => {
	console.warn('[Mermaid] unexpected render error:', e);
	});
	return () => { cancelled = true; };

[github-actions]

Inline Styles: The copy button uses extensive inline styles via cssText, but the parent <pre> element already has styling defined in docs-markdown.css (with display: flex; justify-content: space-between; align-items: center). These static styles should be moved to a CSS class in docs-markdown.css for consistency and maintainability. Only truly dynamic styles should remain inline.

[github-actions]

Inline Styles: The toast portal div uses extensive inline styles that are entirely static. These should be extracted into a CSS class (e.g., .copy-toast) in docs-markdown.css. The only dynamic property is opacity, which can be toggled via a class modifier (e.g., .copy-toast.visible). This improves maintainability and makes theme updates easier.

[github-actions]

The align-self: stretch property only takes effect when the parent element is a flex or grid container. Since .docs-markdown does not have display: flex or display: grid, this property has no effect and can be removed to avoid confusion.

[github-actions]

Potential duplicate ID issue: If a markdown document contains two headings with the same text (e.g., two ## Examples sections), this function will generate identical IDs for both. This results in:

1. Invalid HTML (duplicate id attributes)
2. Broken anchor navigation — clicking a TOC entry may scroll to the wrong heading
3. IntersectionObserver tracking incorrect active heading

Consider adding deduplication logic by appending a suffix (e.g., -1, -2) when an ID has already been generated. Since this function is used in both extractHeadings and MarkdownRenderer, you'd need a stateful approach or pass a counter/map to ensure consistency between the two call sites.