feat: add plugin to generate help.json (#24)

ngyinze · web-flow · commit 4e5a2cde85ff · 2025-03-26T11:13:25.000+08:00
* feat: add help.json plugin

* feat: add formName to front matter
diff --git a/docs/quick-start/customer/_category_.json b/docs/quick-start/customer/_category_.json
@@ -1,8 +1,8 @@
 {
-    "label": "Customer Refund",
+    "label": "Customer",
     "position": 3,
     "link": {
         "type": "generated-index",
-        "description": "Learn on Customer Refund in SQL Account"
+        "description": "Learn on Customer in SQL Account"
     }
 }
diff --git a/docs/quick-start/customer/customer-aging/intro.md b/docs/quick-start/customer/customer-aging/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true 
 slug: /quick-start/customer/customer-aging 
+form_name: TrfmARAging
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/customer/customer-contra/intro.md b/docs/quick-start/customer/customer-contra/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true 
 slug: /quick-start/customer/customer-contra 
+form_name: TfmARCT
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/customer/customer-deposit/intro.md b/docs/quick-start/customer/customer-deposit/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true 
 slug: /quick-start/customer/customer-deposit 
+form_name: TfmARDP
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/customer/customer-due-document/intro.md b/docs/quick-start/customer/customer-due-document/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true 
 slug: /quick-start/customer/customer-due-document 
+form_name: TrfmARDueDocument
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/customer/customer-payment/intro.md b/docs/quick-start/customer/customer-payment/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true 
 slug: /quick-start/customer/customer-payment 
+form_name: TfmARPM
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/customer/customer-refund/intro.md b/docs/quick-start/customer/customer-refund/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true 
 slug: /quick-start/customer/customer-refund 
+form_name: TfmARCF
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/customer/customer-statement/intro.md b/docs/quick-start/customer/customer-statement/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true 
 slug: /quick-start/customer/customer-statement 
+form_name: TrfmARStatement
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/gl/cash-book-entry/intro.md b/docs/quick-start/gl/cash-book-entry/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true
 slug: /quick-start/gl/cash-book-entry 
+form_name: TfmGLCB 
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/gl/journal-entry/intro.md b/docs/quick-start/gl/journal-entry/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true
 slug: /quick-start/gl/journal-entry 
+form_name: TfmGLJE
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/purchase/cash-purchase/intro.md b/docs/quick-start/purchase/cash-purchase/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true
 slug: /quick-start/purchase/cash-purchase 
+form_name: TfmPHCP
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/purchase/goods-received/intro.md b/docs/quick-start/purchase/goods-received/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true
 slug: /quick-start/purchase/goods-received  
+form_name: TfmPHGR
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/purchase/purchase-cancelled-note/intro.md b/docs/quick-start/purchase/purchase-cancelled-note/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true
 slug: /quick-start/purchase/purchase-cancelled-note
+form_name: TfmPHPC
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/purchase/purchase-debit-note/intro.md b/docs/quick-start/purchase/purchase-debit-note/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true
 slug: /quick-start/purchase/purchase-debit-note
+form_name: TfmPHSD
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/purchase/purchase-invoice/intro.md b/docs/quick-start/purchase/purchase-invoice/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true
 slug: /quick-start/purchase/purchase-invoice
+form_name: TfmPHPI
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/purchase/purchase-order/intro.md b/docs/quick-start/purchase/purchase-order/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true
 slug: /quick-start/purchase/purchase-order 
+form_name: TfmPHPO
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/purchase/purchase-request/intro.md b/docs/quick-start/purchase/purchase-request/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true
 slug: /quick-start/purchase/purchase-request 
+form_name: TfmPHPQ
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/purchase/purchase-returned/intro.md b/docs/quick-start/purchase/purchase-returned/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true
 slug: /quick-start/purchase/purchase-returned 
+form_name: TfmPHSC
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/sales/cash-sales/intro.md b/docs/quick-start/sales/cash-sales/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true 
 slug: /quick-start/sales/cash-sales 
+form_name: TfmSLCS
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/sales/sales-cancelled-note/intro.md b/docs/quick-start/sales/sales-cancelled-note/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true 
 slug: /quick-start/sales/sales-cancelled-note 
+form_name: TfmSLCC
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/sales/sales-credit-note/intro.md b/docs/quick-start/sales/sales-credit-note/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true 
 slug: /quick-start/sales/sales-credit-note 
+form_name: TfmSLCN
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/sales/sales-debit-note/intro.md b/docs/quick-start/sales/sales-debit-note/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true 
 slug: /quick-start/sales/sales-debit-note 
+form_name: TfmSLDN
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/sales/sales-delivery-order/intro.md b/docs/quick-start/sales/sales-delivery-order/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true 
 slug: /quick-start/sales/sales-delivery-order 
+form_name: TfmSLDO
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/sales/sales-invoice/intro.md b/docs/quick-start/sales/sales-invoice/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true 
 slug: /quick-start/sales/sales-invoice 
+form_name: TfmSLIV
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/sales/sales-order/intro.md b/docs/quick-start/sales/sales-order/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true  
 slug: /quick-start/sales/sales-order 
+form_name: TfmSLSO
 ---
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docs/quick-start/sales/sales-quotation/intro.md b/docs/quick-start/sales/sales-quotation/intro.md
@@ -3,6 +3,7 @@ sidebar_position: 1
 title: Table of contents
 hide_title: true  
 slug: /quick-start/sales/sales-quotation
+form_name: TfmSLQT
 --- 
 
 import {TOC} from '@src/components/toc.js';
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -31,6 +31,13 @@ const config = {
   },
   plugins: [
     "plugin-image-zoom",
+    [
+      path.resolve(__dirname, 'plugins/generate-help-json'),
+      {
+        docsPath: 'docs',
+        outputPath: '/'
+      },
+    ],
     function aliasPlugin(context, options) {
       return {
         name: 'alias-plugin',
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -20,6 +20,7 @@
     "@easyops-cn/docusaurus-search-local": "^0.40.1",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
+    "gray-matter": "^4.0.3",
     "plugin-image-zoom": "github:flexanalytics/plugin-image-zoom",
     "prism-react-renderer": "^2.3.0",
     "qrcode.react": "^4.2.0",
diff --git a/plugins/generate-help-json/index.js b/plugins/generate-help-json/index.js
@@ -0,0 +1,102 @@
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+
+function getAllMarkdownFiles(dir, fileList = []) {
+  const files = fs.readdirSync(dir);
+  
+  files.forEach(file => {
+    const filePath = path.join(dir, file);
+    if (fs.statSync(filePath).isDirectory()) {
+      getAllMarkdownFiles(filePath, fileList);
+    } else if (file.endsWith('.md') || file.endsWith('.mdx')) {
+      fileList.push(filePath);
+    }
+  });
+  
+  return fileList;
+}
+
+module.exports = function(context, options) {
+  return {
+    name: 'generate-help-json',
+    
+    async postBuild({ siteConfig, routesPaths, outDir }) {
+      let docsDir;
+      docsDir = path.join(context.siteDir, options.docsPath);
+      if (!fs.existsSync(docsDir)) {
+        console.warn(`Warning: Docs directory not found: ${docsDir}`);
+        return;
+      }
+      
+      const markdownFiles = getAllMarkdownFiles(docsDir);
+      const helpData = [];
+      const formNameMap = {}; 
+      const duplicates = []; 
+      
+      for (const fullPath of markdownFiles) {
+        const filePath = path.relative(docsDir, fullPath);
+        const fileContent = fs.readFileSync(fullPath, 'utf8');
+        
+        try {
+          const { data: frontMatter } = matter(fileContent);
+          
+          if (frontMatter && frontMatter.form_name) {
+            let permalink = frontMatter.slug;
+            if (!permalink) {
+              console.warn(`WARNING: No slug found for ${filePath}`);
+            }
+            
+            if (formNameMap[frontMatter.form_name]) {
+              duplicates.push({
+                form_name: frontMatter.form_name,
+                existingFile: formNameMap[frontMatter.form_name],
+                newFile: filePath
+              });
+
+              console.warn(`WARNING: Duplicate form_name "${frontMatter.form_name}" found in:`);
+              console.warn(`  1. ${formNameMap[frontMatter.form_name]}`);
+              console.warn(`  2. ${filePath}`);
+              console.warn(`  Using the first occurrence for help.json`);
+
+              continue;
+            }
+            
+            formNameMap[frontMatter.form_name] = filePath;
+            
+            helpData.push({
+              Name: frontMatter.form_name,
+              Path: permalink
+            });
+          }
+        } catch (err) {
+          console.warn(`Error processing ${filePath}:`, err);
+        }
+      }
+      
+      let targetDir = outDir;
+      const outputPath = path.join(outDir, options.outputPath);
+
+      if (fs.existsSync(outputPath) && fs.statSync(outputPath).isDirectory()) {
+        targetDir = outputPath;
+      }
+
+      const helpJsonPath = path.join(targetDir, 'help.json');
+      fs.writeFileSync(
+        helpJsonPath, 
+        JSON.stringify(helpData, null, 2)
+      );
+
+      if (duplicates.length > 0) {
+        const duplicatesPath = path.join(targetDir, 'help-duplicates.json');
+        fs.writeFileSync(
+          duplicatesPath,
+          JSON.stringify(duplicates, null, 2)
+        );
+        console.warn(`Found ${duplicates.length} duplicate form_name entries. See help-duplicates.json for details.`);
+      }
+
+      console.log(`Generated HELP.json with ${helpData.length} entries in ${targetDir}`);
+    }
+  };
+};

Original file line number	Diff line number	Diff line change
`@@ -1,8 +1,8 @@`
`1`	`1`	`{`
`2`		`- "label": "Customer Refund",`
	`2`	`+ "label": "Customer",`
`3`	`3`	`"position": 3,`
`4`	`4`	`"link": {`
`5`	`5`	`"type": "generated-index",`
`6`		`- "description": "Learn on Customer Refund in SQL Account"`
	`6`	`+ "description": "Learn on Customer in SQL Account"`
`7`	`7`	`}`
`8`	`8`	`}`