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

.eslintrc.js

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

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

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)
 

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 {{

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);

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)

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'),

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)

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"
-  }
+  ]
 }

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);

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 */
 

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;
 

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 */
 

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;

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;
 /**

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 = {};
 

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(/\/$/, '');

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

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

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 */
 

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];

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') {

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) => {

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) => {