@x-wave/blog 2.4.2 → 2.5.0

package/README.md

@@ -568,6 +568,89 @@ keywords: [getting started, tutorial, basics]
 ---
 ```
 
+### Static article indexer (`blog-indexer`)
+
+The framework ships a CLI tool that pre-generates static JSON index files from your MDX content. The home page and month-based archive views read these files at runtime instead of discovering articles on each request.
+
+**Install** (the CLI is included in `@x-wave/blog`):
+
+```bash
+npx blog-indexer --docs src/docs --output public/blog-index
+```
+
+Or add it as a project script:
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "index": "blog-indexer --docs src/docs --output public/blog-index"
+  }
+}
+```
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--docs` | Path to the docs directory (must contain language sub-directories, e.g. `en/`, `es/`) |
+| `--output` | Path to the output directory where JSON index files will be written |
+
+**Output structure** (one set per language):
+
+```
+public/blog-index/
+├── en/
+│   ├── latest.json            # Latest 20 articles (home page)
+│   ├── months-index.json      # Sorted list of YYYY-MM strings
+│   └── months/
+│       └── 2026-02.json       # Articles for that month
+├── es/
+│   └── ...
+└── zh/
+    └── ...
+```
+
+Run the indexer whenever you add, remove, or update articles, and commit the output so it is available at deploy time.
+
+#### CI: keeping the index in sync
+
+Add a GitHub Actions workflow to verify the committed index is up to date on every push. The workflow re-runs the indexer and fails if the output differs from what is committed:
+
+```yaml
+# .github/workflows/check-blog-index.yml
+name: Check blog index is up to date
+
+on: push
+
+jobs:
+  check-index:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Run blog indexer
+        run: npx blog-indexer --docs src/docs --output public/blog-index
+
+      - name: Verify index is up to date
+        run: |
+          if ! git diff --exit-code public/blog-index/; then
+            echo "::error::Blog index is out of date. Run the indexer and commit the result."
+            exit 1
+          fi
+```
+
+`git diff --exit-code` compares file content hashes internally, so no separate hash file is needed — if any generated file differs from the committed version the job fails with a clear error message.
+
 ### Custom headers
 
 If you need a custom header instead of the built-in one, simply omit the `header` config and use the provided hooks:

package/cli/index.js

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+/**
+ * @x-wave/blog Article Indexer CLI
+ *
+ * Generates static JSON index files from MDX article files.
+ * Run this whenever your content changes to keep the index up to date.
+ *
+ * Usage:
+ *   blog-indexer --docs <path-to-docs-dir> --output <output-dir>
+ *
+ * Options:
+ *   --docs    Path to the docs directory (must contain language sub-directories, e.g. en/, es/)
+ *   --output  Path to the output directory where JSON index files will be written
+ *
+ * Output structure (one set of files per language):
+ *   <output>/<lang>/latest.json          - Latest 20 articles (for the home page)
+ *   <output>/<lang>/months-index.json    - Sorted list of YYYY-MM strings with articles
+ *   <output>/<lang>/months/<YYYY-MM>.json - Articles for a specific month
+ *
+ * Example:
+ *   blog-indexer --docs src/docs --output public/blog-index
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+const LATEST_COUNT = 20
+
+/**
+ * Parse CLI arguments from process.argv.
+ */
+function parseArgs(argv) {
+	const args = {}
+	for (let i = 2; i < argv.length; i++) {
+		if (argv[i] === '--docs' && argv[i + 1]) {
+			args.docs = argv[++i]
+		} else if (argv[i] === '--output' && argv[i + 1]) {
+			args.output = argv[++i]
+		}
+	}
+	return args
+}
+
+/**
+ * Parse YAML frontmatter from MDX content.
+ * Supports string, boolean, and array values.
+ */
+function parseFrontmatter(content) {
+	const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n/)
+	if (!match) return { frontmatter: {} }
+
+	const frontmatter = {}
+	const frontmatterText = match[1]
+	let currentKey = ''
+	let isArrayContext = false
+	const arrayValues = []
+
+	for (const line of frontmatterText.split('\n')) {
+		const trimmed = line.trim()
+
+		// Handle array items (lines starting with -)
+		if (trimmed.startsWith('-')) {
+			if (isArrayContext) {
+				arrayValues.push(trimmed.substring(1).trim())
+			}
+			continue
+		}
+
+		// If we were in array context and hit a non-array line, save the array
+		if (isArrayContext && !trimmed.startsWith('-')) {
+			frontmatter[currentKey] = arrayValues.slice()
+			arrayValues.length = 0
+			isArrayContext = false
+		}
+
+		// Handle key-value pairs
+		const colonIndex = trimmed.indexOf(':')
+		if (colonIndex !== -1) {
+			const key = trimmed.substring(0, colonIndex).trim()
+			const value = trimmed.substring(colonIndex + 1).trim()
+			currentKey = key
+
+			// Empty value (nothing after the colon) means an array follows on subsequent lines
+			if (value === '') {
+				isArrayContext = true
+				continue
+			}
+
+			if (value === 'true') frontmatter[currentKey] = true
+			else if (value === 'false') frontmatter[currentKey] = false
+			else frontmatter[currentKey] = value
+		}
+	}
+
+	// Flush trailing array
+	if (isArrayContext && arrayValues.length > 0) {
+		frontmatter[currentKey] = arrayValues
+	}
+
+	return { frontmatter }
+}
+
+/**
+ * Extract the article slug from an MDX filename.
+ * Strips the `-advanced` suffix and `.mdx` extension.
+ */
+function extractSlug(fileName) {
+	return fileName.replace(/(-advanced)?\.mdx$/, '')
+}
+
+/**
+ * Extract the article title from frontmatter or the first H1 heading.
+ */
+function extractTitle(frontmatter, content, fallback) {
+	if (typeof frontmatter.title === 'string' && frontmatter.title) {
+		return frontmatter.title
+	}
+	const match = content.match(/^#\s+(.+)$/m)
+	return match ? match[1].trim() : fallback
+}
+
+/**
+ * Convert a date string to a YYYY-MM key, or null if not parseable.
+ */
+function toYearMonth(dateStr) {
+	if (!dateStr) return null
+	const date = new Date(dateStr)
+	if (Number.isNaN(date.getTime())) return null
+	const year = date.getFullYear()
+	const month = String(date.getMonth() + 1).padStart(2, '0')
+	return `${year}-${month}`
+}
+
+/**
+ * Sort articles by date (newest first), then alphabetically by title.
+ */
+function sortArticles(articles) {
+	return [...articles].sort((a, b) => {
+		const timeA = a.date ? new Date(a.date).getTime() : null
+		const timeB = b.date ? new Date(b.date).getTime() : null
+		const validA = timeA !== null && !Number.isNaN(timeA) ? timeA : null
+		const validB = timeB !== null && !Number.isNaN(timeB) ? timeB : null
+
+		if (validA !== null && validB !== null) {
+			if (validA !== validB) return validB - validA
+			return a.title.localeCompare(b.title)
+		}
+		if (validA !== null) return -1
+		if (validB !== null) return 1
+		return a.title.localeCompare(b.title)
+	})
+}
+
+/**
+ * Process all MDX files for a given language directory.
+ * Returns an array of article metadata objects.
+ */
+function processLanguage(docsDir, language) {
+	const langDir = path.join(docsDir, language)
+	if (!fs.existsSync(langDir)) return []
+
+	const files = fs.readdirSync(langDir)
+	const articles = []
+
+	for (const file of files) {
+		// Skip non-MDX files and advanced variants
+		if (!file.endsWith('.mdx')) continue
+		if (file.endsWith('-advanced.mdx')) continue
+
+		const filePath = path.join(langDir, file)
+		let content
+		try {
+			content = fs.readFileSync(filePath, 'utf-8')
+		} catch (err) {
+			console.warn(`  ⚠ Could not read ${filePath}: ${err.message}`)
+			continue
+		}
+
+		const { frontmatter } = parseFrontmatter(content)
+		const slug = extractSlug(file)
+		const title = extractTitle(frontmatter, content, slug)
+
+		articles.push({
+			slug,
+			title,
+			date: typeof frontmatter.date === 'string' ? frontmatter.date : undefined,
+			author:
+				typeof frontmatter.author === 'string' ? frontmatter.author : undefined,
+			description:
+				typeof frontmatter.description === 'string'
+					? frontmatter.description
+					: undefined,
+		})
+	}
+
+	return articles
+}
+
+/**
+ * Write data as formatted JSON to a file, creating any missing directories.
+ */
+function writeJson(filePath, data) {
+	fs.mkdirSync(path.dirname(filePath), { recursive: true })
+	fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf-8')
+}
+
+/**
+ * Main entry point.
+ */
+async function main() {
+	const args = parseArgs(process.argv)
+
+	if (!args.docs || !args.output) {
+		console.error('Usage: blog-indexer --docs <docs-dir> --output <output-dir>')
+		process.exit(1)
+	}
+
+	const docsDir = path.resolve(args.docs)
+	const outputDir = path.resolve(args.output)
+
+	if (!fs.existsSync(docsDir)) {
+		console.error(`Docs directory not found: ${docsDir}`)
+		process.exit(1)
+	}
+
+	// Discover language sub-directories
+	const entries = fs.readdirSync(docsDir, { withFileTypes: true })
+	const languages = entries.filter((e) => e.isDirectory()).map((e) => e.name)
+
+	if (languages.length === 0) {
+		console.warn('No language directories found in docs dir, nothing to index.')
+		process.exit(0)
+	}
+
+	for (const language of languages) {
+		console.log(`📝 Indexing language: ${language}`)
+
+		const articles = processLanguage(docsDir, language)
+		const sorted = sortArticles(articles)
+		const langOutputDir = path.join(outputDir, language)
+
+		// Write latest.json (top N articles for the home page)
+		const latest = sorted.slice(0, LATEST_COUNT)
+		writeJson(path.join(langOutputDir, 'latest.json'), latest)
+		console.log(`  ✓ latest.json (${latest.length} articles)`)
+
+		// Group articles by month (only articles with a parseable date)
+		/** @type {Map<string, typeof sorted>} */
+		const monthMap = new Map()
+		for (const article of sorted) {
+			const yearMonth = toYearMonth(article.date)
+			if (yearMonth) {
+				let monthArticles = monthMap.get(yearMonth)
+				if (!monthArticles) {
+					monthArticles = []
+					monthMap.set(yearMonth, monthArticles)
+				}
+				monthArticles.push(article)
+			}
+		}
+
+		// Write months-index.json (sorted newest month first)
+		const monthsIndex = Array.from(monthMap.keys()).sort((a, b) =>
+			b.localeCompare(a),
+		)
+		writeJson(path.join(langOutputDir, 'months-index.json'), monthsIndex)
+		console.log(`  ✓ months-index.json (${monthsIndex.length} months)`)
+
+		// Write one file per month
+		const monthsDir = path.join(langOutputDir, 'months')
+		for (const [yearMonth, monthArticles] of monthMap) {
+			writeJson(path.join(monthsDir, `${yearMonth}.json`), monthArticles)
+		}
+		if (monthMap.size > 0) {
+			console.log(`  ✓ ${monthMap.size} month file(s) in months/`)
+		}
+	}
+
+	console.log(`\n✅ Article index written to: ${outputDir}`)
+}
+
+main().catch((err) => {
+	console.error('Error:', err.message)
+	process.exit(1)
+})

package/context.d.ts

@@ -101,6 +101,16 @@ export interface BlogConfig {
      * Example: 'Roboto, sans-serif' or '"Segoe UI", sans-serif'
      */
     articleTitleFont?: string;
+    /**
+     * Optional base path to the pre-built article index files generated by the blog-indexer CLI.
+     * When provided, UI components load pre-built JSON files instead of scanning MDX files at
+     * runtime, which significantly improves performance for large article collections.
+     *
+     * Run `npx blog-indexer --docs src/docs --output public/blog-index` to generate the index.
+     *
+     * Example: '/blog-index' → fetches /blog-index/{language}/latest.json etc.
+     */
+    indexPath?: string;
 }
 /**
  * A navigation link in the header.

package/index.d.ts

@@ -9,6 +9,7 @@ export { ContentPage } from './components/ContentPage';
 export { DocumentationLayout } from './components/DocumentationLayout';
 export { DocumentationRoutes } from './components/DocumentationRoutes';
 export { Header } from './components/Header';
+export type { BlogArticle } from './components/HomePage';
 export { HomePage } from './components/HomePage';
 export type { MetadataProps } from './components/Metadata';
 export { Metadata } from './components/Metadata';