Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 1a352af

Browse files
trusktrtrusktr
committedApr 1, 2024
deprecate globals and global script data-* attributes, and set up the package for people to start importing Docsify and passing in non-global configs
1 parent 2387399 commit 1a352af

File tree

10 files changed

+290
-41
lines changed

10 files changed

+290
-41
lines changed
 

‎build/build.js

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ const version = process.env.VERSION || pkg.version;
1717
/**
1818
* @param {{
1919
* input: string,
20+
* format: 'iife' | 'module',
2021
* output?: string,
2122
* globalName?: string,
2223
* plugins?: Array<import('rollup').Plugin>
@@ -46,11 +47,11 @@ async function build(opts) {
4647
},
4748
})
4849
.then(bundle => {
49-
const dest = 'lib/' + (opts.output || opts.input);
50+
const dest = opts.output || opts.input;
5051

5152
console.log(dest);
5253
return bundle.write({
53-
format: 'iife',
54+
format: opts.format,
5455
output: opts.globalName ? { name: opts.globalName } : {},
5556
file: dest,
5657
strict: false,
@@ -64,15 +65,28 @@ async function buildCore() {
6465
promises.push(
6566
build({
6667
input: 'src/core/index.js',
67-
output: 'docsify.js',
68+
output: 'lib/docsify.js',
69+
format: 'iife',
70+
}),
71+
build({
72+
input: 'src/core/module.js',
73+
output: 'dist/core/module.js',
74+
format: 'module',
6875
})
6976
);
7077

7178
if (isProd) {
7279
promises.push(
7380
build({
7481
input: 'src/core/index.js',
75-
output: 'docsify.min.js',
82+
output: 'lib/docsify.min.js',
83+
format: 'iife',
84+
plugins: [uglify()],
85+
}),
86+
build({
87+
input: 'src/core/module.js',
88+
output: 'dist/core/module.min.js',
89+
format: 'module',
7690
plugins: [uglify()],
7791
})
7892
);
@@ -98,7 +112,7 @@ async function buildAllPlugin() {
98112
const promises = plugins.map(item => {
99113
return build({
100114
input: 'src/plugins/' + item.input,
101-
output: 'plugins/' + item.name + '.js',
115+
output: 'lib/plugins/' + item.name + '.js',
102116
});
103117
});
104118

@@ -107,7 +121,7 @@ async function buildAllPlugin() {
107121
promises.push(
108122
build({
109123
input: 'src/plugins/' + item.input,
110-
output: 'plugins/' + item.name + '.min.js',
124+
output: 'lib/plugins/' + item.name + '.min.js',
111125
plugins: [uglify()],
112126
})
113127
);
@@ -140,7 +154,7 @@ async function main() {
140154

141155
build({
142156
input,
143-
output: 'plugins/' + name + '.js',
157+
output: 'lib/plugins/' + name + '.js',
144158
});
145159
}
146160
})

‎docs/index.html

Lines changed: 165 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@
7171
<body>
7272
<div id="app">Loading ...</div>
7373
<script src="//cdn.jsdelivr.net/npm/docsify-plugin-carbon@1"></script>
74-
<script>
74+
<!-- <script>
7575
// Docsify configuration
7676
window.$docsify = {
7777
alias: {
@@ -214,8 +214,12 @@
214214
},
215215
],
216216
};
217-
</script>
218-
<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
217+
</script> -->
218+
219+
<!-- <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script> -->
220+
221+
<!-- TODO this all relied on globals, currently disabled -->
222+
<!--
219223
<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>
220224
<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/front-matter.min.js"></script>
221225
<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/ga.min.js"></script>
@@ -225,6 +229,163 @@
225229
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-nginx.min.js"></script>
226230
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-php.min.js"></script>
227231
<script src="//cdn.jsdelivr.net/npm/vue@2/dist/vue.min.js"></script>
228-
<!-- <script src="//cdn.jsdelivr.net/npm/vue@3/dist/vue.global.prod.js"></script> -->
232+
<script src="//cdn.jsdelivr.net/npm/vue@3/dist/vue.global.prod.js"></script>
233+
-->
234+
235+
<script type="module">
236+
import { Docsify } from '/lib/module.js';
237+
238+
new Docsify({
239+
alias: {
240+
'.*?/awesome':
241+
'https://raw.githubusercontent.com/docsifyjs/awesome-docsify/master/README.md',
242+
'.*?/changelog':
243+
'https://raw.githubusercontent.com/docsifyjs/docsify/master/CHANGELOG.md',
244+
'/.*/_navbar.md': '/_navbar.md',
245+
'/es/(.*)':
246+
'https://raw.githubusercontent.com/docsifyjs/docs-es/master/$1',
247+
'/de-de/(.*)':
248+
'https://raw.githubusercontent.com/docsifyjs/docs-de/master/$1',
249+
'/ru-ru/(.*)':
250+
'https://raw.githubusercontent.com/docsifyjs/docs-ru/master/$1',
251+
'/zh-cn/(.*)':
252+
'https://cdn.jsdelivr.net/gh/docsifyjs/docs-zh@master/$1',
253+
},
254+
auto2top: true,
255+
coverpage: true,
256+
executeScript: true,
257+
loadSidebar: true,
258+
loadNavbar: true,
259+
mergeNavbar: true,
260+
maxLevel: 4,
261+
subMaxLevel: 2,
262+
ga: 'UA-106147152-1',
263+
matomo: {
264+
host: '//matomo.thunderwave.de',
265+
id: 6,
266+
},
267+
name: 'docsify',
268+
nameLink: {
269+
'/es/': '#/es/',
270+
'/de-de/': '#/de-de/',
271+
'/ru-ru/': '#/ru-ru/',
272+
'/zh-cn/': '#/zh-cn/',
273+
'/': '#/',
274+
},
275+
search: {
276+
noData: {
277+
'/es/': '¡No hay resultados!',
278+
'/de-de/': 'Keine Ergebnisse!',
279+
'/ru-ru/': 'Никаких результатов!',
280+
'/zh-cn/': '没有结果!',
281+
'/': 'No results!',
282+
},
283+
paths: 'auto',
284+
placeholder: {
285+
'/es/': 'Buscar',
286+
'/de-de/': 'Suche',
287+
'/ru-ru/': 'Поиск',
288+
'/zh-cn/': '搜索',
289+
'/': 'Search',
290+
},
291+
pathNamespaces: ['/es', '/de-de', '/ru-ru', '/zh-cn'],
292+
},
293+
skipLink: {
294+
'/es/': 'Saltar al contenido principal',
295+
'/de-de/': 'Ga naar de hoofdinhoud',
296+
'/ru-ru/': 'Перейти к основному содержанию',
297+
'/zh-cn/': '跳到主要内容',
298+
},
299+
vueComponents: {
300+
'button-counter': {
301+
template: /* html */ `<button @click="count += 1">You clicked me {{ count }} times</button>`,
302+
data() {
303+
return {
304+
count: 0,
305+
};
306+
},
307+
},
308+
},
309+
vueGlobalOptions: {
310+
data() {
311+
return {
312+
count: 0,
313+
message: 'Hello, World!',
314+
// Fake API response
315+
images: [
316+
{
317+
title: 'Image 1',
318+
url: 'https://picsum.photos/150?random=1',
319+
},
320+
{
321+
title: 'Image 2',
322+
url: 'https://picsum.photos/150?random=2',
323+
},
324+
{
325+
title: 'Image 3',
326+
url: 'https://picsum.photos/150?random=3',
327+
},
328+
],
329+
};
330+
},
331+
computed: {
332+
timeOfDay() {
333+
const date = new Date();
334+
const hours = date.getHours();
335+
336+
if (hours < 12) {
337+
return 'morning';
338+
} else if (hours < 18) {
339+
return 'afternoon';
340+
} else {
341+
return 'evening';
342+
}
343+
},
344+
},
345+
methods: {
346+
hello() {
347+
alert(this.message);
348+
},
349+
},
350+
},
351+
vueMounts: {
352+
'#counter': {
353+
data() {
354+
return {
355+
count: 0,
356+
};
357+
},
358+
},
359+
},
360+
plugins: [
361+
DocsifyCarbon.create('CEBI6KQE', 'docsifyjsorg'),
362+
function (hook, vm) {
363+
hook.beforeEach(html => {
364+
let url;
365+
if (/githubusercontent\.com/.test(vm.route.file)) {
366+
url = vm.route.file
367+
.replace('raw.githubusercontent.com', 'github.com')
368+
.replace(/\/master/, '/blob/master');
369+
} else if (/jsdelivr\.net/.test(vm.route.file)) {
370+
url = vm.route.file
371+
.replace('cdn.jsdelivr.net/gh', 'github.com')
372+
.replace('@master', '/blob/master');
373+
} else {
374+
url =
375+
'https://github.com/docsifyjs/docsify/blob/develop/docs/' +
376+
vm.route.file;
377+
}
378+
const editHtml = '[:memo: Edit Document](' + url + ')\n';
379+
return (
380+
editHtml +
381+
html +
382+
'\n\n----\n\n' +
383+
'<a href="https://docsify.js.org" target="_blank" style="color: inherit; font-weight: normal; text-decoration: none;">Powered by docsify</a>'
384+
);
385+
});
386+
},
387+
],
388+
});
389+
</script>
229390
</body>
230391
</html>

‎package.json

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,16 @@
1818
"// These exports require moduleResolution:NodeNext to be enabled in the consumer.": "",
1919
"// TODO native ESM (in browsers) does not work yet because prismjs is not ESM and Docsify source imports it as CommonJS": "",
2020
"exports": {
21-
"./*": "./*",
21+
"./src/*": "./src/*",
22+
"./dist/core/module.js": "./dist/core/module.js",
23+
"./dist/core/module.min.js": "./dist/core/module.min.js",
2224
".": {
2325
"types": "./dist/core/Docsify.d.ts",
24-
"default": "./src/core/Docsify.js"
26+
"default": "./dist/core/module.min.js"
2527
}
2628
},
2729
"files": [
30+
"src",
2831
"lib",
2932
"themes"
3033
],

‎src/core/Docsify.js

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import prism from 'prismjs';
12
import { Router } from './router/index.js';
23
import { Render } from './render/index.js';
34
import { Fetch } from './fetch/index.js';
@@ -8,18 +9,31 @@ import config from './config.js';
89
import { isFn } from './util/core.js';
910
import { Lifecycle } from './init/lifecycle.js';
1011

12+
export { prism };
13+
export { marked } from 'marked';
14+
export * as util from './util/index.js';
15+
export * as dom from './util/dom.js';
16+
export { Compiler } from './render/compiler.js';
17+
export { slugify } from './render/slugify.js';
18+
export { get } from './util/ajax.js';
19+
1120
/** @typedef {new (...args: any[]) => any} Constructor */
21+
/** @typedef {import('./config.js').DocsifyConfig} DocsifyConfig */
1222

1323
// eslint-disable-next-line new-cap
1424
export class Docsify extends Fetch(
1525
// eslint-disable-next-line new-cap
1626
Events(Render(VirtualRoutes(Router(Lifecycle(Object)))))
1727
) {
18-
config = config(this);
28+
/** @type {DocsifyConfig} */
29+
config;
1930

20-
constructor() {
31+
/** @param {Partial<DocsifyConfig>} conf */
32+
constructor(conf = {}) {
2133
super();
2234

35+
this.config = config(this, conf);
36+
2337
this.initLifecycle(); // Init hooks
2438
this.initPlugin(); // Install plugins
2539
this.callHook('init');
@@ -45,3 +59,5 @@ export class Docsify extends Fetch(
4559
});
4660
}
4761
}
62+
63+
export const version = '__VERSION__';

‎src/core/config.js

Lines changed: 69 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,65 @@ import { hyphenate, isPrimitive } from './util/core.js';
33

44
const currentScript = document.currentScript;
55

6-
/** @param {import('./Docsify.js').Docsify} vm */
7-
export default function (vm) {
8-
const config = Object.assign(
6+
/**
7+
@typedef {
8+
{
9+
auto2top: boolean
10+
autoHeader: boolean
11+
basePath: string
12+
catchPluginErrors: boolean
13+
cornerExternalLinkTarget: '_blank' | '_self' | '_parent' | '_top' | '_unfencedTop'
14+
coverpage: boolean | string
15+
el: string
16+
executeScript: null | boolean
17+
ext: string
18+
externalLinkRel: 'noopener' | string
19+
externalLinkTarget: '_blank' | '_self' | '_parent' | '_top' | '_unfencedTop'
20+
formatUpdated: string
21+
ga: string
22+
homepage: string
23+
keyBindings: false | {
24+
[commandName: string]: {
25+
bindings: string[]
26+
callback: Function
27+
}
28+
}
29+
loadNavbar: null | boolean | string
30+
loadSidebar: null | boolean | string
31+
maxLevel: number
32+
mergeNavbar: boolean
33+
name: boolean | string
34+
nameLink: string
35+
nativeEmoji: boolean
36+
noCompileLinks: string[]
37+
noEmoji: boolean
38+
notFoundPage: boolean | string | Record<string, string>
39+
plugins: Function[]
40+
relativePath: boolean
41+
repo: boolean | string
42+
routes: Record<string, string | Function>
43+
routerMode: 'hash' | 'history'
44+
subMaxLevel: number,
45+
topMargin: number,
46+
47+
themeColor: string,
48+
}
49+
} DocsifyConfig
50+
*/
51+
52+
/**
53+
* @param {import('./Docsify.js').Docsify} vm
54+
* @param {Partial<DocsifyConfig>} config
55+
* @returns {DocsifyConfig}
56+
*/
57+
export default function (vm, config = {}) {
58+
if (window.$docsify) {
59+
console.warn(
60+
'DEPRECATION: The global $docsify config variable is deprecated. See the latest getting started docs. https://docsify.js.org/#/quickstart'
61+
);
62+
}
63+
64+
config = Object.assign(
965
{
1066
auto2top: false,
1167
autoHeader: false,
@@ -21,6 +77,7 @@ export default function (vm) {
2177
formatUpdated: '',
2278
ga: '',
2379
homepage: 'README.md',
80+
keyBindings: {},
2481
loadNavbar: null,
2582
loadSidebar: null,
2683
maxLevel: 6,
@@ -37,7 +94,6 @@ export default function (vm) {
3794
routes: {},
3895
routerMode: 'hash',
3996
subMaxLevel: 0,
40-
// themeColor: '',
4197
topMargin: 0,
4298

4399
// Deprecations //////////////////
@@ -63,7 +119,9 @@ export default function (vm) {
63119

64120
typeof window.$docsify === 'function'
65121
? window.$docsify(vm)
66-
: window.$docsify
122+
: window.$docsify,
123+
124+
config
67125
);
68126

69127
// Merge default and user-specified key bindings
@@ -99,6 +157,11 @@ export default function (vm) {
99157
const val = script.getAttribute('data-' + hyphenate(prop));
100158

101159
if (isPrimitive(val)) {
160+
console.warn(
161+
`DEPRECATION: data-* attributes on the docsify global script (f.e. ${
162+
'data-' + hyphenate(prop)
163+
}) are deprecated.`
164+
);
102165
config[prop] = val === '' ? true : val;
103166
}
104167
}
@@ -124,7 +187,5 @@ export default function (vm) {
124187
config.name = '';
125188
}
126189

127-
window.$docsify = config;
128-
129-
return config;
190+
return /** @type {DocsifyConfig} */ (config);
130191
}

‎src/core/global-api.js

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,15 @@ import { Compiler } from './render/compiler.js';
66
import { slugify } from './render/slugify.js';
77
import { get } from './util/ajax.js';
88

9-
// TODO This is deprecated, kept for backwards compatibility. Remove in a
10-
// major release. We'll tell people to get everything from the DOCSIFY global
11-
// when using the global build, but we'll highly recommend for them to import
12-
// from the ESM build (f.e. lib/docsify.esm.js and lib/docsify.min.esm.js).
9+
/**
10+
* @deprecated This will be removed in a major release. Import what you need
11+
* from using ES Modules as per the docs.
12+
*/
1313
export default function initGlobalAPI() {
14+
console.warn(
15+
'DEPRECATION: The Docsify global script is deprecated. See the latest getting started docs. https://docsify.js.org/#/quickstart'
16+
);
17+
1418
window.Docsify = {
1519
util,
1620
dom,

‎src/core/index.js

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,6 @@ import { documentReady } from './util/dom.js';
22
import { Docsify } from './Docsify.js';
33
import initGlobalAPI from './global-api.js';
44

5-
// TODO This global API and auto-running Docsify will be deprecated, and removed
6-
// in a major release. Instead we'll tell users to use `new Docsify()` to create
7-
// and manage their instance(s).
8-
95
/**
106
* Global API
117
*/

‎src/core/module.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
export * from './Docsify.js';

‎src/core/module.min.js

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
// This file exists for type declaration output.
2+
export * from './Docsify.js';

‎tsconfig.json

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,5 @@
1212
"resolveJsonModule": true,
1313
"outDir": "dist/"
1414
},
15-
"include": ["src/**/*.js"],
16-
"exclude": [
17-
// "./**/*.test.js",
18-
// "test/",
19-
// "jest.config.js",
20-
// "middleware.js",
21-
// "playwright.config.js",
22-
// "server.configs.js",
23-
// "server.js"
24-
]
15+
"include": ["src/**/*.js", "src/core/module.min.js"]
2516
}

0 commit comments

Comments
 (0)
Please sign in to comment.