refactor: convert to ES Modulesand remove traces of CommonJS

BREAKING: The new project layout might break in some tooling setups.

We've added an exports field to `package.json` to specify where
statements like `import ... from 'docsify'` will import from, and left
the `main` and `unpkg` fields as-is for backwards compatibility with the
global <script> import method. Most people who use a non-module
`<script>` tag to import Docsify will not notice a difference. Anyone
else who is importing Docsify into a specilized build setup using
`import` statements has a chance of being broken, so we've marked this
as BREAKING.

Author: trusktr

Diff for: .eslintrc.js

@@ -12,7 +12,7 @@ module.exports = {
     sourceType: 'module',
     ecmaVersion: 2019,
   },
-  plugins: ['prettier', 'import'],
+  plugins: ['prettier', 'import', 'importAssertions'],
   env: {
     browser: true,
     es6: true,

Diff for: .vscode/launch.json

@@ -7,18 +7,18 @@
     {
       "type": "node",
       "request": "launch",
-      "name": "Run tests",
+      "name": "Run unit tests",
       "runtimeExecutable": "npm",
-      "runtimeArgs": ["run-script", "test"],
+      "runtimeArgs": ["test"],
       "console": "integratedTerminal"
     },
     {
       "type": "node",
       "request": "launch",
       "name": "Run current test file",
-      "runtimeExecutable": "npm",
-      "runtimeArgs": ["run-script", "test"],
-      "args": ["--", "-i", "${relativeFile}", "--testPathIgnorePatterns"],
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["jest"],
+      "args": ["-i", "${relativeFile}", "--testPathIgnorePatterns"],
       "console": "integratedTerminal"
     },
     {
@@ -41,10 +41,9 @@
       "type": "node",
       "request": "launch",
       "name": "Update current test file snapshot(s)",
-      "runtimeExecutable": "npm",
-      "runtimeArgs": ["run-script", "test"],
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["jest"],
       "args": [
-        "--",
         "-i",
         "${relativeFile}",
         "--updateSnapshot",
@@ -56,8 +55,8 @@
       "type": "node",
       "request": "launch",
       "name": "Update selected test name snapshot(s)",
-      "runtimeExecutable": "npm",
-      "runtimeArgs": ["run-script", "test"],
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["jest"],
       "args": [
         "--",
         "-i",

Diff for: README.md

@@ -32,7 +32,10 @@
 - [`develop` branch preview](https://docsify-preview.vercel.app/)
 - [Documentation](https://docsify.js.org)
 - [CLI](https://github.com/docsifyjs/docsify-cli)
-- CDN: [UNPKG](https://unpkg.com/docsify/) | [jsDelivr](https://cdn.jsdelivr.net/npm/docsify/) | [cdnjs](https://cdnjs.com/libraries/docsify)
+- CDN:
+  - [UNPKG](https://unpkg.com/docsify/)
+  - [jsDelivr](https://cdn.jsdelivr.net/npm/docsify/)
+  - [cdnjs](https://cdnjs.com/libraries/docsify)
 - [Awesome docsify](https://github.com/docsifyjs/awesome-docsify)
 - [Community chat](https://discord.gg/3NwKFyR)
 

Diff for: build/build.js

@@ -1,13 +1,14 @@
-const rollup = require('rollup')
-const buble = require('rollup-plugin-buble')
-const commonjs = require('rollup-plugin-commonjs')
-const nodeResolve = require('rollup-plugin-node-resolve')
-const { uglify } = require('rollup-plugin-uglify')
-const replace = require('rollup-plugin-replace')
-const isProd = process.env.NODE_ENV === 'production'
-const version = process.env.VERSION || require('../package.json').version
-const chokidar = require('chokidar')
-const path = require('path')
+import rollup from 'rollup';
+import buble from 'rollup-plugin-buble';
+import commonjs from 'rollup-plugin-commonjs';
+import nodeResolve from 'rollup-plugin-node-resolve';
+import { uglify } from 'rollup-plugin-uglify';
+import replace from 'rollup-plugin-replace';
+import chokidar from 'chokidar';
+import path from 'path';
+import pkg from '../package.json' assert { type: 'json' };
+const isProd = process.env.NODE_ENV === 'production';
+const version = process.env.VERSION || pkg.version;
 
 /**
  * @param {{

Diff for: build/cover.js

@@ -1,14 +1,16 @@
-var fs = require('fs')
-var read = fs.readFileSync
-var write = fs.writeFileSync
-var version = process.env.VERSION || require('../package.json').version
+import fs from 'fs';
+import pkg from '../package.json' assert { type: 'json' };
+var read = fs.readFileSync;
+var write = fs.writeFileSync;
+var version = process.env.VERSION || pkg.version;
 
-var file = __dirname + '/../docs/_coverpage.md'
-var cover = read(file, 'utf8').toString()
+const relative = path => new URL(path, import.meta.url);
+var file = relative('../docs/_coverpage.md');
+var cover = read(file, 'utf8').toString();
 
-console.log('Replace version number in cover page...')
+console.log('Replace version number in cover page...');
 cover = cover.replace(
   /<small>(\S+)?<\/small>/g,
   '<small>' + version + '</small>'
-)
-write(file, cover)
+);
+write(file, cover);

Diff for: build/css.js

@@ -1,9 +1,10 @@
-const fs = require('fs')
-const path = require('path')
-const {spawn} = require('child_process')
+import fs from 'fs'
+import path from 'path'
+import {spawn} from 'child_process'
 
+const relative = path => new URL(path, import.meta.url);
 const args = process.argv.slice(2)
-fs.readdir(path.join(__dirname, '../src/themes'), (err, files) => {
+fs.readdir(relative('../src/themes'), (err, files) => {
     if (err) {
         console.error('err', err)
         process.exit(1)

Diff for: build/emoji.js

@@ -1,6 +1,6 @@
-const axios = require('axios');
-const fs = require('fs');
-const path = require('path');
+import axios from 'axios';
+import fs from 'fs';
+import path from 'path';
 
 const filePaths = {
   emojiMarkdown: path.resolve(process.cwd(), 'docs', 'emoji.md'),

Diff for: build/mincss.js

@@ -1,12 +1,12 @@
-const cssnano = require('cssnano').process
-const path = require('path')
-const fs = require('fs')
+import cssnano from 'cssnano';
+import path from 'path'
+import fs from 'fs'
 
-files = fs.readdirSync(path.resolve('lib/themes'))
+const files = fs.readdirSync(path.resolve('lib/themes'))
 
 files.forEach(file => {
   file = path.resolve('lib/themes', file)
-  cssnano(fs.readFileSync(file)).then(result => {
+  cssnano.process(fs.readFileSync(file)).then(result => {
     fs.writeFileSync(file, result.css)
   }).catch(e => {
     console.error(e)

Diff for: package.json

@@ -2,19 +2,22 @@
   "name": "docsify",
   "version": "4.13.0",
   "description": "A magical documentation generator.",
-  "author": {
-    "name": "qingwei-li",
-    "email": "[email protected]",
-    "url": "https://github.com/QingWei-Li"
-  },
   "homepage": "https://docsify.js.org",
+  "repository": "github:docsifyjs/docsify",
+  "authors": "https://github.com/docsifyjs/docsify/graphs/contributors",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/docsifyjs/docsify.git"
+  "collective": {
+    "url": "https://opencollective.com/docsify"
   },
+  "type": "module",
+  "// The 'main' and 'unpkg' fields will remain as legacy for backwards compatbility for now. We will add deprectaion warnings to these outputs to give people time to see the warnings in their apps in a non-breaking way, and eventually we can remove the legacy stuff.": "",
   "main": "lib/docsify.js",
   "unpkg": "lib/docsify.min.js",
+  "// We're using the 'exports' field as an override of the 'main' field to provide the new ESM setup. Once we remove legacy 'main', we will remove the 'exports' field and have a simple ESM setup with only a 'main' field.": "",
+  "exports": {
+    ".": "./src/Docsify.js",
+    "./*": "./*"
+  },
   "files": [
     "lib",
     "themes"
@@ -117,8 +120,5 @@
     "documentation",
     "creator",
     "generator"
-  ],
-  "collective": {
-    "url": "https://opencollective.com/docsify"
-  }
+  ]
 }

Diff for: server.js

@@ -1,10 +1,10 @@
-const liveServer = require('live-server')
-const middleware = []
+import liveServer from 'live-server';
+const middleware = [];
 
 const params = {
   port: 3000,
   watch: ['lib', 'docs', 'themes'],
-  middleware
-}
+  middleware,
+};
 
-liveServer.start(params)
+liveServer.start(params);

Diff for: src/core/Docsify.js

@@ -6,8 +6,8 @@ import { VirtualRoutes } from './virtual-routes/index.js';
 import initGlobalAPI from './global-api.js';
 
 import config from './config.js';
-import { isFn } from './util/core';
-import { Lifecycle } from './init/lifecycle';
+import { isFn } from './util/core.js';
+import { Lifecycle } from './init/lifecycle.js';
 
 /** @typedef {new (...args: any[]) => any} Constructor */
 

Diff for: src/core/config.js

@@ -1,4 +1,4 @@
-import { merge, hyphenate, isPrimitive, hasOwn } from './util/core';
+import { merge, hyphenate, isPrimitive, hasOwn } from './util/core.js';
 
 const currentScript = document.currentScript;
 

Diff for: src/core/event/index.js

@@ -1,7 +1,7 @@
-import { isMobile } from '../util/env';
-import { body, on } from '../util/dom';
-import * as sidebar from './sidebar';
-import { scrollIntoView, scroll2Top } from './scroll';
+import { isMobile } from '../util/env.js';
+import { body, on } from '../util/dom.js';
+import * as sidebar from './sidebar.js';
+import { scrollIntoView, scroll2Top } from './scroll.js';
 
 /** @typedef {import('../Docsify').Constructor} Constructor */
 

Diff for: src/core/event/scroll.js

@@ -1,8 +1,8 @@
 import Tweezer from 'tweezer.js';
-import { isMobile } from '../util/env';
-import * as dom from '../util/dom';
-import { removeParams } from '../router/util';
-import config from '../config';
+import { isMobile } from '../util/env.js';
+import * as dom from '../util/dom.js';
+import { removeParams } from '../router/util.js';
+import config from '../config.js';
 
 const nav = {};
 let hoverOver = false;

Diff for: src/core/event/sidebar.js

@@ -1,6 +1,6 @@
 /* eslint-disable no-unused-vars */
-import { isMobile } from '../util/env';
-import * as dom from '../util/dom';
+import { isMobile } from '../util/env.js';
+import * as dom from '../util/dom.js';
 
 const title = dom.$.title;
 /**

Diff for: src/core/fetch/ajax.js

@@ -1,6 +1,6 @@
 /* eslint-disable no-unused-vars */
-import progressbar from '../render/progressbar';
-import { noop, hasOwn } from '../util/core';
+import progressbar from '../render/progressbar.js';
+import { noop, hasOwn } from '../util/core.js';
 
 const cache = {};
 

Diff for: src/core/fetch/index.js

@@ -1,8 +1,8 @@
 /* eslint-disable no-unused-vars */
-import { getParentPath, stringifyQuery } from '../router/util';
-import { noop, isExternal } from '../util/core';
-import { getAndActive } from '../event/sidebar';
-import { get } from './ajax';
+import { getParentPath, stringifyQuery } from '../router/util.js';
+import { noop, isExternal } from '../util/core.js';
+import { getAndActive } from '../event/sidebar.js';
+import { get } from './ajax.js';
 
 function loadNested(path, qs, file, next, vm, first) {
   path = first ? path : path.replace(/\/$/, '');

Diff for: src/core/global-api.js

@@ -1,10 +1,10 @@
 import prism from 'prismjs';
 import { marked } from 'marked';
-import * as util from './util';
-import * as dom from './util/dom';
-import { Compiler } from './render/compiler';
-import { slugify } from './render/slugify';
-import { get } from './fetch/ajax';
+import * as util from './util/index.js';
+import * as dom from './util/dom.js';
+import { Compiler } from './render/compiler.js';
+import { slugify } from './render/slugify.js';
+import { get } from './fetch/ajax.js';
 
 // TODO This is deprecated, kept for backwards compatibility. Remove in next
 // major release. We'll tell people to get everything from the DOCSIFY global

Diff for: src/core/index.js

@@ -1,5 +1,5 @@
-import { documentReady } from './util/dom';
-import { Docsify } from './Docsify';
+import { documentReady } from './util/dom.js';
+import { Docsify } from './Docsify.js';
 
 /**
  * Run Docsify

Diff for: src/core/init/lifecycle.js

@@ -1,4 +1,4 @@
-import { noop } from '../util/core';
+import { noop } from '../util/core.js';
 
 /** @typedef {import('../Docsify').Constructor} Constructor */
 

Diff for: src/core/render/compiler.js

@@ -1,21 +1,21 @@
 import { marked } from 'marked';
-import { isAbsolutePath, getPath, getParentPath } from '../router/util';
-import { isFn, merge, cached, isPrimitive } from '../util/core';
-import { tree as treeTpl } from './tpl';
-import { genTree } from './gen-tree';
-import { slugify } from './slugify';
-import { emojify } from './emojify';
+import { isAbsolutePath, getPath, getParentPath } from '../router/util.js';
+import { isFn, merge, cached, isPrimitive } from '../util/core.js';
+import { tree as treeTpl } from './tpl.js';
+import { genTree } from './gen-tree.js';
+import { slugify } from './slugify.js';
+import { emojify } from './emojify.js';
 import {
   getAndRemoveConfig,
   removeAtag,
   getAndRemoveDocisfyIgnorConfig,
-} from './utils';
-import { imageCompiler } from './compiler/image';
-import { highlightCodeCompiler } from './compiler/code';
-import { paragraphCompiler } from './compiler/paragraph';
-import { taskListCompiler } from './compiler/taskList';
-import { taskListItemCompiler } from './compiler/taskListItem';
-import { linkCompiler } from './compiler/link';
+} from './utils.js';
+import { imageCompiler } from './compiler/image.js';
+import { highlightCodeCompiler } from './compiler/code.js';
+import { paragraphCompiler } from './compiler/paragraph.js';
+import { taskListCompiler } from './compiler/taskList.js';
+import { taskListItemCompiler } from './compiler/taskListItem.js';
+import { linkCompiler } from './compiler/link.js';
 
 const cachedLinks = {};
 
@@ -115,6 +115,7 @@ export class Compiler {
       })(text);
 
       const curFileName = this.router.parse().file;
+      console.log('filename:', curFileName);
 
       if (isCached) {
         this.toc = this.cacheTOC[curFileName];

Diff for: src/core/render/compiler/code.js

@@ -1,6 +1,6 @@
 import Prism from 'prismjs';
 // See https://github.com/PrismJS/prism/pull/1367
-import 'prismjs/components/prism-markup-templating';
+import 'prismjs/components/prism-markup-templating.js';
 
 export const highlightCodeCompiler = ({ renderer }) =>
   (renderer.code = function (code, lang = 'markup') {

Diff for: src/core/render/compiler/headline.js

@@ -2,8 +2,8 @@ import {
   getAndRemoveConfig,
   removeAtag,
   getAndRemoveDocisfyIgnorConfig,
-} from '../utils';
-import { slugify } from './slugify';
+} from '../utils.js';
+import { slugify } from './slugify.js';
 
 export const headingCompiler = ({ renderer, router, _self }) =>
   (renderer.code = (text, level) => {

Diff for: src/core/render/compiler/image.js

@@ -1,5 +1,5 @@
-import { getAndRemoveConfig } from '../utils';
-import { isAbsolutePath, getPath, getParentPath } from '../../router/util';
+import { getAndRemoveConfig } from '../utils.js';
+import { isAbsolutePath, getPath, getParentPath } from '../../router/util.js';
 
 export const imageCompiler = ({ renderer, contentBase, router }) =>
   (renderer.image = (href, title, text) => {