feat(blog): enhance heading utilities with locale support

Add locale-aware blog heading utilities and improve validation.
Support both zh-CN and en-US blog directories with unified
heading structure verification.

Co-Authored-By: Hagicode <noreply@hagicode.com>
Signed-off-by: newbe36524 <newbe36524@qq.com>

Author: newbe36524

scripts/blog-heading-utils.mjs

@@ -2,10 +2,27 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 export const blogContentDir = path.resolve(process.cwd(), 'src/content/docs/blog');
+export const englishBlogContentDir = path.resolve(process.cwd(), 'src/content/docs/en/blog');
 export const distDir = path.resolve(process.cwd(), 'dist');
+export const blogLocaleDirs = {
+  zh: 'src/content/docs/blog',
+  en: 'src/content/docs/en/blog',
+};
 
 export function normalizeText(value) {
-  return value.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+  return decodeHtmlEntities(value)
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function decodeHtmlEntities(value) {
+  return value
+    .replace(/&#39;/g, "'")
+    .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>');
 }
 
 export function splitFrontmatter(source) {
@@ -123,24 +140,31 @@ export function listRenderedHtmlFiles(relativeDir) {
   return results.sort();
 }
 
-export function getBlogSourceEntries() {
-  if (!fs.existsSync(blogContentDir)) {
-    throw new Error(`Missing blog content directory: ${blogContentDir}`);
+export function getBlogSourceEntries({ locale = 'zh', rootDir = process.cwd() } = {}) {
+  const relativeDir = blogLocaleDirs[locale];
+  if (!relativeDir) {
+    throw new Error(`Unsupported blog locale: ${locale}`);
+  }
+
+  const contentDir = path.resolve(rootDir, relativeDir);
+  if (!fs.existsSync(contentDir)) {
+    throw new Error(`Missing blog content directory: ${contentDir}`);
   }
 
   return fs
-    .readdirSync(blogContentDir)
+    .readdirSync(contentDir)
     .filter((name) => name.endsWith('.md') || name.endsWith('.mdx'))
     .sort()
     .map((name) => {
-      const relativePath = path.join('src/content/docs/blog', name);
-      const fullPath = path.join(blogContentDir, name);
+      const relativePath = path.join(relativeDir, name);
+      const fullPath = path.join(contentDir, name);
       const source = readTextFile(fullPath);
       const { frontmatter, body, bodyStartLine } = splitFrontmatter(source);
       const slug = name.replace(/\.(md|mdx)$/i, '');
       return {
         fullPath,
         relativePath,
+        locale,
         slug,
         title: parseFrontmatterTitle(frontmatter),
         body,

scripts/verify-blog-heading-structure.mjs

@@ -72,8 +72,11 @@ function verifyCollectionRoutes() {
 }
 
 function verifyPostRoutes() {
-  for (const entry of getBlogSourceEntries()) {
+  for (const entry of getBlogSourceEntries({ locale: 'zh' })) {
     verifyPostRoute(path.posix.join('blog', entry.slug, 'index.html'), entry.title);
+  }
+
+  for (const entry of getBlogSourceEntries({ locale: 'en' })) {
     verifyPostRoute(path.posix.join('en/blog', entry.slug, 'index.html'), entry.title);
   }
 }

tests/blog-heading-validation.test.mjs

@@ -1,8 +1,12 @@
 import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import test from 'node:test';
 
 import {
   extractH1Texts,
+  getBlogSourceEntries,
   hiddenFirstPanelRuleExists,
   parseFrontmatterTitle,
   scanMarkdownH1s,
@@ -27,7 +31,36 @@ test('extractH1Texts normalizes nested markup', () => {
   assert.deepEqual(extractH1Texts(html), ['Docs Blog']);
 });
 
+test('extractH1Texts decodes common HTML entities before comparison', () => {
+  const html = '<h1>HagiCode&#39;s &quot;quoting&quot; test</h1>';
+  assert.deepEqual(extractH1Texts(html), [`HagiCode's "quoting" test`]);
+});
+
 test('hiddenFirstPanelRuleExists detects hidden title panel CSS', () => {
   assert.equal(hiddenFirstPanelRuleExists('.content-panel:first-of-type{display:none}'), true);
   assert.equal(hiddenFirstPanelRuleExists('.content-panel:first-of-type{display:block}'), false);
 });
+
+test('getBlogSourceEntries reads localized blog titles from the matching locale directory', () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'docs-blog-heading-'));
+  fs.mkdirSync(path.join(rootDir, 'src/content/docs/blog'), { recursive: true });
+  fs.mkdirSync(path.join(rootDir, 'src/content/docs/en/blog'), { recursive: true });
+
+  fs.writeFileSync(
+    path.join(rootDir, 'src/content/docs/blog/example.mdx'),
+    '---\ntitle: 中文标题\n---\n\n内容\n',
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(rootDir, 'src/content/docs/en/blog/example.mdx'),
+    '---\ntitle: English Title\n---\n\nBody\n',
+    'utf8',
+  );
+
+  const zhEntries = getBlogSourceEntries({ locale: 'zh', rootDir });
+  const enEntries = getBlogSourceEntries({ locale: 'en', rootDir });
+
+  assert.equal(zhEntries[0].title, '中文标题');
+  assert.equal(enEntries[0].title, 'English Title');
+  assert.equal(enEntries[0].locale, 'en');
+});