@x-wave/blog 2.9.1 → 2.10.0

package/README.md

@@ -300,6 +300,29 @@ The blog system supports standard Markdown and extended syntax via GitHub Flavor
 ~~strikethrough~~
 ```
 
+#### Text Alignment
+
+Wrap content in `[left]`, `[center]`, or `[right]` tags. Inline Markdown remains
+available inside aligned content:
+
+```mdx
+[center]This paragraph is **centered**.[/center]
+
+[right]
+This paragraph is right-aligned.
+[/right]
+
+[left]
+
+- A left-aligned list item
+- Another item
+
+[/left]
+```
+
+Use blank lines between the alignment tags and content when wrapping multiple
+Markdown blocks such as headings, lists, or several paragraphs.
+
 #### Lists
 
 **Unordered lists:**
@@ -633,7 +656,8 @@ 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
+- **Sorting**: Articles sorted by date (newest first), with 20 articles per page
+- **Pagination**: Crawlable archive URLs at `/{language}/page/{page}`
 
 Article metadata comes from MDX frontmatter:
 ```mdx
@@ -673,13 +697,21 @@ Or add it as a project script:
 |---|---|
 | `--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 |
+| `--page-size` | Optional number of articles per page (default: `20`) |
+
+If you customize `--page-size`, pass the same value as `articlesPerPage` to
+`setupSSG()` so the JSON and statically generated archive pages stay aligned.
 
 **Output structure** (one set per language):
 
 ```
 public/blog-index/
 ├── en/
-│   ├── latest.json            # Latest 20 articles (home page)
+│   ├── latest.json            # Latest 100 articles (legacy index)
+│   ├── pages-index.json       # Page count and page-size metadata
+│   ├── pages/
+│   │   ├── 1.json             # First 20 articles
+│   │   └── 2.json             # Next 20 articles
 │   ├── months-index.json      # Sorted list of YYYY-MM strings
 │   └── months/
 │       └── 2026-02.json       # Articles for that month

package/cli/index.js

@@ -11,9 +11,12 @@
  * 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
+ *   --page-size Number of articles per home page (default: 20)
  *
  * Output structure (one set of files per language):
- *   <output>/<lang>/latest.json          - Latest 50 articles (for the home page)
+ *   <output>/<lang>/latest.json          - Latest 100 articles (legacy home page index)
+ *   <output>/<lang>/pages-index.json     - Pagination metadata for the home page
+ *   <output>/<lang>/pages/<N>.json       - Articles for a home page 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
  *
@@ -25,6 +28,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 
 const LATEST_COUNT = 100
+const DEFAULT_PAGE_SIZE = 20
 
 /**
  * Parse CLI arguments from process.argv.
@@ -36,6 +40,8 @@ function parseArgs(argv) {
 			args.docs = argv[++i]
 		} else if (argv[i] === '--output' && argv[i + 1]) {
 			args.output = argv[++i]
+		} else if (argv[i] === '--page-size' && argv[i + 1]) {
+			args.pageSize = Number(argv[++i])
 		}
 	}
 	return args
@@ -202,9 +208,13 @@ function processLanguage(docsDir, language) {
 /**
  * Write data as formatted JSON to a file, creating any missing directories.
  */
-function writeJson(filePath, data) {
+function writeJson(filePath, data, indentation = '\t') {
 	fs.mkdirSync(path.dirname(filePath), { recursive: true })
-	fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf-8')
+	fs.writeFileSync(
+		filePath,
+		`${JSON.stringify(data, null, indentation)}\n`,
+		'utf-8',
+	)
 }
 
 /**
@@ -214,12 +224,23 @@ async function main() {
 	const args = parseArgs(process.argv)
 
 	if (!args.docs || !args.output) {
-		console.error('Usage: blog-indexer --docs <docs-dir> --output <output-dir>')
+		console.error(
+			'Usage: blog-indexer --docs <docs-dir> --output <output-dir> [--page-size <number>]',
+		)
+		process.exit(1)
+	}
+
+	if (
+		args.pageSize !== undefined &&
+		(!Number.isInteger(args.pageSize) || args.pageSize < 1)
+	) {
+		console.error('--page-size must be a positive integer')
 		process.exit(1)
 	}
 
 	const docsDir = path.resolve(args.docs)
 	const outputDir = path.resolve(args.output)
+	const pageSize = args.pageSize ?? DEFAULT_PAGE_SIZE
 
 	if (!fs.existsSync(docsDir)) {
 		console.error(`Docs directory not found: ${docsDir}`)
@@ -247,6 +268,28 @@ async function main() {
 		writeJson(path.join(langOutputDir, 'latest.json'), latest)
 		console.log(`  ✓ latest.json (${latest.length} articles)`)
 
+		// Write paginated indexes for the home page. Keeping the pages separate means
+		// the browser only downloads the metadata it needs for the current page.
+		const totalPages = Math.ceil(sorted.length / pageSize)
+		writeJson(path.join(langOutputDir, 'pages-index.json'), {
+			pageSize,
+			totalArticles: sorted.length,
+			totalPages,
+		})
+
+		const pagesDir = path.join(langOutputDir, 'pages')
+		fs.rmSync(pagesDir, { recursive: true, force: true })
+		for (let page = 1; page <= totalPages; page++) {
+			const start = (page - 1) * pageSize
+			writeJson(
+				path.join(pagesDir, `${page}.json`),
+				sorted.slice(start, start + pageSize),
+			)
+		}
+		console.log(
+			`  ✓ pages-index.json and ${totalPages} page file(s) (${pageSize} per page)`,
+		)
+
 		// Group articles by month (only articles with a parseable date)
 		/** @type {Map<string, typeof sorted>} */
 		const monthMap = new Map()
@@ -266,7 +309,7 @@ async function main() {
 		const monthsIndex = Array.from(monthMap.keys()).sort((a, b) =>
 			b.localeCompare(a),
 		)
-		writeJson(path.join(langOutputDir, 'months-index.json'), monthsIndex)
+		writeJson(path.join(langOutputDir, 'months-index.json'), monthsIndex, 0)
 		console.log(`  ✓ months-index.json (${monthsIndex.length} months)`)
 
 		// Write one file per month