feat: output type definitions, and allow new Docsify(opts) to accept options for ESM usage (#2392)

This `new Docsify(opts)` API can be safely converted to a Custom Element constructor with backwards compatibility later.

Author: trusktr

.github/workflows/test.yml

@@ -49,6 +49,8 @@ jobs:
         run: npm run test:unit -- --ci --runInBand
       - name: Integration Tests
         run: npm run test:integration -- --ci --runInBand
+      - name: Consumption Tests
+        run: npm run test:consume-types
 
   test-playwright:
     runs-on: ubuntu-latest

.gitignore

@@ -4,8 +4,6 @@
 .vercel
 _playwright-report
 _playwright-results
-dist
-lib
 node_modules
 
 # Files
@@ -14,3 +12,10 @@ node_modules
 
 # Exceptions
 !.gitkeep
+
+# Output folder for the global build only
+dist
+
+# TypeScript declaration files for standard ESM consumption
+src/**/*.d.ts
+src/**/*.d.ts.map

.prettierignore

@@ -8,4 +8,4 @@ _vars.css
 _vars-advanced.css
 CHANGELOG.md
 emoji-data.*
-HISTORY.md
+HISTORY.md

.vscode/settings.json

@@ -1,4 +1,5 @@
 {
   "editor.defaultFormatter": "esbenp.prettier-vscode",
-  "cSpell.words": ["coverpage"]
+  "cSpell.words": ["coverpage"],
+  "typescript.tsdk": "node_modules/typescript/lib"
 }

docs/configuration.md

@@ -456,7 +456,7 @@ window.$docsify = {
 
 ## name
 
-- Type: `String`
+- Type: `Boolean | String`
 
 Website name as it appears in the sidebar.
 
@@ -474,6 +474,22 @@ window.$docsify = {
 };
 ```
 
+If `true`, the website name will be inferred from the document's `<title>` tag.
+
+```js
+window.$docsify = {
+  name: true,
+};
+```
+
+If `false` or empty, no name will be displayed.
+
+```js
+window.$docsify = {
+  name: false,
+};
+```
+
 ## nameLink
 
 - Type: `String`
@@ -652,6 +668,10 @@ window.$docsify = {
 };
 ```
 
+## plugins
+
+See [Plugins](./plugins.md).
+
 ## relativePath
 
 - Type: `Boolean`
@@ -706,6 +726,8 @@ window.$docsify = {
 };
 ```
 
+If undefined or empty, no GitHub corner will be displayed.
+
 ## requestHeaders
 
 - Type: `Object`
@@ -887,9 +909,9 @@ window.$docsify = {
 Determines if/how the site's [skip navigation link](https://webaim.org/techniques/skipnav/) will be rendered.
 
 ```js
-// Render skip link for all routes (default)
+// Render skip link for all routes
 window.$docsify = {
-  skipLink: 'Skip to main content',
+  skipLink: 'Skip to content',
 };
 ```
 
@@ -912,6 +934,13 @@ window.$docsify = {
 };
 ```
 
+```js
+// Use default
+window.$docsify = {
+  skipLink: true, // "Skip to main content"
+};
+```
+
 ## subMaxLevel
 
 - Type: `Number`

docs/plugins.md

@@ -1,5 +1,9 @@
 # List of Plugins
 
+These are built-in and external plugins for Docsify.
+
+See also how to [Write a Plugin](./write-a-plugin.md).
+
 ## Full text search
 
 By default, the hyperlink on the current page is recognized and the content is saved in `IndexedDB`. You can also specify the path to the files.
@@ -25,7 +29,7 @@ By default, the hyperlink on the current page is recognized and the content is s
       insertBefore: '.sidebar-nav', // CSS selector in .sidebar scope
 
       maxAge: 86400000, // Expiration time, the default one day
-      paths: [], // or 'auto'
+      paths: [], // string[] of files to search in, or 'auto' for discovery based on your sidebar
       placeholder: 'Type to search',
 
       // Localization

package-lock.json

@@ -24,18 +24,22 @@
   },
   "type": "module",
   "main": "dist/docsify.js",
+  "types": "src/core/Docsify.d.ts",
   "exports": {
     ".": "./src/core/Docsify.js",
     "./*": "./*"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "lint-staged": {
     "*.js": "eslint --fix"
   },
   "dependencies": {
+    "common-tags": "^1.8.0",
     "dexie": "^4.0.11",
+    "marked": "^16.0.0",
     "medium-zoom": "^1.1.0",
     "opencollective-postinstall": "^2.0.2",
     "prismjs": "^1.29.0",
@@ -51,10 +55,11 @@
     "@rollup/plugin-node-resolve": "^16.0.0",
     "@rollup/plugin-replace": "^6.0.1",
     "@rollup/plugin-terser": "^0.4.3",
+    "@types/common-tags": "^1.8.4",
     "@types/eslint": "^8.40.2",
+    "@types/prismjs": "^1.26.5",
     "axios": "^1.5.0",
     "browser-sync": "^3.0.2",
-    "common-tags": "^1.8.0",
     "conventional-changelog-cli": "^3.0.0",
     "cross-env": "^10.0.0",
     "cssnano": "^7.0.1",
@@ -69,7 +74,6 @@
     "jest": "^30.0.4",
     "jest-environment-jsdom": "^30.0.5",
     "lint-staged": "^16.1.0",
-    "marked": "^16.0.0",
     "npm-run-all": "^4.1.5",
     "postcss-cli": "^11.0.0",
     "postcss-import": "^16.1.0",
@@ -78,6 +82,7 @@
     "rimraf": "^6.1.0",
     "rollup": "^4.17.2",
     "rollup-plugin-import-css": "^4.0.1",
+    "typescript": "^5.9.3",
     "vue": "^3.4.27",
     "xhr-mock": "^2.5.1"
   },
@@ -87,8 +92,9 @@
     "build:css:min": "cross-env NODE_ENV='production' npm run build:css -- --ext .min.css",
     "build:emoji": "node ./build/emoji.js",
     "build:js": "rollup -c",
-    "build": "run-s clean build:js build:css build:css:min build:cover",
-    "clean": "rimraf --glob dist/** themes/** _playwright*/**",
+    "build:types": "tsc",
+    "build": "run-s clean build:types build:js build:css build:css:min build:cover",
+    "clean": "rimraf --glob \"dist/**\" \"themes/**\" \"_playwright*/**\" \"src/**/*.d.ts\" \"src/**/*.d.ts.map\"",
     "dev": "run-p serve:dev watch:*",
     "docker:build:test": "npm run docker:cli -- build:test",
     "docker:build": "docker build -f Dockerfile -t docsify-test:local .",
@@ -111,11 +117,15 @@
     "test:e2e": "playwright test",
     "test:e2e:chromium": "playwright test --project='chromium'",
     "test:e2e:ui": "playwright test --ui",
+    "test:e2e:consume-types": "echo TODO: test the consume-types example with ESM modules",
     "test:integration": "npm run test:jest -- --selectProjects integration",
     "test:jest": "cross-env NODE_OPTIONS=--experimental-vm-modules jest",
     "test:unit": "npm run test:jest -- --selectProjects unit",
     "test:update:snapshot": "npm run test:jest -- --updateSnapshot",
-    "test": "run-s test:jest test:e2e",
+    "test:consume-types": "cd test/consume-types && npm clean-install --install-links && npm run typecheck",
+    "test": "run-s test:jest test:e2e test:consume-types",
+    "typecheck": "tsc --noEmit",
+    "typecheck:watch": "tsc --noEmit --watch",
     "watch:css": "run-p 'build:css -- --watch' 'build:css:min -- --watch'",
     "watch:js": "npm run build:js -- --watch"
   }

package.json

@@ -1,3 +1,4 @@
+import prism from 'prismjs';
 import { Router } from './router/index.js';
 import { Render } from './render/index.js';
 import { Fetch } from './fetch/index.js';
@@ -8,16 +9,29 @@ import config from './config.js';
 import { isFn } from './util/core.js';
 import { Lifecycle } from './init/lifecycle.js';
 
+export { prism };
+export { marked } from 'marked';
+export * as util from './util/index.js';
+export * as dom from './util/dom.js';
+export { Compiler } from './render/compiler.js';
+export { slugify } from './render/slugify.js';
+export { get } from './util/ajax.js';
+
 /** @typedef {new (...args: any[]) => any} Constructor */
+/** @typedef {import('./config.js').DocsifyConfig} DocsifyConfig */
 
 export class Docsify extends Fetch(
   Events(Render(VirtualRoutes(Router(Lifecycle(Object))))),
 ) {
-  config = config(this);
+  /** @type {DocsifyConfig} */
+  config;
 
-  constructor() {
+  /** @param {Partial<DocsifyConfig>} conf */
+  constructor(conf = {}) {
     super();
 
+    this.config = config(this, conf);
+
     this.initLifecycle(); // Init hooks
     this.initPlugin(); // Install plugins
     this.callHook('init');
@@ -45,3 +59,5 @@ export class Docsify extends Fetch(
     });
   }
 }
+
+export const version = '__VERSION__';