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

.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.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"
  }

src/core/Docsify.js

@@ -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__';