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).
docsifyjs · Jan 5, 2022 · 00a8731 · 00a8731
1 parent c90c6a4
commit 00a8731
Show file tree

Hide file tree

Showing 3 changed files with 71 additions and 23 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -32,8 +32,8 @@ The config can also be defined as a function, in which case the first argument i
 
 ## el
 
-- Type: `String`
-- Default: `#app`
+- Type: `String | HTMLElement`
+- Default: `"#app"`
 
 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).
 
@@ -43,6 +43,16 @@ window.$docsify = {
 };
 ```
 
+or
+
+```js
+const someElement = document.querySelector('#someElement');
+
+window.$docsify = {
+  el: someElement,
+};
+```
+
 ## repo
 
 - Type: `String`

diff --git a/src/core/util/dom.js b/src/core/util/dom.js
@@ -29,15 +29,30 @@ export const head = inBrowser && $.head;
 
 /**
  * Find elements
- * @param {String|Element} el The root element where to perform the search from
- * @param {Element} node The query
- * @returns {Element} The found DOM element
+ * @param {String|Element} elOrQuery The query to use on document, or the root element on which to use a query.
+ * @param {Element} query The query to use on elOrQuery if elOrQuery is an element.
+ * @returns {Element} If elOrQuery is an element and query is not provided, elOrQuery is returned. Otherwise, the found DOM element is returned.
  * @example
  * find('nav') => document.querySelector('nav')
  * find(nav, 'a') => nav.querySelector('a')
  */
-export function find(el, node) {
-  return node ? el.querySelector(node) : $.querySelector(el);
+export function find(elOrQuery, query) {
+  let root;
+
+  // f.e. dom.find('#foo') or dom.find(el)
+  if (arguments.length === 1) {
+    if (elOrQuery instanceof Element) {
+      return elOrQuery;
+    }
+    root = $;
+    query = elOrQuery;
+  }
+  // f.e. dom.find(el, "#foo")
+  else if (arguments.length === 2) {
+    root = elOrQuery;
+  }
+
+  return root.querySelector(query);
 }
 
 /**

diff --git a/test/integration/docsify.test.js b/test/integration/docsify.test.js
@@ -1,25 +1,48 @@
 const docsifyInit = require('../helpers/docsify-init');
 
-// Suite
-// -----------------------------------------------------------------------------
 describe('Docsify', function() {
-  // Tests
-  // ---------------------------------------------------------------------------
-  test('allows $docsify configuration to be a function', async () => {
-    const testConfig = jest.fn(vm => {
-      expect(vm).toBeInstanceOf(Object);
-      expect(vm.constructor.name).toEqual('Docsify');
-      expect(vm.$fetch).toBeInstanceOf(Function);
-      expect(vm.$resetEvents).toBeInstanceOf(Function);
-      expect(vm.route).toBeInstanceOf(Object);
-    });
+  describe('config options', () => {
+    test('allows $docsify configuration to be a function', async () => {
+      const testConfig = jest.fn(vm => {
+        expect(vm).toBeInstanceOf(Object);
+        expect(vm.constructor.name).toEqual('Docsify');
+        expect(vm.$fetch).toBeInstanceOf(Function);
+        expect(vm.$resetEvents).toBeInstanceOf(Function);
+        expect(vm.route).toBeInstanceOf(Object);
+      });
 
-    await docsifyInit({
-      config: testConfig,
+      await docsifyInit({
+        config: testConfig,
+      });
+
+      expect(typeof Docsify).toEqual('object');
+      expect(testConfig).toHaveBeenCalled();
     });
 
-    expect(typeof Docsify).toEqual('object');
-    expect(testConfig).toHaveBeenCalled();
+    describe('config.el', () => {
+      it('accepts an element instance', async () => {
+        const config = jest.fn(() => {
+          const app = document.querySelector('#app');
+          expect(app).toBeInstanceOf(HTMLElement);
+
+          return {
+            basePath: `${TEST_HOST}/docs/index.html#/`,
+            el: app,
+          };
+        });
+
+        await docsifyInit({
+          config,
+          testURL: `${TEST_HOST}/docs/index.html#/`,
+        });
+
+        expect(config).toHaveBeenCalled();
+
+        expect(document.querySelector('#main').textContent).toContain(
+          'A magical documentation site generator.'
+        );
+      });
+    });
   });
 
   test('provides the hooks and vm API to plugins', async () => {