@x-wave/blog 0.1.0 → 1.0.2

package/README.md

@@ -140,25 +140,13 @@ export const blog = createBlogUtils(mdxFiles)
 
 ```tsx
 // src/App.tsx
-import { BlogProvider, ContentPage, DocumentationLayout } from '@x-wave/blog'
-import { Navigate, Route, HashRouter as Router, Routes, useParams } from 'react-router-dom'
+import { BlogProvider, DocumentationRoutes } from '@x-wave/blog'
+import { Navigate, Route, HashRouter as Router, Routes } from 'react-router-dom'
 import { blog } from './utils'
 import { NAVIGATION_DATA } from './navigation'
 
 const SUPPORTED_LANGUAGES = ['en', 'es', 'zh'] as const
 
-function DocumentationWrapper() {
-  const { language } = useParams<{ language: string }>()
-  return (
-    <DocumentationLayout>
-      <Routes>
-        <Route path="/:slug" element={<ContentPage language={language!} />} />
-        <Route path="/" element={<Navigate to={`/${language}/welcome`} replace />} />
-      </Routes>
-    </DocumentationLayout>
-  )
-}
-
 export default function App() {
   return (
     <BlogProvider
@@ -180,7 +168,7 @@ export default function App() {
     >
       <Router>
         <Routes>
-          <Route path="/:language/*" element={<DocumentationWrapper />} />
+          <Route path="/:language/*" element={<DocumentationRoutes />} />
           <Route path="/" element={<Navigate to="/en/welcome" replace />} />
         </Routes>
       </Router>
@@ -189,6 +177,41 @@ export default function App() {
 }
 ```
 
+> **Router flexibility**: Swap `HashRouter` for `BrowserRouter` to use cleaner URLs without the hash (`/en/welcome` vs `/#/en/welcome`). BrowserRouter requires server configuration to fallback to `index.html` for all routes.
+
+### Using a base path
+
+To mount documentation under a subpath (e.g., `/blog` or `/docs`), set the `basePath` config option:
+
+```tsx
+export default function App() {
+  return (
+    <BlogProvider
+      config={{
+        title: 'My Documentation',
+        basePath: '/blog',  // All routes will be prefixed with /blog
+        supportedLanguages: SUPPORTED_LANGUAGES,
+        navigationData: NAVIGATION_DATA,
+      }}
+      blog={blog}
+    >
+      <Router>
+        <Routes>
+          {/* Routes now mounted under /blog */}
+          <Route path="/blog/:language/*" element={<DocumentationRoutes />} />
+          <Route path="/blog" element={<Navigate to="/blog/en/welcome" replace />} />
+          
+          {/* Your other app routes */}
+          <Route path="/" element={<HomePage />} />
+        </Routes>
+      </Router>
+    </BlogProvider>
+  )
+}
+```
+
+This ensures internal navigation (search, tags, language switching) uses the correct base path.
+
 ## Writing content
 
 ### File naming
@@ -254,6 +277,7 @@ All components are exported from `@x-wave/blog`:
 ```ts
 import { 
   BlogProvider, 
+  DocumentationRoutes,
   DocumentationLayout, 
   ContentPage,
   Header,
@@ -266,6 +290,7 @@ import {
 | Component | Purpose |
 |---|---|
 | `BlogProvider` | Root context wrapper (required) |
+| `DocumentationRoutes` | Pre-configured Routes for documentation pages (recommended) |
 | `DocumentationLayout` | Page layout: header + sidebar + content |
 | `ContentPage` | Loads and renders MDX pages |
 | `Header` | Top navigation bar |
@@ -362,6 +387,7 @@ interface BlogConfig {
   logo?: React.ComponentType<{ className?: string }>  // Optional logo
   supportedLanguages: readonly string[]           // e.g. ['en', 'es', 'zh']
   navigationData: NavigationEntry[]               // Menu structure
+  basePath?: string                               // Base path for all routes (default: '')
   header?: {
     navLinks?: HeaderLink[]                       // Top-level nav links
     dropdownItems?: HeaderDropdownItem[]          // Support dropdown menu
@@ -369,6 +395,17 @@ interface BlogConfig {
 }
 ```
 
+**Key properties:**
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `title` | `string` | Yes | Site title displayed in header and sidebar |
+| `supportedLanguages` | `string[]` | Yes | Array of language codes (e.g., `['en', 'es', 'zh']`) |
+| `navigationData` | `NavigationEntry[]` | Yes | Sidebar navigation structure |
+| `basePath` | `string` | No | Base path prefix for all routes. Use when mounting docs under a subpath like `/blog` or `/docs`. Default: `''` (root) |
+| `logo` | `React.ComponentType` | No | SVG component for site logo |
+| `header` | `object` | No | Header configuration with nav links and dropdown items |
+
 ## Browser support
 
 - Chrome/Edge 90+