@x-wave/blog 1.1.4 → 2.0.0

package/README.md

@@ -1,236 +1,54 @@
-# @x-wave/blog
+# Staking Docs
 
-A responsive, multi-language documentation framework for React + Vite applications. Ships with TypeScript, i18n (i18next), MDX support, dark mode, and built-in navigation.
+Multi-language documentation site built with Next.js App Router and MDX. This repo contains both the framework packages and a reference app used for local development and previews.
 
-## Features
+## Repository structure
 
-- **Multi-language support**: Ship 3+ languages with a single codebase (en, es, zh included)
-- **MDX content**: Write docs in Markdown with React components
-- **Dark mode**: Built-in light/dark/system theme toggle with localStorage persistence
-- **Advanced mode**: Optional Simple/Advanced content variants for the same page
-- **Mobile responsive**: Automatic sidebar → mobile menu on small screens
-- **Headless**: No styling opinions—includes SCSS variables for full customization
-- **HMR-friendly**: Vite development with Hot Module Replacement for instant feedback
-
-## Installation
-
-### npm
-
-```bash
-npm install @x-wave/blog
-```
-
-### pnpm
-
-```bash
-pnpm add @x-wave/blog
-```
-
-### yarn
-
-```bash
-yarn add @x-wave/blog
 ```
-
-## Quick setup
-
-### 1. Create your app structure
-
-```
-src/
-├── App.tsx                      # Your app component
-├── main.tsx                     # Entry point
-├── navigation.ts                # Site navigation definition
-├── utils.ts                     # Content loaders
-├── logo.svg                     # Optional: your logo
-└── docs/
-    ├── en/
-    │   ├── welcome.mdx
-    │   ├── glossary.mdx
-    │   └── faq.mdx
-    ├── es/
-    │   ├── welcome.mdx
-    │   ├── glossary.mdx
-    │   └── faq.mdx
-    └── zh/
-        ├── welcome.mdx
-        ├── glossary.mdx
-        └── faq.mdx
-```
-
-### 2. Set up i18n and styles
-
-Import the i18n setup and framework styles in your app entry point:
-
-```ts
-// src/main.tsx
-import '@x-wave/blog/locales'   // Initialises i18next with en, es, zh
-import '@x-wave/blog/styles'    // Compiled CSS with variables and component styles (required)
-import { createRoot } from 'react-dom/client'
-import App from './App'
-
-createRoot(document.getElementById('root')!).render(<App />)
+packages/
+├── app/            # Next.js reference app
+├── blog/           # Build orchestration package
+├── ui/             # UI components and client logic
+├── locales/        # i18n resources (i18next)
+├── consts/         # Navigation config + shared constants
+├── styles/         # SCSS + compiled CSS
+└── types/          # Shared TypeScript types
 ```
 
-> **The styles import is required** for the UI components and layout to render correctly. This imports a single compiled CSS file (`index.css`) that contains all framework styles, CSS variables, and component styles.
+## Quick start
 
-**Add custom translations:**
-
-```ts
-// src/main.tsx
-import '@x-wave/blog/locales'
-import i18next from 'i18next'
-
-// Add French translations
-i18next.addResourceBundle('fr', 'translation', {
-  language: 'Français',
-  'ui.simple': 'Simple',
-  'ui.advanced': 'Avancé',
-  // ... other keys
-})
-```
+### 1. Install dependencies
 
-### 3. Define your navigation
-
-```ts
-// src/navigation.ts
-import type { NavigationEntry } from '@x-wave/blog/types'
-
-export const NAVIGATION_DATA: NavigationEntry[] = [
-  {
-    title: 'docs.welcome',
-    slug: 'welcome',
-  },
-  {
-    title: 'Help',
-    defaultOpen: true,
-    items: [
-      {
-        title: 'docs.glossary',
-        slug: 'glossary',
-        showTableOfContents: true,
-      },
-      {
-        title: 'docs.faq',
-        slug: 'faq',
-      },
-    ],
-  },
-]
-```
-
-### 4. Create content loaders
-
-```ts
-// src/utils.ts
-import { createBlogUtils } from '@x-wave/blog'
-
-// Vite glob import – resolved relative to this file
-const mdxFiles = import.meta.glob('./docs/**/*.mdx', {
-  query: '?raw',
-  import: 'default',
-  eager: false,
-})
-
-// Export all blog utilities in a single object
-export const blog = createBlogUtils(mdxFiles)
+```bash
+pnpm install
 ```
 
-### 5. Wrap your app with BlogProvider
-
-```tsx
-// src/App.tsx
-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
-
-export default function App() {
-  return (
-    <BlogProvider
-      config={{
-        title: 'My Documentation',
-        supportedLanguages: SUPPORTED_LANGUAGES,
-        navigationData: NAVIGATION_DATA,
-        header: {
-          navLinks: [
-            {
-              label: 'Visit Site',
-              url: 'https://example.com',
-              target: '_blank',
-            },
-          ],
-        },
-      }}
-      blog={blog}
-    >
-      <Router>
-        <Routes>
-          <Route path="/:language/*" element={<DocumentationRoutes />} />
-          <Route path="/" element={<Navigate to="/en/welcome" replace />} />
-        </Routes>
-      </Router>
-    </BlogProvider>
-  )
-}
-```
+### 2. Run the Next.js 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>
-  )
-}
+```bash
+pnpm dev
 ```
 
-This ensures internal navigation (search, tags, language switching) uses the correct base path.
-
-## Writing content
+The app runs from [packages/app](packages/app). The default route is `/en/welcome`.
 
-### File naming
+## Content structure
 
-Place your MDX files in language-specific directories:
+MDX files live under the app package:
 
 ```
-src/docs/
-├── en/welcome.mdx
-├── es/welcome.mdx
-└── zh/welcome.mdx
+packages/app/docs/
+├── en/
+│   ├── welcome.mdx
+│   ├── glossary.mdx
+│   └── faq.mdx
+├── es/
+└── zh/
 ```
 
-File names must match the `slug` field in your navigation definition.
+File names must match the `slug` in the navigation config.
 
 ### Frontmatter
 
-Optional YAML at the top of your MDX file:
-
 ```mdx
 ---
 title: Getting Started
@@ -243,319 +61,68 @@ tags:
 ---
 
 # Welcome!
-
-Regular content here.
 ```
 
+Supported fields:
+
 | Field | Type | Description |
 |---|---|---|
-| `title` | `string` | Document title (informational, not displayed by framework) |
-| `description` | `string` | Optional SEO description for the article. Used in the page `<meta name="description">` tag. Falls back to site-level description if not provided. |
-| `author` | `string` | Author name. Displayed below the page title with a user icon. |
-| `date` | `string` | Publication or update date. Displayed below the page title with "Last edited" label and calendar icon (i18n supported). |
-| `keywords` | `string[] \| string` | Optional array of keywords or comma-separated string for SEO. Inserted into the page `<meta name="keywords">` tag. |
-| `hasAdvanced` | `boolean` | Enables Simple/Advanced mode toggle. Requires a `-advanced.mdx` variant. |
-| `tags` | `string[]` | Array of tag strings for categorizing content. Tags are automatically indexed by the framework when you pass `mdxFiles` to BlogProvider. Tags are clickable and show search results. |
+| `title` | `string` | Document title (informational, not displayed as the main heading) |
+| `description` | `string` | SEO description override (used for `<meta name="description">`) |
+| `author` | `string` | Author display under the title |
+| `date` | `string` | Date shown under the title (i18n-aware label) |
+| `keywords` | `string[] \| string` | Optional SEO keywords list |
+| `hasAdvanced` | `boolean` | Enables Simple/Advanced toggle and `-advanced.mdx` variant |
+| `tags` | `string[]` | Tag labels used by the tag index modal |
 
 ### Advanced mode variants
 
-Create `welcome-advanced.mdx` alongside `welcome.mdx`:
+Create a paired file that ends with `-advanced.mdx`:
 
 ```
-src/docs/
-├── en/
-│   ├── welcome.mdx
-│   └── welcome-advanced.mdx
+packages/app/docs/en/
+├── welcome.mdx
+└── welcome-advanced.mdx
 ```
 
-Set `hasAdvanced: true` in the simple version's frontmatter, and the framework automatically shows a toggle.
-
-## API reference
+Set `hasAdvanced: true` in the simple version frontmatter.
 
-### Components
+## Navigation configuration
 
-All components are exported from `@x-wave/blog`:
+Navigation lives in [packages/consts/src/navigation.ts](packages/consts/src/navigation.ts) and is passed into `BlogProvider` via the app config. Each entry can specify `showTableOfContents` per item.
 
-```ts
-import { 
-  BlogProvider, 
-  DocumentationRoutes,
-  DocumentationLayout, 
-  ContentPage,
-  HomePage,
-  Header,
-  Sidebar,
-  TableOfContents,
-  AdvancedModeToggle,
-  Metadata
-} from '@x-wave/blog'
-```
+## Next.js implementation notes
 
-| 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 |
-| `HomePage` | Lists latest articles with metadata (configurable via `defaultRoute`) |
-| `Header` | Top navigation bar |
-| `Sidebar` | Left navigation panel |
-| `TableOfContents` | "On this page" anchor panel |
-| `AdvancedModeToggle` | Simple/Advanced tab switch |
-| `Metadata` | Displays author and publication date with icons (used in HomePage and ContentPage) |
-
-### Hooks
-
-```ts
-import { useTheme } from '@x-wave/blog'
-
-const { theme, setTheme, effectiveTheme } = useTheme()
-```
-Manages light/dark/system theme preference.
-
-### Utilities
-
-```ts
-import { createBlogUtils } from '@x-wave/blog'
-
-const blog = createBlogUtils(mdxFiles)
-```
-Creates all blog utilities from a Vite glob import. This is the recommended approach as it bundles everything together.
-
-Returns an object with:
-- **`mdxFiles`**: The glob import (used internally for automatic tag indexing)
-- **`loadContent(language, slug, advanced?)`**: Loads MDX content for a specific language and slug
-- **`loadEnglishContent(slug, advanced?)`**: Loads English content for heading ID generation
-
-Pass the entire `blog` object to BlogProvider:
-
-```tsx
-<BlogProvider config={config} blog={blog}>
-```
-
-**Alternative: Advanced usage**
-
-```ts
-import { createContentLoaders } from '@x-wave/blog'
-
-const { loadMDXContent, loadEnglishContent, buildTagIndex } = createContentLoaders(mdxFiles)
-```
-For advanced use cases where you need more control over content loading and tag indexing.
-
-### Types
-
-All TypeScript types are exported from `@x-wave/blog/types`:
-
-```ts
-import type { NavigationEntry, BlogConfig, HeaderLink } from '@x-wave/blog/types'
-```
+- **Static params**: `generateStaticParams()` in [packages/app/app/[language]/[slug]/page.tsx](packages/app/app/%5Blanguage%5D/%5Bslug%5D/page.tsx)
+- **Server-side content**: `readArticle()` and `readEnglishContent()` in [packages/app/lib/content.ts](packages/app/lib/content.ts)
+- **Client render**: `ContentPage` in [packages/ui/src/components/ContentPage/index.tsx](packages/ui/src/components/ContentPage/index.tsx)
 
 ## Customization
 
-### CSS variables
-
-The framework uses CSS custom properties (`--xw-*` prefix) for theming. These are automatically injected when the framework initializes, but you can override them:
-
-```css
-/* In your app.css */
-.xw-blog-root {
-  --xw-primary: #007bff;
-  --xw-background: #fafafa;
-  --xw-foreground: #1a1a1a;
-  /* ... other variables */
-}
-```
-
-Or in JavaScript:
-
-```javascript
-const blogRoot = document.querySelector('.xw-blog-root')
-blogRoot.style.setProperty('--xw-primary', '#007bff')
-blogRoot.style.setProperty('--xw-background', '#fafafa')
-```
-
-Available CSS variables include:
-- `--xw-primary`, `--xw-secondary`
-- `--xw-background`, `--xw-foreground`
-- `--xw-card`, `--xw-card-foreground`
-- `--xw-muted`, `--xw-muted-foreground`
-- `--xw-accent`, `--xw-accent-foreground`
-- `--xw-border`, `--xw-ring`
-- And more—defined in `packages/styles/main.scss`
-
-All CSS variables are scoped to `.xw-blog-root` for isolation and to prevent conflicts with your application styles.
-
-### Config options
-
-**BlogConfig** properties:
-
-```ts
-interface BlogConfig {
-  title: string                                    // Site title
-  description?: string                            // Optional default description for SEO (used as fallback if article has no description)
-  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: '')
-  contentMaxWidth?: string                        // Max width for content area (default: '80rem')
-  defaultRoute?: string                           // Default route: 'latest' (home page) or article slug (default: 'latest')
-  header?: {                                       // Optional: omit to hide built-in header
-    navLinks?: HeaderLink[]                       // Top-level nav links
-    dropdownItems?: HeaderDropdownItem[]          // Support dropdown menu
-  }
-}
-```
-
-**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.
-- **`description`**: Optional. Default SEO description used in the page `<meta name="description">` tag. Articles can override this with their own `description` in frontmatter.
-- **`contentMaxWidth`**: Optional. Set a custom maximum width for the main content area. Example: `'100rem'` or `'1400px'`. Default: `'80rem'`.
-- **`defaultRoute`**: Optional. Controls which page displays at the root path (`/`):
-  - Set to `'latest'` (default) to show the HomePage listing the latest articles
-  - Set to any article slug (e.g., `'welcome'`, `'getting-started'`) to redirect the root path to that article
-
-### Home page feature
+### Styles
 
-The framework includes an optional home/latest posts page that lists articles sorted by publish date. Configure it with the `defaultRoute` option:
+The compiled CSS is exported from `@x-wave/blog/styles`. In the Next.js app, it is imported once in [packages/app/app/globals.scss](packages/app/app/globals.scss). Override CSS variables on `.xw-blog-root` to theme the UI.
 
-```tsx
-// Show home page at root path (lists latest articles)
-config: {
-  defaultRoute: 'latest'  // or omit (defaults to 'latest')
-}
+### Base path
 
-// Or redirect root path to a specific article
-config: {
-  defaultRoute: 'welcome'  // Root path goes to /welcome article
-}
-```
-
-The home page displays:
-- **Title**: "Latest Posts" (i18n translated)
-- **Header metadata**: Author and date from the most recent article
-- **Article cards**: Recent articles with title, description, author, and date
-- **Sorting**: Articles sorted by date (newest first), limited to 50 articles
-
-Article metadata comes from MDX frontmatter:
-```mdx
----
-title: Getting Started
-author: Jane Doe
-date: 2026-02-23
-description: Learn the basics in 5 minutes
-keywords: [getting started, tutorial, basics]
----
-```
+If you mount the docs under a subpath, set `basePath` in the BlogProvider config. This ensures internal links and language switching include the prefix.
 
-### 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>
-  )
-}
-```
+### Custom header
 
-### Reusable components
+Omit the `header` config to hide the built-in header and use the hooks provided by the UI package (`useTheme`, `useSearchModal`).
 
-#### Metadata component
+## Scripts
 
-The `Metadata` component displays article metadata (author and publication date) with icons and i18n support. It's used throughout the framework (HomePage and ContentPage) but is also exported for your own use:
+From repo root:
 
-```tsx
-import { Metadata } from '@x-wave/blog'
-
-function MyComponent() {
-  return (
-    <Metadata 
-      author="Jane Doe"
-      date="2026-02-23"
-    />
-  )
-}
-```
-
-The component:
-- Displays author with a user icon
-- Displays date with a calendar icon and "Last edited" label
-- Automatically formats the date using the user's locale
-- Returns `null` if both author and date are missing
-- Uses i18n for the "Last edited" label and date formatting
-
-**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 |
-| `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+
-- Firefox 88+
-- Safari 14+
-- Mobile browsers (iOS Safari 14.5+, Chrome Android 90+)
+- `pnpm dev`: Starts the Next.js app and blog watcher
+- `pnpm build`: Builds all packages and the app
+- `pnpm build:blog`: Builds the blog package output
 
 ## License
 
-See LICENSE file in this repository.
-
----
+See [LICENSE](LICENSE).
 
-## For framework maintainers
+## Maintainers
 
-Contributing or maintaining this framework? See [DEVELOPMENT.md](./DEVELOPMENT.md) for setup, architecture, and build system details.
+See [DEVELOPMENT.md](DEVELOPMENT.md) for build system details and contributor notes.