Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 00a8731

Browse files
committed
allow the el option to accept an HTMLElement instance
This aligns it with what the docs were already saying erroneously, plus this is useful in cases when people have refs to an element already (embedding Docsify in a custom element shadow root, or in a React component that has a ref to the target element, etc).
1 parent c90c6a4 commit 00a8731

File tree

3 files changed

+71
-23
lines changed

3 files changed

+71
-23
lines changed

β€Ždocs/configuration.md

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,8 @@ The config can also be defined as a function, in which case the first argument i
3232

3333
## el
3434

35-
- Type: `String`
36-
- Default: `#app`
35+
- Type: `String | HTMLElement`
36+
- Default: `"#app"`
3737

3838
The DOM element to be mounted on initialization. It can be a CSS selector string or an actual [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement).
3939

@@ -43,6 +43,16 @@ window.$docsify = {
4343
};
4444
```
4545

46+
or
47+
48+
```js
49+
const someElement = document.querySelector('#someElement');
50+
51+
window.$docsify = {
52+
el: someElement,
53+
};
54+
```
55+
4656
## repo
4757

4858
- Type: `String`

β€Žsrc/core/util/dom.js

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,15 +29,30 @@ export const head = inBrowser && $.head;
2929

3030
/**
3131
* Find elements
32-
* @param {String|Element} el The root element where to perform the search from
33-
* @param {Element} node The query
34-
* @returns {Element} The found DOM element
32+
* @param {String|Element} elOrQuery The query to use on document, or the root element on which to use a query.
33+
* @param {Element} query The query to use on elOrQuery if elOrQuery is an element.
34+
* @returns {Element} If elOrQuery is an element and query is not provided, elOrQuery is returned. Otherwise, the found DOM element is returned.
3535
* @example
3636
* find('nav') => document.querySelector('nav')
3737
* find(nav, 'a') => nav.querySelector('a')
3838
*/
39-
export function find(el, node) {
40-
return node ? el.querySelector(node) : $.querySelector(el);
39+
export function find(elOrQuery, query) {
40+
let root;
41+
42+
// f.e. dom.find('#foo') or dom.find(el)
43+
if (arguments.length === 1) {
44+
if (elOrQuery instanceof Element) {
45+
return elOrQuery;
46+
}
47+
root = $;
48+
query = elOrQuery;
49+
}
50+
// f.e. dom.find(el, "#foo")
51+
else if (arguments.length === 2) {
52+
root = elOrQuery;
53+
}
54+
55+
return root.querySelector(query);
4156
}
4257

4358
/**

β€Žtest/integration/docsify.test.js

Lines changed: 39 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,48 @@
11
const docsifyInit = require('../helpers/docsify-init');
22

3-
// Suite
4-
// -----------------------------------------------------------------------------
53
describe('Docsify', function() {
6-
// Tests
7-
// ---------------------------------------------------------------------------
8-
test('allows $docsify configuration to be a function', async () => {
9-
const testConfig = jest.fn(vm => {
10-
expect(vm).toBeInstanceOf(Object);
11-
expect(vm.constructor.name).toEqual('Docsify');
12-
expect(vm.$fetch).toBeInstanceOf(Function);
13-
expect(vm.$resetEvents).toBeInstanceOf(Function);
14-
expect(vm.route).toBeInstanceOf(Object);
15-
});
4+
describe('config options', () => {
5+
test('allows $docsify configuration to be a function', async () => {
6+
const testConfig = jest.fn(vm => {
7+
expect(vm).toBeInstanceOf(Object);
8+
expect(vm.constructor.name).toEqual('Docsify');
9+
expect(vm.$fetch).toBeInstanceOf(Function);
10+
expect(vm.$resetEvents).toBeInstanceOf(Function);
11+
expect(vm.route).toBeInstanceOf(Object);
12+
});
1613

17-
await docsifyInit({
18-
config: testConfig,
14+
await docsifyInit({
15+
config: testConfig,
16+
});
17+
18+
expect(typeof Docsify).toEqual('object');
19+
expect(testConfig).toHaveBeenCalled();
1920
});
2021

21-
expect(typeof Docsify).toEqual('object');
22-
expect(testConfig).toHaveBeenCalled();
22+
describe('config.el', () => {
23+
it('accepts an element instance', async () => {
24+
const config = jest.fn(() => {
25+
const app = document.querySelector('#app');
26+
expect(app).toBeInstanceOf(HTMLElement);
27+
28+
return {
29+
basePath: `${TEST_HOST}/docs/index.html#/`,
30+
el: app,
31+
};
32+
});
33+
34+
await docsifyInit({
35+
config,
36+
testURL: `${TEST_HOST}/docs/index.html#/`,
37+
});
38+
39+
expect(config).toHaveBeenCalled();
40+
41+
expect(document.querySelector('#main').textContent).toContain(
42+
'A magical documentation site generator.'
43+
);
44+
});
45+
});
2346
});
2447

2548
test('provides the hooks and vm API to plugins', async () => {

0 commit comments

Comments
(0)

AltStyle γ«γ‚ˆγ£γ¦ε€‰ζ›γ•γ‚ŒγŸγƒšγƒΌγ‚Έ (->γ‚ͺγƒͺγ‚ΈγƒŠγƒ«) /