@x-wave/blog 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,424 @@
+# @x-wave/blog
+
+A responsive, multi-language documentation framework for React + Vite applications. Ships with TypeScript, i18n (i18next), MDX support, dark mode, and built-in navigation.
+
+## Features
+
+- **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'    // Framework styles (required)
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(<App />)
+```
+
+> **The styles import is required** for the UI components and layout to render correctly.
+
+**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
+})
+```
+
+### 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)
+```
+
+### 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>
+  )
+}
+```
+
+> **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
+
+Place your MDX files in language-specific directories:
+
+```
+src/docs/
+├── en/welcome.mdx
+├── es/welcome.mdx
+└── zh/welcome.mdx
+```
+
+File names must match the `slug` field in your navigation definition.
+
+### Frontmatter
+
+Optional YAML at the top of your MDX file:
+
+```mdx
+---
+title: Getting Started
+author: Jane Doe
+date: 2026-02-23
+hasAdvanced: true
+tags:
+  - tutorial
+  - beginner
+---
+
+# Welcome!
+
+Regular content here.
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `title` | `string` | Document title (informational, not displayed by framework) |
+| `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). |
+| `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. |
+
+### Advanced mode variants
+
+Create `welcome-advanced.mdx` alongside `welcome.mdx`:
+
+```
+src/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
+
+### Components
+
+All components are exported from `@x-wave/blog`:
+
+```ts
+import { 
+  BlogProvider, 
+  DocumentationRoutes,
+  DocumentationLayout, 
+  ContentPage,
+  Header,
+  Sidebar,
+  TableOfContents,
+  AdvancedModeToggle
+} from '@x-wave/blog'
+```
+
+| 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 |
+| `Sidebar` | Left navigation panel |
+| `TableOfContents` | "On this page" anchor panel |
+| `AdvancedModeToggle` | Simple/Advanced tab switch |
+
+### 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'
+```
+
+## Customization
+
+### CSS variables
+
+The framework exports SCSS variable files. Import and override them in your own stylesheets:
+
+```scss
+// In your app.scss
+@use '~@x-wave/blog/styles/_variables' as vars;
+
+// Override the color palette
+$color-primary: #007bff;
+$color-background: #fafafa;
+
+// Your custom styles here
+```
+
+Or import directly from the framework package:
+
+```scss
+@import 'node_modules/@x-wave/blog/dist/styles/_variables.scss';
+
+$color-primary: #007bff;
+$color-background: #fafafa;
+```
+
+Available variables include:
+- `$color-primary`, `$color-secondary`
+- `$color-background`, `$color-text`
+- `$spacing-xs`, `$spacing-sm`, `$spacing-md`, `$spacing-lg`, `$spacing-xl`
+- `$font-family-sans`, `$font-family-mono`
+- And more—see [styles/_variables.scss](packages/styles/_variables.scss)
+
+### Config options
+
+**BlogConfig** properties:
+
+```ts
+interface BlogConfig {
+  title: string                                    // Site title
+  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
+  }
+}
+```
+
+**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+
+- Firefox 88+
+- Safari 14+
+- Mobile browsers (iOS Safari 14.5+, Chrome Android 90+)
+
+## License
+
+See LICENSE file in this repository.
+
+---
+
+## For framework maintainers
+
+Contributing or maintaining this framework? See [DEVELOPMENT.md](./DEVELOPMENT.md) for setup, architecture, and build system details.