vuepress-jsdoc 4.3.1 → 6.1.0

package/dist/lib/vue-sidebar.js

@@ -1,82 +1,125 @@
-"use strict";
-var __values = (this && this.__values) || function(o) {
-    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
-    if (m) return m.call(o);
-    if (o && typeof o.length === "number") return {
-        next: function () {
-            if (o && i >= o.length) o = void 0;
-            return { value: o && o[i++], done: !o };
-        }
-    };
-    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
-};
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateVueSidebar = void 0;
 /*
  * @vuepress
  * ---
  * headline: lib/vue-sidebar.ts
  * ---
  */
-var fs_1 = __importDefault(require("fs"));
-var path_1 = require("path");
+import fs from 'node:fs';
+import path from 'node:path';
+import { SIDEBAR_TITLE_PLACEHOLDER } from '../constants.js';
+import { getPageName, normalizePath } from './list-folder.js';
 /**
- * Runs through the given tree structure and creates a vuepress config
- * @param {object} data Informations to build config
- * @param {array} data.fileTree tree strcture
- * @param {string} data.codeFolder ./code/ folder
- * @param {string} data.srcFolder ./src/ folder
- * @param {string} data.docsFolder ./documentation/ folder
- * @param {string} data.title title string
- * @returns {object} returns the vuepress menu strcture
+ * Get the route of the generated folder, e.g. `/code/`
+ * @param {string} codeFolder
+ * @returns {string}
  */
-var generateVueSidebar = function (_a) {
-    var _b;
-    var fileTree = _a.fileTree, codeFolder = _a.codeFolder, srcFolder = _a.srcFolder, docsFolder = _a.docsFolder, title = _a.title;
-    var rootFiles = [['', '::vuepress-jsdoc-title::']];
-    rootFiles = rootFiles.concat(fileTree.filter(function (file) { return !file.children; }).map(function (file) { return file.name; }));
-    var rootFolder = fileTree.filter(function (file) { return file.children && file.children.length > 0; });
-    var buildChildren = function (children, name, depth) {
-        var e_1, _a;
-        var newChildren = [];
-        try {
-            for (var children_1 = __values(children), children_1_1 = children_1.next(); !children_1_1.done; children_1_1 = children_1.next()) {
-                var child = children_1_1.value;
-                if (child.children && child.children.length > 0) {
-                    newChildren = newChildren.concat(buildChildren(child.children, child.name, depth + 1));
-                }
-                else if (child.fullPath) {
-                    if (fs_1.default.existsSync((0, path_1.join)(docsFolder, child.fullPath.replace(srcFolder, '')) + '.md')) {
-                        newChildren.push(child.fullPath.replace("".concat(srcFolder, "/"), ''));
-                    }
+export const getSidebarBase = (codeFolder) => `/${normalizePath(codeFolder)}/`;
+/**
+ * Runs through the given tree structure and creates a vuepress 2 sidebar config.
+ * Only pages that were generated are linked. Folders become nested sidebar groups.
+ * @param {SidebarOptions} data Information to build config
+ * @returns {object} returns the vuepress sidebar structure
+ */
+export const generateVueSidebar = ({ fileTree, codeFolder, srcFolder, docsFolder, title, readmeTitle = SIDEBAR_TITLE_PLACEHOLDER, collapsible = false }) => {
+    const base = getSidebarBase(codeFolder);
+    const root = normalizePath(srcFolder);
+    const toLink = (file) => {
+        if (!file.fullPath)
+            return null;
+        const relativePath = path.posix.relative(root, normalizePath(file.fullPath));
+        if (!fs.existsSync(`${path.join(docsFolder, relativePath)}.md`))
+            return null;
+        return `${base}${relativePath}`;
+    };
+    const buildChildren = (children) => {
+        const items = [];
+        for (const child of children) {
+            if (child.children) {
+                const nested = buildChildren(child.children);
+                if (nested.length > 0) {
+                    items.push({ text: child.name, collapsible: true, children: nested });
                 }
             }
-        }
-        catch (e_1_1) { e_1 = { error: e_1_1 }; }
-        finally {
-            try {
-                if (children_1_1 && !children_1_1.done && (_a = children_1.return)) _a.call(children_1);
+            else {
+                const link = toLink(child);
+                if (link)
+                    items.push(link);
             }
-            finally { if (e_1) throw e_1.error; }
         }
-        return newChildren;
+        return items;
     };
-    var tree = rootFolder.map(function (folder) { return ({
-        title: folder.name,
-        collapsable: false,
-        children: buildChildren(folder.children, folder.name, 0)
-    }); });
-    return _b = {},
-        _b["/".concat(codeFolder, "/")] = [
-            {
-                title: title,
-                collapsable: false,
-                children: rootFiles
-            }
-        ].concat(tree),
-        _b;
+    const rootFiles = [
+        { text: readmeTitle, link: base },
+        ...buildChildren(fileTree.filter((file) => !file.children))
+    ];
+    const folders = fileTree
+        .filter((file) => file.children)
+        .map((folder) => ({ text: folder.name, collapsible, children: buildChildren(folder.children) }))
+        .filter((group) => group.children.length > 0);
+    return {
+        [base]: [{ text: title, collapsible, children: rootFiles }, ...folders]
+    };
+};
+/**
+ * Get the `title` of the frontmatter of a generated page (set with the `@vuepress` block)
+ * @param {string} mdPath path to the generated markdown file
+ * @returns {string|undefined}
+ */
+const readPageTitle = (mdPath) => {
+    const title = /^---\r?\n[\s\S]*?^title:\s*(.+?)\s*$[\s\S]*?^---/m.exec(fs.readFileSync(mdPath, 'utf-8'))?.[1];
+    return title?.replace(/^(['"])(.*)\1$/, '$2');
+};
+/**
+ * Runs through the given tree structure and creates a vitepress sidebar config.
+ * Vitepress needs the text of every link, so it is read from the generated page.
+ * @param {SidebarOptions} data Information to build config
+ * @returns {object} returns the vitepress sidebar structure
+ */
+export const generateVitepressSidebar = (data) => {
+    const base = getSidebarBase(data.codeFolder);
+    const root = normalizePath(data.srcFolder);
+    // the frontmatter title or the file name. Index files are shown as `index` instead of their prefixed page name.
+    const getText = (link) => {
+        const relativePath = link.slice(base.length);
+        const name = path.posix.basename(relativePath);
+        const isIndex = name === getPageName(path.posix.join(root, path.posix.dirname(relativePath)), 'index');
+        return readPageTitle(`${path.join(data.docsFolder, relativePath)}.md`) ?? (isIndex ? 'index' : name);
+    };
+    const toVitepressItem = (item, nested = true) => {
+        if (typeof item === 'string') {
+            return { text: getText(item), link: item };
+        }
+        if ('link' in item) {
+            return { text: item.text, link: item.link };
+        }
+        return {
+            text: item.text,
+            // nested folders are collapsed, vitepress opens groups with the active page.
+            // collapsible top level groups stay open.
+            ...(item.collapsible ? { collapsed: nested } : {}),
+            items: item.children.map((child) => toVitepressItem(child))
+        };
+    };
+    return { [base]: generateVueSidebar(data)[base].map((group) => toVitepressItem(group, false)) };
+};
+/**
+ * Create the content of the `config.js`, which is placed into the generated folder.
+ * It exports the file tree and a `sidebarTree(title)` function, which returns the vuepress or vitepress sidebar.
+ * @param {SidebarOptions} options
+ * @returns {string} javascript code (ES module)
+ */
+export const createSidebarConfig = (options) => {
+    // the placeholder is replaced with the `title` parameter of `sidebarTree`
+    const data = { ...options, readmeTitle: SIDEBAR_TITLE_PLACEHOLDER };
+    const tree = options.format === 'vitepress' ? generateVitepressSidebar(data) : generateVueSidebar(data);
+    const sidebar = JSON.stringify(tree, null, 2).replace(JSON.stringify(SIDEBAR_TITLE_PLACEHOLDER), 'title');
+    return [
+        '// This file is generated by vuepress-jsdoc. Do not edit it manually.',
+        `export const fileTree = ${JSON.stringify(options.fileTree, null, 2)};`,
+        '',
+        `export const sidebarTree = (title = 'Mainpage') => (${sidebar});`,
+        '',
+        'export default sidebarTree;',
+        ''
+    ].join('\n');
 };
-exports.generateVueSidebar = generateVueSidebar;

package/dist/lib/vuepress-plugin.d.ts

@@ -0,0 +1,48 @@
+import { CLIArguments } from '../interfaces.js';
+export interface VuepressJsdocPluginOptions extends Omit<CLIArguments, 'dist' | 'watch' | 'format' | 'config'> {
+    /**
+     * Add the generated sidebar to all generated pages (frontmatter `sidebar`).
+     * Disable it, if you configure the sidebar in your theme.
+     * @default true
+     */
+    sidebar?: boolean;
+    /**
+     * Text of the first sidebar entry, which links to the readme
+     * @default 'Readme'
+     */
+    sidebarTitle?: string;
+}
+/** Minimal parts of the vuepress app, which are used by the plugin */
+interface App {
+    dir: {
+        source: (...args: string[]) => string;
+    };
+    env: {
+        isDev: boolean;
+    };
+}
+interface Page {
+    path: string;
+    frontmatter: Record<string, unknown>;
+}
+/**
+ * VuePress 2 plugin, which generates the documentation when vuepress starts and
+ * updates it while `vuepress dev` is running. No separate CLI call is needed.
+ * @example
+ * import { vuepressJsdocPlugin } from 'vuepress-jsdoc';
+ *
+ * export default defineUserConfig({
+ *   plugins: [vuepressJsdocPlugin({ source: './src', folder: 'code' })]
+ * });
+ * @param {VuepressJsdocPluginOptions} pluginOptions
+ * @returns {Function} vuepress plugin
+ */
+export declare const vuepressJsdocPlugin: ({ sidebar, sidebarTitle, ...pluginOptions }?: VuepressJsdocPluginOptions) => (app: App) => {
+    name: string;
+    extendsMarkdownOptions: () => Promise<void>;
+    extendsPage: (page: Page) => Promise<void>;
+    onWatched: (_app: App, watchers: {
+        close: () => Promise<void> | void;
+    }[]) => void;
+};
+export {};

package/dist/lib/vuepress-plugin.js

@@ -0,0 +1,63 @@
+/*
+ * @vuepress
+ * ---
+ * headline: lib/vuepress-plugin.ts
+ * ---
+ */
+import path from 'node:path';
+import { generate, getSidebarOptions, parseArguments, watchFiles } from '../index.js';
+import { listFolder } from './list-folder.js';
+import { generateVueSidebar, getSidebarBase } from './vue-sidebar.js';
+/**
+ * VuePress 2 plugin, which generates the documentation when vuepress starts and
+ * updates it while `vuepress dev` is running. No separate CLI call is needed.
+ * @example
+ * import { vuepressJsdocPlugin } from 'vuepress-jsdoc';
+ *
+ * export default defineUserConfig({
+ *   plugins: [vuepressJsdocPlugin({ source: './src', folder: 'code' })]
+ * });
+ * @param {VuepressJsdocPluginOptions} pluginOptions
+ * @returns {Function} vuepress plugin
+ */
+export const vuepressJsdocPlugin = ({ sidebar = true, sidebarTitle = 'Readme', ...pluginOptions } = {}) => (app) => {
+    // generated files are written into the source folder of vuepress
+    const argv = {
+        ...pluginOptions,
+        dist: path.relative(process.cwd(), app.dir.source()) || '.',
+        format: 'vuepress',
+        watch: false
+    };
+    const options = parseArguments(argv);
+    const base = getSidebarBase(options.codeFolder);
+    let generated = null;
+    // the promise is cached, because all pages are extended at the same time
+    let sidebarCache = null;
+    const buildSidebar = async () => {
+        const { tree } = await listFolder(options.srcFolder, options.exclude, options.include);
+        return generateVueSidebar({ ...getSidebarOptions(options, tree), readmeTitle: sidebarTitle });
+    };
+    return {
+        name: 'vuepress-plugin-jsdoc',
+        // this hook runs before the pages are resolved, so the generated files become pages
+        extendsMarkdownOptions: async () => {
+            generated ??= generate(argv);
+            await generated;
+        },
+        extendsPage: async (page) => {
+            if (!sidebar || !page.path.startsWith(base) || page.frontmatter.sidebar !== undefined)
+                return;
+            sidebarCache ??= buildSidebar();
+            page.frontmatter.sidebar = await sidebarCache;
+        },
+        onWatched: (_app, watchers) => {
+            const watcher = watchFiles(argv);
+            // changed files can create or remove a page, which changes the sidebar
+            watcher.on('all', (event) => {
+                if (event !== 'addDir')
+                    sidebarCache = null;
+            });
+            watchers.push(watcher);
+        }
+    };
+};

package/package.json

@@ -1,21 +1,16 @@
 {
   "name": "vuepress-jsdoc",
-  "version": "4.3.1",
+  "version": "6.1.0",
   "description": "Generate jsdoc markdown files for vuepress",
+  "type": "module",
   "main": "dist/index.js",
-  "scripts": {
-    "test": "jest",
-    "test-coverage": "cross-env NODE_ENV=test jest --coverage",
-    "test-watch": "cross-env NODE_ENV=test jest --watchAll",
-    "lint": "eslint --ext .tsx,.ts,.json,.js src/ --fix",
-    "dev": "npm run build -- -w",
-    "build": "tsc",
-    "prepublishOnly": "npm i && npm run build",
-    "prepare": "husky install",
-    "version": "conventional-changelog -p karma -i CHANGELOG.md -s -r 0 && git add .",
-    "docs": "./bin/vuepress-jsdoc.js --source=./dist --partials=./example/partials/*.hbs --readme ./README.md --include=\"**/*.(ts|js)\" --exclude=\"**/*.d.ts,**/interfaces.*,**/constants.*\"",
-    "docs:dev": "npx concurrently --kill-others \"npm run dev\" \"npm run docs -- -w\" \"npx vuepress dev documentation\"",
-    "docs:build": "npm run build && npm run docs && npx vuepress build documentation"
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
   },
   "keywords": [
     "jsdoc",
@@ -25,7 +20,7 @@
     "vuepress"
   ],
   "engines": {
-    "node": ">=14"
+    "node": ">=22.22.0"
   },
   "license": "MIT",
   "author": "Philip Stapelfeldt <me@ph1p.dev>",
@@ -40,116 +35,74 @@
     "printWidth": 120,
     "trailingComma": "none"
   },
-  "jest": {
-    "coverageThreshold": {
-      "global": {
-        "branches": 95,
-        "functions": 60,
-        "lines": 75,
-        "statements": -10
-      }
-    },
-    "roots": [
-      "<rootDir>/src"
-    ],
-    "transform": {
-      "^.+\\.tsx?$": "ts-jest"
-    },
-    "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$",
-    "moduleFileExtensions": [
-      "ts",
-      "tsx",
-      "js",
-      "jsx",
-      "json",
-      "node"
-    ],
-    "bail": true,
-    "verbose": true,
-    "collectCoverageFrom": [
-      "**/*.{js,jsx,ts,tsx}",
-      "!**/node_modules/**",
-      "!**/coverage/**",
-      "!**/example/**",
-      "!**/vendor/**"
-    ],
-    "coverageDirectory": "./coverage"
-  },
+  "files": [
+    "bin",
+    "dist",
+    "template"
+  ],
   "bin": {
     "vuepress-jsdoc": "bin/vuepress-jsdoc.js"
   },
   "dependencies": {
-    "chalk": "^4.1.2",
-    "chokidar": "^3.5.3",
-    "commander": "^9.4.1",
-    "del": "^6.0.0",
+    "chokidar": "^6.0.0",
+    "commander": "^15.1.0",
+    "del": "^9.0.1",
     "front-matter": "^4.0.2",
-    "jsdoc-to-markdown": "^7.1.1",
-    "micromatch": "^4.0.5",
-    "mkdirp": "^1.0.4",
-    "vue-docgen-cli": "^4.51.0"
+    "jsdoc-to-markdown": "^9.1.3",
+    "kleur": "^4.1.5",
+    "micromatch": "^4.0.8",
+    "vue-docgen-cli": "^4.79.0"
+  },
+  "peerDependencies": {
+    "typescript": "*"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@types/jest": "^29.1.1",
-    "@types/jsdoc-to-markdown": "^7.0.3",
-    "@types/micromatch": "^4.0.2",
-    "@types/mkdirp": "^1.0.2",
-    "@typescript-eslint/eslint-plugin": "^5.39.0",
-    "@typescript-eslint/parser": "^5.39.0",
-    "babel-jest": "^29.1.2",
-    "cross-env": "^7.0.3",
-    "eslint": "^8.24.0",
-    "eslint-config-prettier": "^8.5.0",
-    "eslint-plugin-import": "^2.26.0",
-    "eslint-plugin-jest": "^27.1.1",
-    "eslint-plugin-prefer-arrow": "^1.2.3",
-    "husky": "^8.0.1",
-    "jest": "^29.1.2",
-    "lint-staged": "^13.0.3",
-    "memfs": "^3.4.7",
-    "ts-jest": "^29.0.3",
-    "typescript": "^4.8.4",
-    "vue": "^2.7.8"
+    "@eslint/js": "^10.0.1",
+    "@types/jsdoc-to-markdown": "^7.0.6",
+    "@types/micromatch": "^4.0.10",
+    "@types/node": "^26.6.6",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "@vitest/coverage-v8": "^5.1.0",
+    "conventional-changelog": "^8.1.3",
+    "conventional-changelog-conventionalcommits": "^10.4.1",
+    "eslint": "^10.14.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.14.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.6.0",
+    "memfs": "^4.80.0",
+    "prettier": "^3.9.10",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "typescript-eslint": "^8.72.1",
+    "vitepress": "^1.6.4",
+    "vitest": "^5.1.0"
   },
   "lint-staged": {
-    "src/**/*.{css,scss,json}": [
-      "prettier --write",
-      "git add"
+    "src/**/*.{js,ts}": [
+      "eslint --fix",
+      "prettier --write"
     ],
-    "src/**/*.{js,jsx,ts,tsx}": [
-      "eslint",
-      "prettier --write",
-      "git add"
+    "src/**/*.json": [
+      "prettier --write"
     ]
   },
-  "eslintConfig": {
-    "env": {
-      "commonjs": true,
-      "es6": true,
-      "node": true,
-      "jest": true
-    },
-    "extends": "eslint:recommended",
-    "globals": {
-      "Atomics": "readonly",
-      "SharedArrayBuffer": "readonly"
-    },
-    "parserOptions": {
-      "ecmaVersion": 2018
-    },
-    "rules": {
-      "quotes": [
-        "error",
-        "single",
-        {
-          "allowTemplateLiterals": true
-        }
-      ],
-      "no-console": 0,
-      "arrow-parens": [
-        "error",
-        "as-needed"
-      ]
-    }
+  "scripts": {
+    "test": "vitest run",
+    "test-coverage": "vitest run --coverage",
+    "test-watch": "vitest",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "dev": "tsc -w",
+    "build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "version": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -s && git add CHANGELOG.md",
+    "docs": "./bin/vuepress-jsdoc.js --source=./src --partials=./example/partials/*.hbs --readme=./README.md --format=vitepress --exclude=\"**/__tests__/**\"",
+    "docs:dev": "pnpm run build && pnpm run docs && vitepress dev documentation",
+    "docs:build": "pnpm run build && pnpm run docs && vitepress build documentation"
   }
-}
+}