@x-wave/blog 1.0.36 → 1.0.37

package/README.md

@@ -250,8 +250,10 @@ Regular content here.
 | 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. |
 
@@ -390,6 +392,7 @@ All CSS variables are scoped to `.xw-blog-root` for isolation and to prevent con
 ```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
@@ -406,6 +409,7 @@ 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.
+- **`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
@@ -440,9 +444,52 @@ title: Getting Started
 author: Jane Doe
 date: 2026-02-23
 description: Learn the basics in 5 minutes
+keywords: [getting started, tutorial, basics]
 ---
 ```
 
+### SEO and metadata
+
+The framework automatically handles SEO metadata using React Helmet. Page `<title>`, `<meta description>`, and `<meta keywords>` tags are set based on:
+
+**Article pages:**
+- **Title**: `"{article title} | {site title}"` (if title exists in frontmatter)
+- **Description**: Uses article `description` from frontmatter, falls back to site-level `description` from config
+- **Keywords**: Uses article `keywords` from frontmatter (converts array to comma-separated string)
+
+**Home page:**
+- **Title**: Site title from config
+- **Description**: Uses site-level `description` from config
+
+Example setup:
+
+```tsx
+// app.tsx
+<BlogProvider
+  config={{
+    title: 'My Documentation',
+    description: 'Complete guide to our platform',  // Fallback description
+    supportedLanguages: ['en', 'es'],
+    navigationData: NAVIGATION_DATA,
+  }}
+  blog={blog}
+>
+```
+
+Then in your MDX frontmatter:
+
+```mdx
+---
+title: Getting Started
+author: Jane Doe
+date: 2026-02-23
+description: Step-by-step guide to getting started in 5 minutes  // Overrides site description
+keywords: [getting started, setup, tutorial, beginners]
+---
+```
+
+This ensures proper SEO for search engines and social media sharing, with support for multi-language content.
+
 ### Custom headers
 
 If you need a custom header instead of the built-in one, simply omit the `header` config and use the provided hooks: