Automated README.md generator & individual item files

.github/workflows/build-readme.yml

@@ -0,0 +1,37 @@
+name: Build README.md
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - main
+
+jobs:
+  build:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: ./.website
+
+      - name: Build README
+        run: npm run build-readme
+        working-directory: ./.website
+
+      - name: Commit and push changes
+        run: |
+          git diff
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git commit -am "Update README.md" || echo "No changes to commit"
+          git push

.website/build-readme.cjs

@@ -0,0 +1,131 @@
+// This script is used to build the README file by combining the header, sections, and contribute files with the items files.
+
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+
+// Function to sanitize names for use in links
+function sanitizeName(name) {
+    name = name.trim()
+        .toLowerCase()
+        .replace(/ /g, '-')
+        .replace(/&/g, 'and')
+        .replace(/[^\w-]+/g, '');
+    return encodeURIComponent(name)
+}
+
+// Start the content with the header
+let content = fs.readFileSync(path.join(__dirname, '../partials/header.md'), 'utf8');
+
+// Read the sections file
+const sectionsFilePath = path.join(__dirname, '../partials/sections.md');
+const sectionsFileContent = fs.readFileSync(sectionsFilePath, 'utf-8');
+const {sections, categories} = matter(sectionsFileContent).data;
+
+// Add the table of contents
+content += '\n## Table of Contents\n';
+for (const section of sections) {
+    content += '- [' + section.name + '](#' + sanitizeName(section.name) + ')\n';
+    if (section.name === 'Tools') {
+        for (const category of categories) {
+            content += '    - [' + category.name + '](#' + sanitizeName(category.name) + ')\n';
+        }
+    }
+}
+// Add the contribute link to the table of contents
+content += '- [Contribute](#contribute)\n';
+content += '\n';
+
+// Add the sections to the content
+for (const section of sections) {
+    content += '## ' + section.name + '\n';
+    if (section.description) {
+        content += section.description + '\n';
+    }
+
+    // Add the items for this section to the content
+    const itemsDir = path.join(__dirname, '../items');
+    const sectionDirs = fs.readdirSync(itemsDir);
+    let items = [];
+    for (const sectionDir of sectionDirs) {
+        const sectionDirPath = path.join(itemsDir, sectionDir);
+        if (fs.statSync(sectionDirPath).isDirectory()) {
+            const itemFiles = fs.readdirSync(sectionDirPath);
+            for (const itemFile of itemFiles) {
+                const itemFilePath = path.join(sectionDirPath, itemFile);
+                const itemFileContent = fs.readFileSync(itemFilePath, 'utf-8');
+                const item = matter(itemFileContent).data;
+
+                // Check if the item's section matches the current section
+                if (item.section === section.name) {
+                    // Check if the item's category is valid or if it doesn't have a category
+                    if (!item.category || categories.find(category => category.name === item.category)) {
+                        items.push(item);
+                    }
+                }
+            }
+        }
+    }
+
+    // Group the items by category if the section is Tools
+    const itemsByCategory = items.reduce((groups, item) => {
+        if (item.category) {
+            if (!groups[item.category]) {
+                groups[item.category] = [];
+            }
+            groups[item.category].push(item);
+        }
+        return groups;
+    }, {});
+
+    // Add the items to the content
+    if (section.name === 'Tools') {
+        for (const category of categories) {
+            content += '### ' + category.name + '\n';
+            if (category.description) {
+                // Uncomment this line to add the category description to the content
+                //content += category.description + '\n';
+            }
+            if (itemsByCategory[category.name]) {
+                itemsByCategory[category.name].sort((a, b) => {
+                    if (a.order && b.order) {
+                        return a.order - b.order;
+                    } else {
+                        return a.name.localeCompare(b.name);
+                    }
+                });
+                for (const item of itemsByCategory[category.name]) {
+                    content += '- [' + item.name + '](' + item.link + ') - ' + item.description + '\n';
+                }
+            }
+            content += '\n';
+        }
+    } else {
+
+        // Sort the items by order if it exists, otherwise by name
+        items.sort((a, b) => {
+            if (a.order && b.order) {
+                return a.order - b.order;
+            } else {
+                return a.name.localeCompare(b.name);
+            }
+        });
+
+        // Add the items to the content
+        for (const item of items) {
+            content += '- [' + item.name + '](' + item.link + ') - ' + item.description + '\n';
+        }
+
+        content += '\n';
+
+    }
+
+}
+
+// Add the contribution section
+const contributePath = path.join(__dirname, '../partials/contribute.md');
+const contributeContent = fs.readFileSync(contributePath, 'utf-8');
+content += contributeContent;
+
+// Write the combined content to the README file
+fs.writeFileSync(path.join(__dirname, '../README.md'), content);

.website/package.json

@@ -5,12 +5,14 @@
     "build": "nuxt build",
     "dev": "nuxt dev",
     "generate": "nuxt generate",
-    "preview": "nuxt preview"
+    "preview": "nuxt preview",
+    "build-readme": "node build-readme.cjs"
   },
   "dependencies": {
     "@nuxt/content": "^2.12.1",
     "@nuxtjs/tailwindcss": "^6.11.4",
     "@tailwindcss/typography": "^0.5.10",
+    "gray-matter": "^4.0.3",
     "nuxt": "^3.10.3"
   },
   "devDependencies": {