From 7152439659dada8c0241a2c09be73bed0b8a537b Mon Sep 17 00:00:00 2001
From: Luffy <52o@qq52o.cn>
Date: Fri, 11 Sep 2026 15:06:04 +0800
Subject: [PATCH 1/2] fix: support inline ES modules with executeScript

Execute inline module scripts through a new script element so the browser
can handle static imports, exports, and top-level await.

Preserve classic script execution and first-script selection behavior.
Keep external modules handled by the external-script plugin.

Add browser regression tests and a manual demo. Document asynchronous
execution and relative import resolution.
---
 docs/configuration.md           |  14 +-
 src/core/render/index.js        |  18 ++-
 test/e2e/execute-script.test.js | 246 ++++++++++++++++++++++++++++++++
 3 files changed, 276 insertions(+), 2 deletions(-)
 create mode 100644 test/e2e/execute-script.test.js

diff --git a/docs/configuration.md b/docs/configuration.md
index 16d1fded4..7d48d40a5 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -227,7 +227,19 @@ window.$docsify = {
 </script>
 ```
 
-Note that if you are running an external script, e.g. an embedded jsfiddle demo, make sure to include the [external-script](plugins.md?id=external-script) plugin.
+Inline ES modules are supported with `type="module"`:
+
+```html
+<script type="module">
+  import { message } from './example.js';
+
+  console.log(message);
+</script>
+```
+
+Modules execute asynchronously, and Docsify does not wait for them before running its lifecycle hooks. Relative imports resolve against the HTML document URL, rather than the Markdown file URL. Only the first non-template script is considered for execution, whether it is a classic script or a module.
+
+Note that if you are running an external script with a `src` attribute, e.g. an embedded jsfiddle demo, make sure to include the [external-script](plugins.md?id=external-script) plugin. This also applies to `<script type="module" src="...">`.
 
 ## ext
 
diff --git a/src/core/render/index.js b/src/core/render/index.js
index 1d55c66a3..cc68d56f6 100644
--- a/src/core/render/index.js
+++ b/src/core/render/index.js
@@ -81,7 +81,23 @@ export function Render(Base) {
         return false;
       }
 
-      new Function(code)();
+      if (script.getAttribute('type') === 'module') {
+        // External scripts are handled by the external-script plugin.
+        if (script.hasAttribute('src')) {
+          return false;
+        }
+
+        // Scripts inserted via innerHTML are inert. Create a fresh element
+        // so the browser can execute imports and exports as an ES module.
+        const moduleScript = document.createElement('script');
+        for (const { name, value } of script.attributes) {
+          moduleScript.setAttribute(name, value);
+        }
+        moduleScript.textContent = code;
+        script.replaceWith(moduleScript);
+      } else {
+        new Function(code)();
+      }
     }
 
     #formatUpdated(html, updated, fn) {
diff --git a/test/e2e/execute-script.test.js b/test/e2e/execute-script.test.js
new file mode 100644
index 000000000..3fe8d4aaf
--- /dev/null
+++ b/test/e2e/execute-script.test.js
@@ -0,0 +1,246 @@
+import docsifyInit from '../helpers/docsify-init.js';
+import { test, expect } from './fixtures/docsify-init-fixture.js';
+
+test.describe('executeScript', () => {
+  for (const width of [1280, 375]) {
+    test(`executes inline modules on navigation at ${width}px`, async ({
+      page,
+    }) => {
+      const errors = [];
+      page.on('pageerror', error => errors.push(error.message));
+      await page.setViewportSize({ width, height: 800 });
+
+      const markdown = `
+        # Module example
+
+        [Next page](next.md)
+
+        <p id="result">Loading</p>
+
+        <script type="module" data-example="module">
+          import { value } from './module-value.js';
+          export const moduleValue = await Promise.resolve(value);
+          window.moduleRuns = (window.moduleRuns || 0) + 1;
+          document.querySelector('#result').textContent = moduleValue;
+        </script>
+
+        <script>
+          throw new Error('The second script must not execute');
+        </script>
+      `;
+
+      await docsifyInit({
+        config: { executeScript: true },
+        markdown: { homepage: markdown },
+        routes: {
+          'next.md': markdown.replace('# Module example', '# Next page'),
+          'module-value.js': `
+            window.dependencyRuns = (window.dependencyRuns || 0) + 1;
+            export const value = 'Module loaded';
+          `,
+        },
+        styleURLs: ['/dist/themes/core.css'],
+      });
+
+      await expect(page.locator('#result')).toHaveText('Module loaded');
+      await expect(page.locator('#result')).toBeInViewport();
+      await expect(page.locator('script[data-example]')).toHaveAttribute(
+        'type',
+        'module',
+      );
+      await page.getByRole('link', { name: 'Next page', exact: true }).click();
+      await expect(page.locator('h1')).toHaveText('Next page');
+      await expect(page.locator('#result')).toHaveText('Module loaded');
+      await page.goBack();
+      await expect(page.locator('h1')).toHaveText('Module example');
+      await expect(page.locator('#result')).toHaveText('Module loaded');
+      expect(
+        await page.evaluate(() => ({
+          moduleRuns: window.moduleRuns,
+          dependencyRuns: window.dependencyRuns,
+          moduleValue: window.moduleValue,
+        })),
+      ).toEqual({ moduleRuns: 3, dependencyRuns: 1, moduleValue: undefined });
+      expect(errors).toEqual([]);
+    });
+  }
+
+  test('keeps classic scripts in function scope and skips templates', async ({
+    page,
+  }) => {
+    await docsifyInit({
+      config: { executeScript: true },
+      markdown: {
+        homepage: `
+          <p id="result">Waiting</p>
+
+          <script type="text/x-template">{{ template }}</script>
+
+          <script>
+            var localValue = 'Classic script';
+            document.querySelector('#result').textContent = localValue;
+            return;
+          </script>
+
+          <script type="module">
+            document.querySelector('#result').textContent = 'Second script';
+          </script>
+        `,
+      },
+    });
+
+    await expect(page.locator('#result')).toHaveText('Classic script');
+    expect(await page.evaluate(() => window.localValue)).toBeUndefined();
+  });
+
+  for (const type of ['', 'module']) {
+    for (const executeScript of [false, null]) {
+      test(`does not execute type="${type}" with executeScript=${executeScript}`, async ({
+        page,
+      }) => {
+        const errors = [];
+        page.on('pageerror', error => errors.push(error.message));
+        await docsifyInit({
+          config: { executeScript },
+          markdown: {
+            homepage: `
+              # Disabled script
+
+              <script type="${type}">
+                throw new Error('Script must not execute');
+              </script>
+            `,
+          },
+        });
+
+        await expect(page.locator('h1')).toHaveText('Disabled script');
+        expect(errors).toEqual([]);
+      });
+    }
+  }
+
+  for (const script of [
+    '',
+    '<script> </script>',
+    '<script type="module"> </script>',
+    '<script type="text/x-template">{{ template }}</script>',
+  ]) {
+    test(`handles an empty page script: ${JSON.stringify(script)}`, async ({
+      page,
+    }) => {
+      const errors = [];
+      page.on('pageerror', error => errors.push(error.message));
+      await docsifyInit({
+        config: { executeScript: true },
+        markdown: { homepage: `# Empty script\n\n${script}` },
+      });
+
+      await expect(page.locator('h1')).toHaveText('Empty script');
+      expect(errors).toEqual([]);
+    });
+  }
+
+  for (const [scriptURLs, expectedText] of [
+    [[], 'Waiting'],
+    [['/dist/plugins/external-script.js'], 'External module'],
+  ]) {
+    test(`leaves external modules to the plugin (${expectedText})`, async ({
+      page,
+    }) => {
+      const errors = [];
+      page.on('pageerror', error => errors.push(error.message));
+      await docsifyInit({
+        config: { executeScript: true },
+        scriptURLs,
+        markdown: {
+          homepage: `
+            <p id="result">Waiting</p>
+
+            <script type="module" src="./external-module.js">
+              throw new Error('Inline content must not execute with src');
+            </script>
+          `,
+        },
+        routes: {
+          'external-module.js': `
+            document.querySelector('#result').textContent = 'External module';
+          `,
+        },
+      });
+
+      await expect(page.locator('#result')).toHaveText(expectedText);
+      expect(errors).toEqual([]);
+    });
+  }
+
+  test('renders the document while a module is loading', async ({ page }) => {
+    let releaseModule;
+    const moduleReady = new Promise(resolve => {
+      releaseModule = resolve;
+    });
+    await page.route('**/slow-module.js', async route => {
+      await moduleReady;
+      await route.fulfill({
+        contentType: 'application/javascript',
+        body: 'export const value = "Loaded";',
+      });
+    });
+    const request = page.waitForRequest('**/slow-module.js');
+
+    try {
+      await docsifyInit({
+        config: { executeScript: true },
+        markdown: {
+          homepage: `
+            # Loading example
+
+            <p id="result">Loading</p>
+
+            <script type="module">
+              import { value } from '${process.env.TEST_HOST}/slow-module.js';
+              document.querySelector('#result').textContent = value;
+            </script>
+          `,
+        },
+      });
+
+      await request;
+      await expect(page.locator('h1')).toHaveText('Loading example');
+      await expect(page.locator('#result')).toHaveText('Loading');
+    } finally {
+      releaseModule();
+    }
+
+    await expect(page.locator('#result')).toHaveText('Loaded');
+  });
+
+  test('keeps navigation working after a module fails to load', async ({
+    page,
+  }) => {
+    await page.route('**/missing-module.js', route => route.abort());
+    const failedRequest = page.waitForEvent('requestfailed', request =>
+      request.url().endsWith('/missing-module.js'),
+    );
+
+    await docsifyInit({
+      config: { executeScript: true },
+      markdown: {
+        homepage: `
+          # Failed module
+
+          [Next page](next.md)
+
+          <script type="module">
+            import './missing-module.js';
+          </script>
+        `,
+      },
+      routes: { 'next.md': '# Next page' },
+    });
+
+    expect((await failedRequest).failure()).toBeTruthy();
+    await expect(page.locator('h1')).toHaveText('Failed module');
+    await page.getByRole('link', { name: 'Next page', exact: true }).click();
+    await expect(page.locator('h1')).toHaveText('Next page');
+  });
+});

From 6a9ebecda6ba884f4c927b3896a12ffc61a07ebc Mon Sep 17 00:00:00 2001
From: Luffy <52o@qq52o.cn>
Date: Wed, 28 Oct 2026 16:29:18 +0800
Subject: [PATCH 2/2] feat(module): implement relative module imports for
 Markdown content

---
 docs/configuration.md                         |  10 +-
 package-lock.json                             |   7 +
 package.json                                  |   1 +
 rollup.config.js                              |   8 +
 src/core/render/index.js                      |  29 +-
 src/core/render/module-script.js              |  38 +++
 src/core/util/ajax.js                         |   4 +-
 test/e2e/module-paths.test.js                 | 291 ++++++++++++++++++
 test/manual/execute-script/README.md          |  21 ++
 test/manual/execute-script/content/README.md  |   5 +
 .../content/guide/demo-module.js              |   6 +
 .../execute-script/content/guide/page.md      |  12 +
 test/manual/execute-script/content/shared.js  |   1 +
 test/manual/execute-script/index.html         |  29 ++
 test/manual/execute-script/server.js          |  26 ++
 test/unit/module-script.test.js               |  77 +++++
 tsconfig.json                                 |   5 +
 17 files changed, 563 insertions(+), 7 deletions(-)
 create mode 100644 src/core/render/module-script.js
 create mode 100644 test/e2e/module-paths.test.js
 create mode 100644 test/manual/execute-script/README.md
 create mode 100644 test/manual/execute-script/content/README.md
 create mode 100644 test/manual/execute-script/content/guide/demo-module.js
 create mode 100644 test/manual/execute-script/content/guide/page.md
 create mode 100644 test/manual/execute-script/content/shared.js
 create mode 100644 test/manual/execute-script/index.html
 create mode 100644 test/manual/execute-script/server.js
 create mode 100644 test/unit/module-script.test.js

diff --git a/docs/configuration.md b/docs/configuration.md
index 7d48d40a5..b76c9db1a 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -237,7 +237,15 @@ Inline ES modules are supported with `type="module"`:
 </script>
 ```
 
-Modules execute asynchronously, and Docsify does not wait for them before running its lifecycle hooks. Relative imports resolve against the HTML document URL, rather than the Markdown file URL. Only the first non-template script is considered for execution, whether it is a classic script or a module.
+Modules execute asynchronously, and Docsify does not wait for them before running its lifecycle hooks. Only the first non-template script is considered for execution, whether it is a classic script or a module.
+
+Relative specifiers (`./` and `../`) in inline modules resolve against the URL of the Markdown content being rendered, in both `hash` and `history` router modes. This applies to static imports, re-exports, and dynamic imports with quoted string literals, such as `import('./example.js')`. Docsify uses the content URL after applying `basePath`, `alias`, and `homepage`, including redirects, language fallback pages, and custom 404 pages. Virtual routes use their mapped Markdown file URL.
+
+For example, if the Markdown file is `/content/guide/page.md`, `./example.js` resolves to `/content/guide/example.js` and `../shared.js` resolves to `/content/shared.js`. A hash route at `/app/index.html#/guide/page` with the default `basePath` loads `/app/guide/page.md`; `index.html` is not treated as a directory.
+
+Absolute URLs, root-relative paths (`/example.js`), and bare specifiers (`vue`) retain their native browser behavior, including import maps. `import.meta.url` and computed dynamic imports such as `import(path)`, `import('./' + name)`, and template literals are not rewritten; they retain the HTML document as their base. Imports inside external modules resolve relative to those modules, as usual.
+
+If an inline module cannot be parsed, Docsify reports the error without executing it, and continues rendering the document.
 
 Note that if you are running an external script with a `src` attribute, e.g. an embedded jsfiddle demo, make sure to include the [external-script](plugins.md?id=external-script) plugin. This also applies to `<script type="module" src="...">`.
 
diff --git a/package-lock.json b/package-lock.json
index 602b22db0..9bfccc0df 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -12,6 +12,7 @@
       "dependencies": {
         "common-tags": "^1.8.0",
         "dexie": "^4.0.11",
+        "es-module-lexer": "^3.0.4",
         "marked": "^18.0.3",
         "medium-zoom": "^1.1.0",
         "opencollective-postinstall": "^2.0.2",
@@ -7852,6 +7853,12 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/es-module-lexer": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-3.0.4.tgz",
+      "integrity": "sha512-BldNY5mwkVu+cQ5Ymn3e6hB9Sx8XHx4ZevWbiUyZbfKxJxYO27Hf0wfzkxIaD5CAJMaGl3YspKELj0ff/7nCMA==",
+      "license": "MIT"
+    },
     "node_modules/es-object-atoms": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz",
diff --git a/package.json b/package.json
index 895d40b19..06caa1a96 100644
--- a/package.json
+++ b/package.json
@@ -47,6 +47,7 @@
   "dependencies": {
     "common-tags": "^1.8.0",
     "dexie": "^4.0.11",
+    "es-module-lexer": "^3.0.4",
     "marked": "^18.0.3",
     "medium-zoom": "^1.1.0",
     "opencollective-postinstall": "^2.0.2",
diff --git a/rollup.config.js b/rollup.config.js
index 18245bcdf..fdea1c5f1 100644
--- a/rollup.config.js
+++ b/rollup.config.js
@@ -55,6 +55,14 @@ const baseConfig = {
     resolve(),
     commonjs(),
     css(),
+    // Run the synchronous lexer as plain JS. asm.js is only an optimization
+    // hint and produces a deprecation warning in Firefox, even before use.
+    replace({
+      include: '**/es-module-lexer/dist/lexer.asm.js',
+      preventAssignment: true,
+      delimiters: ['', ''],
+      values: { '"use asm";': '' },
+    }),
     replace({
       preventAssignment: true,
       values: {
diff --git a/src/core/render/index.js b/src/core/render/index.js
index cc68d56f6..b9c9fef9b 100644
--- a/src/core/render/index.js
+++ b/src/core/render/index.js
@@ -11,6 +11,7 @@ import { isExternal, isPrimitive } from '../util/core.js';
 import { Compiler } from './compiler.js';
 import * as tpl from './tpl.js';
 import { prerenderEmbed } from './embed.js';
+import { resolveModuleSpecifiers } from './module-script.js';
 
 /** @typedef {import('../Docsify.js').Constructor} Constructor */
 
@@ -66,7 +67,8 @@ export function Render(Base) {
       });
     }
 
-    #executeScript() {
+    /** @param {string} moduleBaseURL */
+    #executeScript(moduleBaseURL) {
       const script = dom
         .findAll('.markdown-section>script')
         .filter(
@@ -93,7 +95,18 @@ export function Render(Base) {
         for (const { name, value } of script.attributes) {
           moduleScript.setAttribute(name, value);
         }
-        moduleScript.textContent = code;
+        try {
+          moduleScript.textContent = resolveModuleSpecifiers(
+            code,
+            moduleBaseURL,
+          );
+        } catch (error) {
+          // Report invalid modules without interrupting document rendering.
+          queueMicrotask(() => {
+            throw error;
+          });
+          return false;
+        }
         script.replaceWith(moduleScript);
       } else {
         new Function(code)();
@@ -111,7 +124,7 @@ export function Render(Base) {
       return html.replace(/{docsify-updated}/g, updated);
     }
 
-    #renderMain(html) {
+    #renderMain(html, moduleBaseURL) {
       const docsifyConfig = this.config;
       const markdownElm = dom.find('.markdown-section');
       const vueVersion =
@@ -151,7 +164,7 @@ export function Render(Base) {
         docsifyConfig.executeScript ||
         ('Vue' in window && docsifyConfig.executeScript !== false)
       ) {
-        this.#executeScript();
+        this.#executeScript(moduleBaseURL);
       }
 
       // Handle Vue content not mounted by markdown <script>
@@ -572,6 +585,12 @@ export function Render(Base) {
 
     _renderMain(text, opt = {}, next) {
       const { response } = this.route;
+      // Fetch metadata identifies redirects, fallback pages, and 404 pages.
+      // Virtual routes use their mapped file URL instead. Capture this before
+      // asynchronous hooks run, while the route still belongs to this content.
+      const moduleBaseURL =
+        opt.url ||
+        new URL(this.router.getFile(this.route.path), document.baseURI).href;
 
       // Note: It is possible for the response to be undefined in environments
       // where XMLHttpRequest has been modified or mocked
@@ -591,7 +610,7 @@ export function Render(Base) {
           }
 
           this.callHook('afterEach', html, hookData => {
-            this.#renderMain(hookData);
+            this.#renderMain(hookData, moduleBaseURL);
             next();
           });
         };
diff --git a/src/core/render/module-script.js b/src/core/render/module-script.js
new file mode 100644
index 000000000..bb02c732f
--- /dev/null
+++ b/src/core/render/module-script.js
@@ -0,0 +1,38 @@
+import { parse } from 'es-module-lexer/js';
+
+/**
+ * Resolve relative module specifiers without changing strings, comments,
+ * import.meta, or computed dynamic imports. The JS lexer runs synchronously
+ * and does not require WebAssembly initialization or eval permissions.
+ *
+ * @param {string} code
+ * @param {string} baseURL URL of the Markdown content being rendered
+ * @returns {string}
+ */
+export function resolveModuleSpecifiers(code, baseURL) {
+  const [imports] = parse(code, baseURL);
+
+  // Work backwards so replacements do not invalidate the lexer's offsets.
+  for (let i = imports.length - 1; i >= 0; i--) {
+    const entry = imports[i];
+    const specifier = entry.specifier;
+    const dynamic = entry.type === 'dynamic';
+
+    if (
+      !specifier ||
+      !/^(?:\.\/|\.\.\/)/.test(specifier) ||
+      (dynamic && (entry.glob || !['"', "'"].includes(code[entry.start])))
+    ) {
+      continue;
+    }
+
+    // Static offsets omit quotes; dynamic offsets include the whole literal.
+    // Replace both quotes too, to safely encode URLs containing apostrophes.
+    const start = dynamic ? entry.start : entry.start - 1;
+    const end = dynamic ? entry.end : entry.end + 1;
+    const url = new URL(specifier, baseURL).href;
+    code = code.slice(0, start) + JSON.stringify(url) + code.slice(end);
+  }
+
+  return code;
+}
diff --git a/src/core/util/ajax.js b/src/core/util/ajax.js
index 0c442d1a0..f893af4e6 100644
--- a/src/core/util/ajax.js
+++ b/src/core/util/ajax.js
@@ -3,7 +3,7 @@
 import progressbar from '../render/progressbar.js';
 import { noop } from './core.js';
 
-/** @typedef {{updatedAt: string}} CacheOpt */
+/** @typedef {{updatedAt: string, url: string}} CacheOpt */
 /** @typedef {{content: string, opt: CacheOpt, response: ResponseStatus}} CacheItem */
 /** @typedef {{ok: boolean, status: number, statusText: string}} ResponseStatus */
 /** @type {Record<string, CacheItem>} */
@@ -89,6 +89,8 @@ export function get(url, hasBar = false, headers = {}) {
             content: target.response,
             opt: {
               updatedAt: xhr.getResponseHeader('last-modified') ?? '',
+              // Preserve the content location across redirects and cache hits.
+              url: xhr.responseURL || new URL(url, document.baseURI).href,
             },
             response: getResponseStatus(event),
           });
diff --git a/test/e2e/module-paths.test.js b/test/e2e/module-paths.test.js
new file mode 100644
index 000000000..ee462a7fb
--- /dev/null
+++ b/test/e2e/module-paths.test.js
@@ -0,0 +1,291 @@
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import docsifyInit from '../helpers/docsify-init.js';
+import { test, expect } from './fixtures/docsify-init-fixture.js';
+
+const home = '# Home\n\n[Guide](/guide/page)';
+const guide = `
+  # Guide
+
+  <p id="result">Loading</p>
+
+  <script type="module">
+    import /* comment */ { value } from './dep.js';
+    document.querySelector('#result').textContent = value;
+  </script>
+`;
+
+async function initSite(options) {
+  await docsifyInit({
+    ...options,
+    config: {
+      ...options.config,
+      alias: { '/module-host.html': '/', ...options.config.alias },
+    },
+  });
+}
+
+// docsifyInit accepts text fixtures; HTTP statuses and headers need native routes.
+async function mockFiles(page, files) {
+  for (const [path, response] of Object.entries(files)) {
+    await page.route(
+      new URL(path, `${process.env.TEST_HOST}/content/`).href,
+      route =>
+        route.fulfill({
+          contentType: path.endsWith('.js')
+            ? 'application/javascript'
+            : 'text/markdown',
+          ...(typeof response === 'string' ? { body: response } : response),
+        }),
+    );
+  }
+}
+
+async function startRedirectServer() {
+  const docsify = await readFile(
+    new URL('../../dist/docsify.js', import.meta.url),
+  );
+  const server = createServer((request, response) => {
+    response.setHeader('Access-Control-Allow-Origin', '*');
+    if (request.url === '/dist/docsify.js') {
+      response.setHeader('Content-Type', 'application/javascript');
+      response.end(docsify);
+    } else if (request.url === '/redirect.md') {
+      response.writeHead(302, { Location: '/actual/page.md' }).end();
+    } else if (request.url === '/actual/page.md') {
+      response.setHeader('Content-Type', 'text/markdown');
+      response.end(guide);
+    } else if (request.url === '/actual/dep.js') {
+      response.setHeader('Content-Type', 'application/javascript');
+      response.end('export const value = "Redirected";');
+    } else {
+      response.writeHead(404).end();
+    }
+  });
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  return server;
+}
+
+for (const routerMode of ['hash', 'history']) {
+  const testURL = `${process.env.TEST_HOST}/module-host.html`;
+  test.describe(`Markdown module paths (${routerMode})`, () => {
+    test.beforeEach(async ({ page }) => {
+      await page.addInitScript(mode => {
+        if (mode === 'hash') {
+          history.replaceState(null, '', location.pathname + '#/');
+        }
+      }, routerMode);
+    });
+    for (const width of [1280, 375]) {
+      test(`resolves imports on navigation at ${width}px`, async ({ page }) => {
+        const errors = [];
+        page.on('pageerror', error => errors.push(error.message));
+        await page.setViewportSize({ width, height: 800 });
+        const markdown = `
+          # Guide
+
+          [Other](/guide/other)
+
+          <p id="result">Loading</p>
+
+          <script type="module">
+            import /* comment */ { value } from './dep.js';
+            import './side-effect.js';
+            import { root } from '/root.js';
+            export { shared } from '../shared.js';
+            export * from './more.js';
+            const { dynamic } = await import(/* comment */ '../dynamic.js');
+            const text = "import './untouched.js'";
+            window.moduleVisits = (window.moduleVisits || 0) + 1;
+            document.querySelector('#result').textContent =
+              [value, window.sideEffect, root, dynamic, text, window.moduleVisits].join('|');
+          </script>
+        `;
+
+        await initSite({
+          testURL,
+          config: { executeScript: true, routerMode, basePath: '/content/' },
+          markdown: { homepage: home },
+          routes: {
+            'guide/page.md': markdown,
+            'guide/other.md': markdown.replace('# Guide', '# Other'),
+            'guide/dep.js': "export { value } from './nested.js';",
+            'guide/nested.js': 'export const value = "nested";',
+            'guide/side-effect.js': 'window.sideEffect = "side";',
+            'guide/more.js': 'export const more = true;',
+            'shared.js': 'export const shared = true;',
+            'dynamic.js': 'export const dynamic = "dynamic";',
+            '/root.js': 'export const root = "root";',
+          },
+          styleURLs: ['/dist/themes/core.css'],
+        });
+
+        const result = page.locator('#result');
+        const expected = "nested|side|root|dynamic|import './untouched.js'|";
+        await page.getByRole('link', { name: 'Guide', exact: true }).click();
+        await expect(result).toHaveText(`${expected}1`);
+        await expect(result).toBeInViewport();
+        await page.getByRole('link', { name: 'Other', exact: true }).click();
+        await expect(result).toHaveText(`${expected}2`);
+        await page.goBack();
+        await expect(result).toHaveText(`${expected}3`);
+        expect(errors).toEqual([]);
+      });
+    }
+
+    for (const { name, config, files } of [
+      {
+        name: 'alias and custom extension',
+        config: { ext: '.txt', alias: { '/guide/page': '/actual/page' } },
+        files: {
+          'actual/page.txt': guide,
+          'actual/dep.js': 'export const value = "OK";',
+        },
+      },
+      {
+        name: 'remote alias',
+        config: {
+          alias: { '/guide/page': 'https://modules.example/actual/page.md' },
+        },
+        files: {
+          'https://modules.example/actual/page.md': {
+            body: guide,
+            headers: { 'Access-Control-Allow-Origin': '*' },
+          },
+          'https://modules.example/actual/dep.js': {
+            body: 'export const value = "OK";',
+            headers: { 'Access-Control-Allow-Origin': '*' },
+          },
+        },
+      },
+      {
+        name: 'virtual route',
+        config: { routes: { '/guide/page': guide } },
+        files: { 'guide/dep.js': 'export const value = "OK";' },
+      },
+      {
+        name: 'language fallback',
+        config: {
+          fallbackLanguages: ['guide'],
+          fallbackDefaultLanguage: '/en',
+        },
+        files: {
+          'guide/page.md': { status: 404, body: 'Missing' },
+          'en/page.md': guide,
+          'en/dep.js': 'export const value = "OK";',
+        },
+      },
+      {
+        name: 'custom 404 page',
+        config: { notFoundPage: 'errors/not-found.md' },
+        files: {
+          'guide/page.md': { status: 404, body: 'Missing' },
+          'errors/not-found.md': guide,
+          'errors/dep.js': 'export const value = "OK";',
+        },
+      },
+    ]) {
+      test(`uses the content URL for ${name}`, async ({ page }) => {
+        const errors = [];
+        page.on('pageerror', error => errors.push(error.message));
+        await mockFiles(page, files);
+        await initSite({
+          testURL,
+          config: {
+            executeScript: true,
+            routerMode,
+            basePath: '/content/',
+            ...config,
+          },
+          markdown: { homepage: home },
+        });
+
+        await page.getByRole('link', { name: 'Guide', exact: true }).click();
+        await expect(page.locator('#result')).toHaveText('OK');
+        expect(errors).toEqual([]);
+      });
+    }
+
+    test('uses a nested homepage URL', async ({ page }) => {
+      await initSite({
+        testURL,
+        config: {
+          executeScript: true,
+          routerMode,
+          basePath: '/content/',
+          homepage: 'start/home.md',
+        },
+        routes: {
+          'start/home.md': guide,
+          'start/dep.js': 'export const value = "Homepage";',
+        },
+      });
+      await expect(page.locator('#result')).toHaveText('Homepage');
+    });
+
+    test('uses the response URL after a redirect, including cached navigation', async ({
+      page,
+    }) => {
+      // A real redirect verifies XMLHttpRequest.responseURL end to end,
+      // including WebKit, which cannot fulfill a mocked redirect response.
+      const server = await startRedirectServer();
+      try {
+        const origin = `http://127.0.0.1:${server.address().port}`;
+        await initSite({
+          testURL: `${origin}/module-host.html`,
+          config: {
+            executeScript: true,
+            routerMode,
+            basePath: `${origin}/content/`,
+            alias: { '/guide/page': `${origin}/redirect.md` },
+          },
+          markdown: { homepage: home },
+        });
+        await page.getByRole('link', { name: 'Guide', exact: true }).click();
+        await expect(page.locator('#result')).toHaveText('Redirected');
+        await page.goBack();
+        await page.getByRole('link', { name: 'Guide', exact: true }).click();
+        await expect(page.locator('#result')).toHaveText('Redirected');
+      } finally {
+        server.closeAllConnections();
+        await new Promise(resolve => server.close(resolve));
+      }
+    });
+
+    test('keeps navigation working after a module parse error', async ({
+      page,
+    }) => {
+      const error = page.waitForEvent('pageerror');
+      await initSite({
+        testURL,
+        config: { executeScript: true, routerMode },
+        markdown: {
+          homepage: `${home}\n\n<script type="module">import {</script>`,
+        },
+        routes: { 'guide/page.md': '# Next page' },
+      });
+      expect((await error).message).toBeTruthy();
+      await page.getByRole('link', { name: 'Guide', exact: true }).click();
+      await expect(page.locator('h1')).toHaveText('Next page');
+    });
+  });
+}
+
+test('resolves hash routes hosted at an explicit HTML file', async ({
+  page,
+}) => {
+  await page.addInitScript(() => {
+    history.replaceState(null, '', location.pathname + '#/');
+  });
+  await docsifyInit({
+    testURL: `${process.env.TEST_HOST}/app/index.html`,
+    config: { executeScript: true, basePath: '' },
+    routes: {
+      '/app/README.md': home,
+      '/app/guide/page.md': guide,
+      '/app/guide/dep.js': 'export const value = "Index file";',
+    },
+  });
+  await page.getByRole('link', { name: 'Guide', exact: true }).click();
+  await expect(page.locator('#result')).toHaveText('Index file');
+});
diff --git a/test/manual/execute-script/README.md b/test/manual/execute-script/README.md
new file mode 100644
index 000000000..cc0432b87
--- /dev/null
+++ b/test/manual/execute-script/README.md
@@ -0,0 +1,21 @@
+# Manual module import test
+
+Run these commands from the repository root:
+
+```sh
+npm run build
+node test/manual/execute-script/server.js
+```
+
+Open either mode:
+
+- Hash: <http://127.0.0.1:4173/module-demo/hash/>
+- History: <http://127.0.0.1:4173/module-demo/history/>
+
+Follow the guide link. Expect `Static and dynamic imports succeeded; executions: 1`.
+Return home and open the guide again: expect the execution count to increase.
+Refresh the guide: expect success with the count reset to 1 in both modes.
+The server includes history fallback so deep links also work.
+
+The guide imports `./demo-module.js` and `../shared.js` from its Markdown
+directory, which differs from the HTML entry URL in both modes.
diff --git a/test/manual/execute-script/content/README.md b/test/manual/execute-script/content/README.md
new file mode 100644
index 000000000..bdacc5bc9
--- /dev/null
+++ b/test/manual/execute-script/content/README.md
@@ -0,0 +1,5 @@
+# Markdown-relative imports
+
+[Open the guide](guide/page.md)
+
+The guide uses static and dynamic imports relative to its Markdown file.
diff --git a/test/manual/execute-script/content/guide/demo-module.js b/test/manual/execute-script/content/guide/demo-module.js
new file mode 100644
index 000000000..2e9970526
--- /dev/null
+++ b/test/manual/execute-script/content/guide/demo-module.js
@@ -0,0 +1,6 @@
+let executions = 0;
+
+export function renderResult(element, message) {
+  executions += 1;
+  element.textContent = `${message}; executions: ${executions}`;
+}
diff --git a/test/manual/execute-script/content/guide/page.md b/test/manual/execute-script/content/guide/page.md
new file mode 100644
index 000000000..dd10992f7
--- /dev/null
+++ b/test/manual/execute-script/content/guide/page.md
@@ -0,0 +1,12 @@
+# Module guide
+
+<p id="module-result">Loading module…</p>
+
+<script type="module">
+  import { renderResult } from './demo-module.js';
+  const { message } = await import('../shared.js');
+
+  renderResult(document.querySelector('#module-result'), message);
+</script>
+
+[Return home](../README.md)
diff --git a/test/manual/execute-script/content/shared.js b/test/manual/execute-script/content/shared.js
new file mode 100644
index 000000000..c3304af3b
--- /dev/null
+++ b/test/manual/execute-script/content/shared.js
@@ -0,0 +1 @@
+export const message = 'Static and dynamic imports succeeded';
diff --git a/test/manual/execute-script/index.html b/test/manual/execute-script/index.html
new file mode 100644
index 000000000..c72c9455f
--- /dev/null
+++ b/test/manual/execute-script/index.html
@@ -0,0 +1,29 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Markdown-relative module imports</title>
+    <link rel="stylesheet" href="/dist/themes/core.css" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script>
+      const routerMode = location.pathname.includes('/history')
+        ? 'history'
+        : 'hash';
+      window.$docsify = {
+        name: `Module imports (${routerMode})`,
+        executeScript: true,
+        routerMode,
+        relativePath: true,
+        basePath: '/test/manual/execute-script/content/',
+        alias: {
+          '/module-demo/history/?': '/',
+          '/module-demo/history/(.*)': '/$1',
+        },
+      };
+    </script>
+    <script src="/dist/docsify.js"></script>
+  </body>
+</html>
diff --git a/test/manual/execute-script/server.js b/test/manual/execute-script/server.js
new file mode 100644
index 000000000..cdd1efeb1
--- /dev/null
+++ b/test/manual/execute-script/server.js
@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { create } from 'browser-sync';
+
+const html = await readFile(new URL('./index.html', import.meta.url), 'utf8');
+
+create().init({
+  listen: '127.0.0.1',
+  port: 4173,
+  open: false,
+  ui: false,
+  notify: false,
+  snippet: false,
+  server: {
+    baseDir: fileURLToPath(new URL('../../../', import.meta.url)),
+    middleware: [
+      {
+        route: '/module-demo',
+        handle(request, response) {
+          response.setHeader('Content-Type', 'text/html; charset=utf-8');
+          response.end(html);
+        },
+      },
+    ],
+  },
+});
diff --git a/test/unit/module-script.test.js b/test/unit/module-script.test.js
new file mode 100644
index 000000000..075089d50
--- /dev/null
+++ b/test/unit/module-script.test.js
@@ -0,0 +1,77 @@
+import { resolveModuleSpecifiers } from '../../src/core/render/module-script.js';
+
+const base = 'https://example.test/content/guide/page.md';
+
+describe('resolveModuleSpecifiers', () => {
+  test.each([
+    [
+      "import value from './dep.js';",
+      'import value from "https://example.test/content/guide/dep.js";',
+    ],
+    [
+      "import /* comment */ './dep.js';",
+      'import /* comment */ "https://example.test/content/guide/dep.js";',
+    ],
+    [
+      "export { value } from '../shared.js';",
+      'export { value } from "https://example.test/content/shared.js";',
+    ],
+    [
+      "export * from './dep.js';",
+      'export * from "https://example.test/content/guide/dep.js";',
+    ],
+    [
+      "import(/* comment */ './dep.js');",
+      'import(/* comment */ "https://example.test/content/guide/dep.js");',
+    ],
+    [
+      "import('./data.json', { with: { type: 'json' } });",
+      'import("https://example.test/content/guide/data.json", { with: { type: \'json\' } });',
+    ],
+    [
+      String.raw`import './\u0061.js?version=1#test';`,
+      'import "https://example.test/content/guide/a.js?version=1#test";',
+    ],
+    [
+      String.raw`import './it\'s.js';`,
+      'import "https://example.test/content/guide/it\'s.js";',
+    ],
+    [
+      'import "./quote\\".js";',
+      'import "https://example.test/content/guide/quote%22.js";',
+    ],
+  ])('rewrites %s', (code, expected) => {
+    expect(resolveModuleSpecifiers(code, base)).toBe(expected);
+  });
+
+  test('rewrites multiple imports without changing intervening source', () => {
+    const code =
+      "import './a.js';\n/* import './ignored.js' */\nexport * from '../b.js';";
+    expect(resolveModuleSpecifiers(code, base)).toBe(
+      'import "https://example.test/content/guide/a.js";\n/* import \'./ignored.js\' */\nexport * from "https://example.test/content/b.js";',
+    );
+  });
+
+  test.each([
+    '',
+    'const text = "import \'./example.js\'";',
+    "const text = `export * from './example.js'`;",
+    "// import './example.js'\n/* export * from '../other.js' */",
+    String.raw`const pattern = /import '.\/example.js'/;`,
+    'const object = { import(value) { return value; } }; object.import("./a.js");',
+    "import '/root.js'; import 'https://cdn.example/dep.js'; import '//cdn.example/dep.js';",
+    "import 'vue'; import 'data:text/javascript,export default 1';",
+    "import.meta.url; import(path); import('./' + name);",
+    // eslint-disable-next-line no-template-curly-in-string -- Source code under test.
+    'import(`./${name}.js`); import(`./dep.js`);',
+  ])(
+    'leaves non-relative imports and non-import syntax unchanged: %s',
+    code => {
+      expect(resolveModuleSpecifiers(code, base)).toBe(code);
+    },
+  );
+
+  test('rejects an unterminated import', () => {
+    expect(() => resolveModuleSpecifiers('import {', base)).toThrow();
+  });
+});
diff --git a/tsconfig.json b/tsconfig.json
index ef671d362..78931bfc5 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -5,6 +5,11 @@
 
     "module": "esnext",
     "moduleResolution": "node",
+    // The synchronous JS build shares the main entry's types, but legacy
+    // node resolution does not read package.json subpath exports.
+    "paths": {
+      "es-module-lexer/js": ["./node_modules/es-module-lexer/types/lexer.d.ts"]
+    },
     "target": "es2023",
     "lib": ["ES2023", "DOM", "DOM.AsyncIterable", "DOM.Iterable"],
     "declaration": true,