@x-wave/blog 1.0.5 → 1.0.6

package/README.md

@@ -390,7 +390,7 @@ interface BlogConfig {
   supportedLanguages: readonly string[]           // e.g. ['en', 'es', 'zh']
   navigationData: NavigationEntry[]               // Menu structure
   basePath?: string                               // Base path for all routes (default: '')
-  header?: {
+  header?: {                                       // Optional: omit to hide built-in header
     navLinks?: HeaderLink[]                       // Top-level nav links
     dropdownItems?: HeaderDropdownItem[]          // Support dropdown menu
   }
@@ -399,6 +399,68 @@ interface BlogConfig {
 
 **Key properties:**
 
+- **`header`**: Optional. If omitted entirely, the built-in header component will not be rendered. Use this when you want to implement a custom header.
+
+### Custom headers
+
+If you need a custom header instead of the built-in one, simply omit the `header` config and use the provided hooks:
+
+```tsx
+import { useTheme, useSearchModal } from '@x-wave/blog'
+import { Moon, Sun, MagnifyingGlass } from '@phosphor-icons/react'
+
+function CustomHeader() {
+  const { theme, setTheme } = useTheme()
+  const { openSearchModal } = useSearchModal()
+
+  return (
+    <header>
+      <h1>My Custom Header</h1>
+      
+      {/* Theme toggle button */}
+      <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
+        {theme === 'dark' ? <Sun /> : <Moon />}
+      </button>
+      
+      {/* Search button */}
+      <button onClick={openSearchModal}>
+        <MagnifyingGlass />
+      </button>
+    </header>
+  )
+}
+
+function App() {
+  return (
+    <BlogProvider
+      config={{
+        title: 'My Docs',
+        supportedLanguages: ['en'],
+        navigationData: NAVIGATION_DATA,
+        // No header config = no built-in header
+      }}
+      blog={blog}
+    >
+      <CustomHeader />
+      <Router>
+        <Routes>
+          <Route path="/:language/*" element={<DocumentationRoutes />} />
+        </Routes>
+      </Router>
+    </BlogProvider>
+  )
+}
+```
+
+**Available hooks:**
+
+- **`useTheme()`**: Returns `{ theme, setTheme, effectiveTheme }` for managing light/dark/system theme
+- **`useSearchModal()`**: Returns `{ openSearchModal, closeSearchModal }` for controlling the search modal
+
+These are the exact functions used by the built-in header, so you get the same functionality with full customization.
+
+**Key properties (continued):**
+
 | Property | Type | Required | Description |
 |---|---|---|---|
 | `title` | `string` | Yes | Site title displayed in header and sidebar |