Sidebar changes + linter page (#18)

* wip

* generating linter overview based on linter readme

* build ci

* wip

* wip

* ci fix

.github/workflows/build.yaml

@@ -0,0 +1,36 @@
+---
+name: build
+on:
+  pull_request:
+    branches:
+      - main
+
+# Recommended by https://github.com/JamesIves/github-pages-deploy-action
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container: node:20
+    steps:
+      - uses: actions/checkout@v3
+      - name: Clone aep.dev
+        uses: actions/checkout@v3
+        with:
+          repository: aep-dev/aep.dev
+          path: './aep-dev'
+      - name: Clone Proto linter
+        uses: actions/checkout@v3
+        with:
+          repository: aep-dev/api-linter
+          path: './api-linter'
+      - name: Create rules folder
+        run: mkdir -p src/content/docs/tooling/linter/rules
+      - name: Install all dependencies.
+        run: npm install
+      - name: Generate all static pages.
+        run: AEP_LOCATION=./aep-dev AEP_LINTER_LOC=./api-linter npm run generate
+      - name: Install, build, and upload your site output
+        uses: withastro/action@v2

.github/workflows/publish.yaml

@@ -29,7 +29,7 @@ jobs:
           repository: aep-dev/api-linter
           path: './api-linter'
       - name: Create rules folder
-        run: mkdir src/content/docs/tooling/linter/rules
+        run: mkdir -p src/content/docs/tooling/linter/rules
       - name: Install all dependencies.
         run: npm install
       - name: Generate all static pages.

scripts/generate.ts

@@ -3,9 +3,9 @@ import * as path from 'path';
 import { load, dump } from "js-yaml";
 
 import loadConfigFiles from './src/config';
-import { buildSidebar, buildLinterSidebar } from './src/sidebar';
-import type { AEP, ConsolidatedLinterRule, GroupFile, LinterRule, Markdown } from './src/types';
-import { buildMarkdown } from './src/markdown';
+import { buildSidebar, buildLinterSidebar, addToSidebar } from './src/sidebar';
+import { type AEP, type ConsolidatedLinterRule, type GroupFile, type LinterRule, type Sidebar } from './src/types';
+import { buildMarkdown, Markdown } from './src/markdown';
 
 const AEP_LOC = process.env.AEP_LOCATION!;
 const AEP_LINTER_LOC = process.env.AEP_LINTER_LOC!;
@@ -30,28 +30,31 @@ async function getLinterRules(dirPath: string): Promise<string[]> {
   return folders;
 }
 
-async function writePage(dirPath: string, filename: string) {
-  let contents = fs.readFileSync(path.join(dirPath, filename), 'utf-8')
+async function writePage(dirPath: string, filename: string, outputPath: string, title: string) {
+  let contents = new Markdown(fs.readFileSync(path.join(dirPath, filename), 'utf-8'));
   let frontmatter = {
-    'title': getTitle(contents.toString())
+    'title': title ?? getTitle(contents.contents)
   }
   let final = `---
 ${dump(frontmatter)}
 ---
-${contents}`
-  fs.writeFileSync(path.join("src/content/docs", filename), final, { flag: 'w' });
+${contents.removeTitle().contents}`
+  fs.writeFileSync(outputPath, final, { flag: 'w' });
 }
 
-async function writePages(dirPath: string) {
+async function writePages(dirPath: string, sidebar: Sidebar): Promise<Sidebar> {
   const entries = await fs.promises.readdir(path.join(dirPath, "pages/general/"), { withFileTypes: true });
 
   let files = entries
     .filter(entry => entry.isFile() && entry.name.endsWith('.md'))
 
   for (var file of files) {
-    writePage(path.join(dirPath, "pages/general"), file.name);
+    writePage(path.join(dirPath, "pages/general"), file.name, path.join("src/content/docs", file.name));
+    addToSidebar(sidebar, "Overview", [file.name.replace('.md', '')])
   }
-  writePage(dirPath, "CONTRIBUTING.md");
+  writePage(dirPath, "CONTRIBUTING.md", path.join("src/content/docs", "contributing.md"));
+  addToSidebar(sidebar, "Overview", ["contributing"]);
+  return sidebar;
 }
 
 function readAEP(dirPath: string): string[] {
@@ -248,7 +251,6 @@ let aeps = await assembleAEPs();
 
 // Build sidebar.
 let sidebar = buildSidebar(aeps, readGroupFile(AEP_LOC));
-writeSidebar(sidebar, "sidebar.json");
 
 let full_aeps = buildFullAEPList(aeps);
 writeSidebar(full_aeps, "full_aeps.json");
@@ -260,7 +262,12 @@ for (var aep of aeps) {
 }
 
 // Write assorted pages.
-writePages(AEP_LOC);
+sidebar = await writePages(AEP_LOC, sidebar);
+
+// Write linter pages.
+await writePage(AEP_LINTER_LOC, "README.md", "src/content/docs/tooling/linter/index.md", "Protobuf Linter")
+
+writeSidebar(sidebar, "sidebar.json");
 
 // Write out linter rules.
 let linter_rules = await assembleLinterRules();

scripts/src/sidebar.ts

@@ -6,7 +6,7 @@ function buildLinterSidebar(rules: ConsolidatedLinterRule[]): Sidebar {
     label: 'Tooling',
     items: [
       {
-          'label': 'Linter',
+          'label': 'Protobuf Linter',
           'items': [
             'tooling/linter',
             {
@@ -22,7 +22,7 @@ function buildLinterSidebar(rules: ConsolidatedLinterRule[]): Sidebar {
 }
 
 function buildSidebar(aeps: AEP[], groups: any): Sidebar {
-  let response = [];
+  let response = [{'label': 'Overview', 'items':[]}];
 
   for (var group of groups.categories) {
     response.push({
@@ -33,4 +33,16 @@ function buildSidebar(aeps: AEP[], groups: any): Sidebar {
   return response as Sidebar;
 }
 
-export { buildSidebar, buildLinterSidebar };
+function addToSidebar(sidebar: Sidebar, label: string, items: string[]): Sidebar {
+  const targetGroupIndex = sidebar.findIndex(group => group.label === label);
+  if (targetGroupIndex != -1) {
+    if (Array.isArray(sidebar[targetGroupIndex].items)) {
+      sidebar[targetGroupIndex].items.push(...items);
+    } else {
+      sidebar[targetGroupIndex].items = items;
+    }
+  }
+  return sidebar;
+}
+
+export { buildSidebar, buildLinterSidebar, addToSidebar };