From bd5f879cb859c024169ba621683c184fe1c20be2 Mon Sep 17 00:00:00 2001
From: "Yii.Guxing" <yii.guxing@outlook.com>
Date: Mon, 13 May 2024 22:40:53 +0800
Subject: [PATCH 1/7] feat: The timing of the `doneEach` hook call for the
 cover

The `doneEach` hook function for the cover should be called after the cover page HTML has been appended to the DOM.
---
 src/core/fetch/index.js | 30 +++++++++++++++++-------------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/src/core/fetch/index.js b/src/core/fetch/index.js
index 52c777ff9..60f7a25ae 100644
--- a/src/core/fetch/index.js
+++ b/src/core/fetch/index.js
@@ -150,7 +150,7 @@ export function Fetch(Base) {
       }
     }
 
-    _fetchCover() {
+    _fetchCover(cb = noop) {
       const { coverpage, requestHeaders } = this.config;
       const query = this.route.query;
       const root = getParentPath(this.route.path);
@@ -174,13 +174,17 @@ export function Fetch(Base) {
           path = this.router.getFile(root + path);
           this.coverIsHTML = /\.html$/g.test(path);
           get(path + stringifyQuery(query, ['id']), false, requestHeaders).then(
-            text => this._renderCover(text, coverOnly)
+            text => {
+              this._renderCover(text, coverOnly);
+              cb(coverOnly);
+            }
           );
         } else {
           this._renderCover(null, coverOnly);
+          cb(coverOnly);
         }
-
-        return coverOnly;
+      } else {
+        cb(false);
       }
     }
 
@@ -190,16 +194,16 @@ export function Fetch(Base) {
         cb();
       };
 
-      const onlyCover = this._fetchCover();
-
-      if (onlyCover) {
-        done();
-      } else {
-        this._fetch(() => {
-          onNavigate();
+      this._fetchCover(onlyCover => {
+        if (onlyCover) {
           done();
-        });
-      }
+        } else {
+          this._fetch(() => {
+            onNavigate();
+            done();
+          });
+        }
+      });
     }
 
     _fetchFallbackPage(path, qs, cb = noop) {

From dea1229ea18333f37cb0bb07dad6e7f519366c56 Mon Sep 17 00:00:00 2001
From: "Yii.Guxing" <yii.guxing@outlook.com>
Date: Wed, 29 May 2024 17:21:44 +0800
Subject: [PATCH 2/7] test: Add test cases for the `doneEach` hook

---
 test/e2e/plugins.test.js | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/test/e2e/plugins.test.js b/test/e2e/plugins.test.js
index 68534830d..ee3522685 100644
--- a/test/e2e/plugins.test.js
+++ b/test/e2e/plugins.test.js
@@ -158,6 +158,36 @@ test.describe('Plugins', () => {
     });
   });
 
+  test.describe('doneEach()', () => {
+    test('callback after cover loads', async ({ page }) => {
+      const consoleMessages = [];
+
+      page.on('console', msg => consoleMessages.push(msg.text()));
+
+      await docsifyInit({
+        config: {
+          plugins: [
+            function (hook) {
+              hook.doneEach(() => {
+                const homepageTitle = document.querySelector('#homepage-title');
+                const coverTitle = document.querySelector('#cover-title');
+                console.log(homepageTitle?.textContent);
+                console.log(coverTitle?.textContent);
+              });
+            },
+          ],
+        },
+        markdown: {
+          homepage: '# Hello World :id=homepage-title',
+          coverpage: '# Cover Page :id=cover-title',
+        },
+        // _logHTML: true,
+      });
+
+      await expect(consoleMessages).toEqual(['Hello World', 'Cover Page']);
+    });
+  });
+
   test.describe('route data accessible to plugins', () => {
     let routeData = null;
 

From 56c922fe43c3e24e369bd30bf2dd9ee1ef500d6a Mon Sep 17 00:00:00 2001
From: "Yii.Guxing" <yii.guxing@outlook.com>
Date: Wed, 29 May 2024 17:22:08 +0800
Subject: [PATCH 3/7] style: Fix eslint code style

---
 src/core/fetch/index.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/core/fetch/index.js b/src/core/fetch/index.js
index e296141ed..73cb54c81 100644
--- a/src/core/fetch/index.js
+++ b/src/core/fetch/index.js
@@ -177,7 +177,7 @@ export function Fetch(Base) {
             text => {
               this._renderCover(text, coverOnly);
               cb(coverOnly);
-            }
+            },
           );
         } else {
           this._renderCover(null, coverOnly);

From 837d04af17e7eb4d0532bf02d9005c8c2433841e Mon Sep 17 00:00:00 2001
From: "Yii.Guxing" <yii.guxing@outlook.com>
Date: Thu, 30 May 2024 15:13:56 +0800
Subject: [PATCH 4/7] fix(test): fix HTML logging

---
 test/helpers/docsify-init.js | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/test/helpers/docsify-init.js b/test/helpers/docsify-init.js
index bbc357022..de406f527 100644
--- a/test/helpers/docsify-init.js
+++ b/test/helpers/docsify-init.js
@@ -363,13 +363,13 @@ async function docsifyInit(options = {}) {
     }
 
     if (htmlArr.length) {
-      htmlArr.forEach(html => {
+      for (let html of htmlArr) {
         if (settings._logHTML.format !== false) {
-          html = prettier.format(html, { parser: 'html' });
+          html = await prettier.format(html, { parser: 'html' });
         }
 
         console.log(html);
-      });
+      }
     } else {
       console.warn(`docsify-init(): unable to match selector '${selector}'`);
     }

From ec48f93351b521057a1f9e457c5648bd72bef809 Mon Sep 17 00:00:00 2001
From: "Yii.Guxing" <yii.guxing@outlook.com>
Date: Thu, 30 May 2024 16:51:39 +0800
Subject: [PATCH 5/7] feat(test): add dynamic and asynchronous content
 provision support for test instances

---
 test/helpers/docsify-init.js | 54 ++++++++++++++++++------------------
 1 file changed, 27 insertions(+), 27 deletions(-)

diff --git a/test/helpers/docsify-init.js b/test/helpers/docsify-init.js
index de406f527..6fd4f5d0c 100644
--- a/test/helpers/docsify-init.js
+++ b/test/helpers/docsify-init.js
@@ -17,11 +17,11 @@ const docsifyURL = '/dist/docsify.js'; // Playwright
  * @param {Function|Object} [options.config] docsify configuration (merged with default)
  * @param {String} [options.html] HTML content to use for docsify `index.html` page
  * @param {Object} [options.markdown] Docsify markdown content
- * @param {String} [options.markdown.coverpage] coverpage markdown
- * @param {String} [options.markdown.homepage] homepage markdown
- * @param {String} [options.markdown.navbar] navbar markdown
- * @param {String} [options.markdown.sidebar] sidebar markdown
- * @param {Object} [options.routes] custom routes defined as `{ pathOrGlob: responseText }`
+ * @param {String|(()=>Promise<String>|String)} [options.markdown.coverpage] coverpage markdown
+ * @param {String|(()=>Promise<String>|String)} [options.markdown.homepage] homepage markdown
+ * @param {String|(()=>Promise<String>|String)} [options.markdown.navbar] navbar markdown
+ * @param {String|(()=>Promise<String>|String)} [options.markdown.sidebar] sidebar markdown
+ * @param {Record<String,String|(()=>Promise<String>|String)>} [options.routes] custom routes defined as `{ pathOrGlob: response }`
  * @param {String} [options.script] JS to inject via <script> tag
  * @param {String|String[]} [options.scriptURLs] External JS to inject via <script src="..."> tag(s)
  * @param {String} [options.style] CSS to inject via <style> tag
@@ -114,7 +114,7 @@ async function docsifyInit(options = {}) {
           ...options.markdown,
         })
           .filter(([key, markdown]) => key && markdown)
-          .map(([key, markdown]) => [key, stripIndent`${markdown}`]),
+          .map(([key, markdown]) => [key, markdown]),
       );
     },
     get routes() {
@@ -132,13 +132,12 @@ async function docsifyInit(options = {}) {
           ...options.routes,
         })
           // Remove items with falsey responseText
-          .filter(([url, responseText]) => url && responseText)
-          .map(([url, responseText]) => [
+          .filter(([url, response]) => url && response)
+          .map(([url, response]) => [
             // Convert relative to absolute URL
             new URL(url, settings.config.basePath || process.env.TEST_HOST)
               .href,
-            // Strip indentation from responseText
-            stripIndent`${responseText}`,
+            response,
           ]),
       );
 
@@ -173,29 +172,30 @@ async function docsifyInit(options = {}) {
     mock.setup();
   }
 
-  for (let [urlGlob, response] of Object.entries(settings.routes)) {
+  for (const [urlGlob, response] of Object.entries(settings.routes)) {
     const fileExtension = (urlGlob.match(reFileExtentionFromURL) || [])[1];
     const contentType = contentTypes[fileExtension];
-
-    if (typeof response === 'string') {
-      response = {
-        status: 200,
-        body: response,
-      };
-    }
-
-    // Specifying contentType required for Webkit
-    response.contentType = response.contentType || contentType || '';
+    const responseBody = async () => {
+      if (typeof response === 'string') {
+        return stripIndent`${response}`;
+      } else {
+        return stripIndent`${await response()}`;
+      }
+    };
 
     if (isJSDOM) {
-      mock.get(urlGlob, (req, res) => {
-        return res
-          .status(response.status)
-          .body(settings.routes[urlGlob])
-          .header('Content-Type', contentType);
+      mock.get(urlGlob, async (req, res) => {
+        const body = await responseBody();
+        return res.status(200).body(body).header('Content-Type', contentType);
       });
     } else {
-      await page.route(urlGlob, route => route.fulfill(response));
+      await page.route(urlGlob, async route => {
+        return route.fulfill({
+          status: 200,
+          body: await responseBody(),
+          contentType: contentType || '',
+        });
+      });
     }
   }
 

From 7cc7cdf0cb7c61baa9ddd4dd2bf190f5dad9db5b Mon Sep 17 00:00:00 2001
From: "Yii.Guxing" <yii.guxing@outlook.com>
Date: Thu, 30 May 2024 18:35:37 +0800
Subject: [PATCH 6/7] feat: cover page supports embedding external files

---
 src/core/fetch/index.js      | 15 ++++++----
 src/core/render/index.js     | 57 ++++++++++++++++++++++++------------
 test/e2e/embed-files.test.js | 33 +++++++++++++++++++++
 test/e2e/plugins.test.js     | 42 ++++++++++++++++++++++++--
 4 files changed, 121 insertions(+), 26 deletions(-)
 create mode 100644 test/e2e/embed-files.test.js

diff --git a/src/core/fetch/index.js b/src/core/fetch/index.js
index 73cb54c81..b5ab0dafd 100644
--- a/src/core/fetch/index.js
+++ b/src/core/fetch/index.js
@@ -170,18 +170,23 @@ export function Fetch(Base) {
         }
 
         const coverOnly = Boolean(path) && this.config.onlyCover;
+        const next = () => cb(coverOnly);
         if (path) {
           path = this.router.getFile(root + path);
           this.coverIsHTML = /\.html$/g.test(path);
           get(path + stringifyQuery(query, ['id']), false, requestHeaders).then(
-            text => {
-              this._renderCover(text, coverOnly);
-              cb(coverOnly);
+            text => this._renderCover(text, coverOnly, next),
+            (event, response) => {
+              this.coverIsHTML = false;
+              this._renderCover(
+                `# ${response.status} - ${response.statusText}`,
+                coverOnly,
+                next,
+              );
             },
           );
         } else {
-          this._renderCover(null, coverOnly);
-          cb(coverOnly);
+          this._renderCover(null, coverOnly, next);
         }
       } else {
         cb(false);
diff --git a/src/core/render/index.js b/src/core/render/index.js
index bf2f859d6..d3faeff85 100644
--- a/src/core/render/index.js
+++ b/src/core/render/index.js
@@ -382,7 +382,7 @@ export function Render(Base) {
       });
     }
 
-    _renderCover(text, coverOnly) {
+    _renderCover(text, coverOnly, next) {
       const el = dom.getNode('.cover');
 
       dom.toggleClass(
@@ -392,37 +392,56 @@ export function Render(Base) {
       );
       if (!text) {
         dom.toggleClass(el, 'remove', 'show');
+        next();
         return;
       }
 
       dom.toggleClass(el, 'add', 'show');
 
-      let html = this.coverIsHTML ? text : this.compiler.cover(text);
+      const callback = html => {
+        const m = html
+          .trim()
+          .match('<p><img.*?data-origin="(.*?)"[^a]+alt="(.*?)">([^<]*?)</p>$');
 
-      const m = html
-        .trim()
-        .match('<p><img.*?data-origin="(.*?)"[^a]+alt="(.*?)">([^<]*?)</p>$');
+        if (m) {
+          if (m[2] === 'color') {
+            el.style.background = m[1] + (m[3] || '');
+          } else {
+            let path = m[1];
 
-      if (m) {
-        if (m[2] === 'color') {
-          el.style.background = m[1] + (m[3] || '');
-        } else {
-          let path = m[1];
+            dom.toggleClass(el, 'add', 'has-mask');
+            if (!isAbsolutePath(m[1])) {
+              path = getPath(this.router.getBasePath(), m[1]);
+            }
 
-          dom.toggleClass(el, 'add', 'has-mask');
-          if (!isAbsolutePath(m[1])) {
-            path = getPath(this.router.getBasePath(), m[1]);
+            el.style.backgroundImage = `url(${path})`;
+            el.style.backgroundSize = 'cover';
+            el.style.backgroundPosition = 'center center';
           }
 
-          el.style.backgroundImage = `url(${path})`;
-          el.style.backgroundSize = 'cover';
-          el.style.backgroundPosition = 'center center';
+          html = html.replace(m[0], '');
         }
 
-        html = html.replace(m[0], '');
-      }
+        this._renderTo('.cover-main', html);
+        next();
+      };
 
-      this._renderTo('.cover-main', html);
+      // TODO: Call the 'beforeEach' and 'afterEach' hooks.
+      // However, when the cover and the home page are on the same page,
+      // the 'beforeEach' and 'afterEach' hooks are called multiple times.
+      // It is difficult to determine the target of the hook within the
+      // hook functions. We might need to make some changes.
+      if (this.coverIsHTML) {
+        callback(text);
+      } else {
+        prerenderEmbed(
+          {
+            compiler: this.compiler,
+            raw: text,
+          },
+          tokens => callback(this.compiler.cover(tokens)),
+        );
+      }
     }
 
     _updateRender() {
diff --git a/test/e2e/embed-files.test.js b/test/e2e/embed-files.test.js
new file mode 100644
index 000000000..0fcc4888a
--- /dev/null
+++ b/test/e2e/embed-files.test.js
@@ -0,0 +1,33 @@
+import docsifyInit from '../helpers/docsify-init.js';
+import { test, expect } from './fixtures/docsify-init-fixture.js';
+
+test.describe('Embed files', () => {
+  const routes = {
+    'fragment.md': '## Fragment',
+  };
+
+  test('embed into homepage', async ({ page }) => {
+    await docsifyInit({
+      routes,
+      markdown: {
+        homepage: "# Hello World\n\n[fragment](fragment.md ':include')",
+      },
+      _logHTML: {},
+    });
+
+    await expect(page.locator('#main')).toContainText('Fragment');
+  });
+
+  test('embed into cover', async ({ page }) => {
+    await docsifyInit({
+      routes,
+      markdown: {
+        homepage: '# Hello World',
+        coverpage: "# Cover\n\n[fragment](fragment.md ':include')",
+      },
+      _logHTML: {},
+    });
+
+    await expect(page.locator('.cover-main')).toContainText('Fragment');
+  });
+});
diff --git a/test/e2e/plugins.test.js b/test/e2e/plugins.test.js
index ee3522685..00f31b0ad 100644
--- a/test/e2e/plugins.test.js
+++ b/test/e2e/plugins.test.js
@@ -179,13 +179,51 @@ test.describe('Plugins', () => {
         },
         markdown: {
           homepage: '# Hello World :id=homepage-title',
-          coverpage: '# Cover Page :id=cover-title',
+          coverpage: () => {
+            return new Promise(resolve => {
+              setTimeout(() => resolve('# Cover Page :id=cover-title'), 500);
+            });
+          },
         },
-        // _logHTML: true,
+        // _logHTML: {},
       });
 
       await expect(consoleMessages).toEqual(['Hello World', 'Cover Page']);
     });
+
+    test('only cover', async ({ page }) => {
+      const consoleMessages = [];
+
+      page.on('console', msg => consoleMessages.push(msg.text()));
+
+      await docsifyInit({
+        config: {
+          onlyCover: true,
+          plugins: [
+            function (hook) {
+              hook.doneEach(() => {
+                const homepageTitle = document.querySelector('#homepage-title');
+                const coverTitle = document.querySelector('#cover-title');
+                console.log(homepageTitle?.textContent);
+                console.log(coverTitle?.textContent);
+              });
+            },
+          ],
+        },
+        markdown: {
+          homepage: '# Hello World :id=homepage-title',
+          coverpage: () => {
+            return new Promise(resolve => {
+              setTimeout(() => resolve('# Cover Page :id=cover-title'), 500);
+            });
+          },
+        },
+        waitForSelector: '.cover-main > *:first-child',
+        // _logHTML: {},
+      });
+
+      await expect(consoleMessages).toEqual(['undefined', 'Cover Page']);
+    });
   });
 
   test.describe('route data accessible to plugins', () => {

From 0333d96e45fe1b7a56a920d9e079a93d8a401b83 Mon Sep 17 00:00:00 2001
From: "Yii.Guxing" <yii.guxing@outlook.com>
Date: Thu, 30 May 2024 21:47:34 +0800
Subject: [PATCH 7/7] test: disable logging

---
 test/e2e/embed-files.test.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/test/e2e/embed-files.test.js b/test/e2e/embed-files.test.js
index 0fcc4888a..46ae1d1c3 100644
--- a/test/e2e/embed-files.test.js
+++ b/test/e2e/embed-files.test.js
@@ -12,7 +12,7 @@ test.describe('Embed files', () => {
       markdown: {
         homepage: "# Hello World\n\n[fragment](fragment.md ':include')",
       },
-      _logHTML: {},
+      // _logHTML: {},
     });
 
     await expect(page.locator('#main')).toContainText('Fragment');
@@ -25,7 +25,7 @@ test.describe('Embed files', () => {
         homepage: '# Hello World',
         coverpage: "# Cover\n\n[fragment](fragment.md ':include')",
       },
-      _logHTML: {},
+      // _logHTML: {},
     });
 
     await expect(page.locator('.cover-main')).toContainText('Fragment');