fix: Expose additional vitepress sidebar options

.changeset/stale-coats-perform.md

@@ -0,0 +1,5 @@
+---
+"typedoc-vitepress-theme": patch
+---
+
+- Exposed additional sidebar options

.github/workflows/ci.typedoc-vitepress-theme.yml

@@ -0,0 +1,35 @@
+name: CI [typedoc-vitepress-theme]
+on:
+  push:
+    paths:
+      - 'packages/typedoc-vitepress-theme/**'
+      - '!packages/typedoc-vitepress-theme/README.md'
+      - '!packages/typedoc-vitepress-theme/package.json'
+  pull_request:
+    paths:
+      - 'packages/typedoc-vitepress-theme/**'
+      - '!packages/typedoc-vitepress-theme/README.md'
+      - '!packages/typedoc-vitepress-theme/package.json'
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: ['18']
+    name: Node ${{ matrix.node }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Set up Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node }}
+          cache: 'npm'
+      - name: Install
+        run: npm install
+      - name: Lint
+        run: npm run lint --workspace typedoc-vitepress-theme
+      - name: Build
+        run: npm run build --workspace typedoc-plugin-markdown --workspace typedoc-vitepress-theme
+      - name: Test
+        run: npm run test --workspace typedoc-vitepress-theme

dev-packages/prebuild-options/tasks/generate-docs.ts

@@ -116,7 +116,7 @@ export async function generateDocs(docsConfig: DocsConfig) {
 
         if (
           option.type === ParameterType.Mixed &&
-          option.defaultValue?.length
+          (!Array.isArray(option.defaultValue) || option.defaultValue?.length)
         ) {
           out.push('Below is the full list of keys and default values:');
         }

docs/pages/options.mdx

@@ -390,6 +390,8 @@ Keys are categorised with the following namespace conventions:
 
 Only keys that require translation need to be added to the object.
 
+Below is the full list of keys and default values:
+
 
 ```json filename="typedoc.json"
 {

docs/pages/themes/vitepress/options.mdx

@@ -18,14 +18,24 @@ Set to `false` to disable sidebar generation. Defaults to true.
 
 Eenables backward compatibility with VuePress. Available options [`"vitepress"`, `"vuepress1"`, `"vuepress2"`]. Defaults to `"vitepress"`.
 
+**sidebar.collapse**
+
+Determines if sidebar items with children are open or closed. Set `collapse` to `false` to set sidebar items as open by default.
+
+**sidebar.pretty**
+
+Pretty format the sidebar JSON.
+
 Below is the full list of keys and default values:
 
 
 ```json filename="typedoc.json"
 {
   "sidebar": {
     "autoConfiguration": true,
-    "format": "vitepress"
+    "format": "vitepress",
+    "pretty": false,
+    "collapse": true
   }
 }
 

examples/vitepress/typedoc.json

@@ -4,5 +4,9 @@
   "plugin": [
     "../../packages/typedoc-plugin-markdown/dist",
     "../../packages/typedoc-vitepress-theme/dist"
-  ]
+  ],
+  "sidebar": {
+    "collapse": false,
+    "pretty": true
+  }
 }

packages/typedoc-vitepress-theme/jest.config.js

@@ -2,6 +2,5 @@ const base = require('../../jest.config.base.js');
 
 module.exports = {
   ...base,
-  name: 'vuepress-plugin-typedoc',
-  displayName: 'vuepress-plugin-typedoc',
+  displayName: 'typedoc-vitepress-theme',
 };

packages/typedoc-vitepress-theme/package.json

@@ -22,7 +22,10 @@
     "prebuild": "rm -rf dist && prebuild-options",
     "build": "tsc",
     "predocs": "npm run build",
-    "docs": "rm -rf ./demo && npm run build && typedoc"
+    "docs": "rm -rf ./demo && npm run build && typedoc",
+    "build-and-test": "npm run build && npm run test",
+    "pretest": "ts-node ./test/__scripts__/prepare.ts",
+    "test": "jest"
   },
   "peerDependencies": {
     "typedoc-plugin-markdown": ">=4.0.0-next.39"

packages/typedoc-vitepress-theme/src/index.ts

@@ -52,7 +52,12 @@ export function load(app: Application) {
           basePath,
           sidebarOptions,
         );
-        fs.writeFileSync(sidebarPath, JSON.stringify(sidebarJson, null, 2));
+        fs.writeFileSync(
+          sidebarPath,
+          sidebarOptions.pretty
+            ? JSON.stringify(sidebarJson, null, 2)
+            : JSON.stringify(sidebarJson),
+        );
       }
     },
   );

packages/typedoc-vitepress-theme/src/options.ts

@@ -1,4 +1,6 @@
 export const DEFAULT_SIDEBAR_OPTIONS = {
   autoConfiguration: true,
   format: 'vitepress',
+  pretty: false,
+  collapse: true,
 };

packages/typedoc-vitepress-theme/src/options/declarations.ts

@@ -9,6 +9,15 @@ import { DEFAULT_SIDEBAR_OPTIONS } from '../options';
  * **sidebar.format**
  *
  * Eenables backward compatibility with VuePress. Available options [`"vitepress"`, `"vuepress1"`, `"vuepress2"`]. Defaults to `"vitepress"`.
+ *
+ * **sidebar.collapse**
+ *
+ * Determines if sidebar items with children are open or closed. Set `collapse` to `false` to set sidebar items as open by default.
+ *
+ * **sidebar.pretty**
+ *
+ * Pretty format the sidebar JSON.
+ *
  */
 export const sidebar = {
   help: 'Configures the autogenerated VitePress sidebar.',

packages/typedoc-vitepress-theme/src/options/models.ts

@@ -15,4 +15,6 @@ export interface PluginOptions {
 export interface Sidebar {
   autoConfiguration: string;
   format: string;
+  pretty: string;
+  collapse: string;
 }

packages/typedoc-vitepress-theme/src/sidebars/sidebar.vitepress.ts

@@ -1,20 +1,28 @@
 import { NavigationItem } from 'typedoc-plugin-markdown';
+import { Sidebar } from '../options/models';
 
-export = (navigation: NavigationItem[], basePath: string) => {
+export = (navigation: NavigationItem[], basePath: string, options: Sidebar) => {
   return navigation.map((navigationItem) => {
-    return getNavigationItem(navigationItem, basePath);
+    return getNavigationItem(navigationItem, basePath, options);
   });
 };
 
-function getNavigationItem(navigationItem: NavigationItem, basePath: string) {
+function getNavigationItem(
+  navigationItem: NavigationItem,
+  basePath: string,
+  options: Sidebar,
+) {
+  const hasChildren = navigationItem.children?.length;
   return {
     text: navigationItem.title,
     ...(Boolean(navigationItem.url) && {
       link: `/${basePath}/${navigationItem.url}`,
     }),
-    collapsed: true,
-    items: navigationItem.children?.map((group) => {
-      return getNavigationItem(group, basePath);
+    ...(hasChildren && { collapsed: options.collapse }),
+    ...(hasChildren && {
+      items: navigationItem.children?.map((group) =>
+        getNavigationItem(group, basePath, options),
+      ),
     }),
   };
 }

packages/typedoc-vitepress-theme/src/sidebars/sidebars.ts

@@ -15,5 +15,5 @@ export function getSidebar(
   if (options.format === 'vuepress2') {
     return sidebarVuepress2(navigation, basePath);
   }
-  return sidebarVitepress(navigation, basePath);
+  return sidebarVitepress(navigation, basePath, options);
 }

packages/typedoc-vitepress-theme/test/__scripts__/prepare.ts

@@ -0,0 +1,47 @@
+import { spawn } from 'child_process';
+import { consola } from 'consola';
+import * as fs from 'fs-extra';
+
+const timeStart = new Date().getTime();
+
+consola.start(`Building test fixtures...`);
+
+// remove output dir
+fs.removeSync(`./test/out`);
+
+const fixtures = [
+  { options: 'typedoc.base.json', outDir: 'default' },
+  { options: 'typedoc.sidebar-options.json', outDir: 'sidebar-options' },
+];
+
+// write fixtures
+fixtures.forEach((fixture) => {
+  writeMarkdown(fixture);
+});
+
+function writeMarkdown(fixture: any) {
+  spawn(
+    'typedoc',
+    [
+      ...[
+        '-options',
+        `./test/${fixture.options}`,
+        '-logLevel',
+        'Info',
+        '-out',
+        `./test/out/${fixture.outDir}`,
+      ],
+    ],
+    {
+      stdio: 'inherit',
+    },
+  );
+}
+process.on('exit', () => {
+  consola.success(
+    `Finished building fixtures in ${(
+      (new Date().getTime() - timeStart) /
+      1000
+    ).toFixed(2)} seconds`,
+  );
+});

packages/typedoc-vitepress-theme/test/specs/__snapshots__/vitepress.spec.ts.snap

@@ -0,0 +1,76 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`VitePress should generate typedoc sidebar 1`] = `"[{"text":"module-1","link":"/test/out/default/module-1/index.md","collapsed":true,"items":[{"text":"Classes","collapsed":true,"items":[{"text":"ClassA","link":"/test/out/default/module-1/classes/ClassA.md"},{"text":"ClassB","link":"/test/out/default/module-1/classes/ClassB.md"},{"text":"InterfaceA","link":"/test/out/default/module-1/classes/InterfaceA.md"},{"text":"InterfaceB","link":"/test/out/default/module-1/classes/InterfaceB.md"}]}]},{"text":"module-2","link":"/test/out/default/module-2/index.md","collapsed":true,"items":[{"text":"Classes","collapsed":true,"items":[{"text":"ClassA","link":"/test/out/default/module-2/classes/ClassA.md"},{"text":"ClassB","link":"/test/out/default/module-2/classes/ClassB.md"},{"text":"InterfaceA","link":"/test/out/default/module-2/classes/InterfaceA.md"},{"text":"InterfaceB","link":"/test/out/default/module-2/classes/InterfaceB.md"}]}]}]"`;
+
+exports[`VitePress should generate typedoc sidebar with options 1`] = `
+"[
+  {
+    "text": "module-1",
+    "link": "/test/out/sidebar-options/module-1/index.md",
+    "collapsed": false,
+    "items": [
+      {
+        "text": "Classes",
+        "collapsed": false,
+        "items": [
+          {
+            "text": "ClassA",
+            "link": "/test/out/sidebar-options/module-1/classes/ClassA.md"
+          },
+          {
+            "text": "ClassB",
+            "link": "/test/out/sidebar-options/module-1/classes/ClassB.md"
+          },
+          {
+            "text": "InterfaceA",
+            "link": "/test/out/sidebar-options/module-1/classes/InterfaceA.md"
+          },
+          {
+            "text": "InterfaceB",
+            "link": "/test/out/sidebar-options/module-1/classes/InterfaceB.md"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "text": "module-2",
+    "link": "/test/out/sidebar-options/module-2/index.md",
+    "collapsed": false,
+    "items": [
+      {
+        "text": "Classes",
+        "collapsed": false,
+        "items": [
+          {
+            "text": "ClassA",
+            "link": "/test/out/sidebar-options/module-2/classes/ClassA.md"
+          },
+          {
+            "text": "ClassB",
+            "link": "/test/out/sidebar-options/module-2/classes/ClassB.md"
+          },
+          {
+            "text": "InterfaceA",
+            "link": "/test/out/sidebar-options/module-2/classes/InterfaceA.md"
+          },
+          {
+            "text": "InterfaceB",
+            "link": "/test/out/sidebar-options/module-2/classes/InterfaceB.md"
+          }
+        ]
+      }
+    ]
+  }
+]"
+`;
+
+exports[`VitePress should output docs with vitepress theme 1`] = `
+"# typedoc-vitepress-theme
+
+## Modules
+
+- [module-1](module-1/index.md)
+- [module-2](module-2/index.md)
+"
+`;

packages/typedoc-vitepress-theme/test/specs/vitepress.spec.ts

@@ -0,0 +1,26 @@
+import * as fs from 'fs';
+import * as path from 'path';
+describe(`VitePress`, () => {
+  test(`should output docs with vitepress theme`, async () => {
+    const contents = fs
+      .readFileSync(path.join(__dirname, '../out/default/index.md'))
+      .toString();
+    expect(contents).toMatchSnapshot();
+  });
+
+  test(`should generate typedoc sidebar`, async () => {
+    const contents = fs
+      .readFileSync(path.join(__dirname, '../out/default/typedoc-sidebar.json'))
+      .toString();
+    expect(contents).toMatchSnapshot();
+  });
+
+  test(`should generate typedoc sidebar with options`, async () => {
+    const contents = fs
+      .readFileSync(
+        path.join(__dirname, '../out/sidebar-options/typedoc-sidebar.json'),
+      )
+      .toString();
+    expect(contents).toMatchSnapshot();
+  });
+});

packages/typedoc-vitepress-theme/test/stubs/module-1.ts

@@ -0,0 +1,5 @@
+export class ClassA {}
+export class ClassB {}
+
+export class InterfaceA {}
+export class InterfaceB {}

packages/typedoc-vitepress-theme/test/stubs/module-2.ts

@@ -0,0 +1,5 @@
+export class ClassA {}
+export class ClassB {}
+
+export class InterfaceA {}
+export class InterfaceB {}

packages/typedoc-vitepress-theme/test/stubs/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "esModuleInterop": true,
+    "lib": ["es2020", "dom"],
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "noImplicitAny": false,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "strictNullChecks": false,
+    "target": "es2020"
+  }
+}

packages/typedoc-vitepress-theme/test/typedoc.base.json

@@ -0,0 +1,13 @@
+{
+  "entryPoints": ["./stubs/*.ts"],
+  "tsconfig": "./stubs/tsconfig.json",
+  "out": "./out",
+  "plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme"],
+  "readme": "none",
+  "githubPages": false,
+  "disableSources": true,
+  "cleanOutputDir": true,
+  "hideGenerator": true,
+  "hidePageHeader": true,
+  "hideBreadcrumbs": true
+}