@x-wave/blog 1.0.36 → 1.0.38

package/README.md

@@ -56,6 +56,20 @@ src/
         ├── welcome.mdx
         ├── glossary.mdx
         └── faq.mdx
+public/
+└── og/
+    ├── en/                      # Language-specific OG images
+    │   ├── welcome-preview.png
+    │   ├── glossary-preview.png
+    │   └── faq-preview.png
+    ├── es/
+    │   ├── welcome-preview.png
+    │   ├── glossary-preview.png
+    │   └── faq-preview.png
+    └── zh/
+        ├── welcome-preview.png
+        ├── glossary-preview.png
+        └── faq-preview.png
 ```
 
 ### 2. Set up i18n and styles
@@ -250,8 +264,11 @@ 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. |
+| `ogImage` | `string` | Optional Open Graph image filename (just the filename, not the full path). Images should be stored in `public/og/<language>/` folder. Used for social media sharing previews. |
 | `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 +407,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 +424,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 +459,79 @@ 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>`, `<meta keywords>`, and Open Graph tags are set based on article frontmatter and site configuration.
+
+**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)
+- **Open Graph Image**: Uses article `ogImage` filename (image path is auto-constructed from language folder)
+
+**Open Graph tags (for social media sharing):**
+When an article includes an `ogImage`, the framework automatically generates:
+- `og:image` - The full image URL for social media preview
+- `og:title` - The article title
+- `twitter:card` - Set to `summary_large_image` for Twitter/X preview
+- `twitter:image` - The image URL for Twitter/X sharing
+
+**Home page:**
+- **Title**: Site title from config
+- **Description**: Uses site-level `description` from config
+
+Image folder structure for serving OG images:
+
+```
+public/og/
+├── en/
+│   ├── getting-started.png      # Served as /og/en/getting-started.png
+│   └── tutorial.png              # Served as /og/en/tutorial.png
+├── es/
+│   └── getting-started.png      # Served as /og/es/getting-started.png
+└── zh/
+    └── getting-started.png      # Served as /og/zh/getting-started.png
+```
+
+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
+keywords: [getting started, setup, tutorial, beginners]
+ogImage: getting-started.png  // Image at /og/en/getting-started.png (or /og/es/, /og/zh/)
+---
+```
+
+When users share this article on social media:
+- Facebook will show the title, description, and the OG image
+- Twitter/X will show a large image preview with the article title
+- LinkedIn and other platforms will use the OG metadata for rich previews
+
+This ensures proper SEO for search engines and rich sharing previews on social media, with full 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: