feat: add route option (close #1505)

.eslintrc.cjs

@@ -1,6 +1,12 @@
 module.exports = {
   root: true,
   extends: 'vuepress',
+
+  // FIXME: This should be added to `eslint-config-vuepress`
+  globals: {
+    __VUEPRESS_CLEAN_URL__: 'readonly',
+  },
+
   overrides: [
     {
       files: ['*.ts', '*.vue', '*.cts'],

e2e/docs/.vuepress/theme/client/layouts/NotFound.vue

@@ -1,3 +1,4 @@
 <template>
   <div class="e2e-theme-not-found">404 Not Found</div>
+  <div class="e2e-theme-not-found-content"><Content /></div>
 </template>

e2e/docs/404.md

@@ -2,3 +2,5 @@
 routeMeta:
   foo: bar
 ---
+
+## NotFound H2

e2e/docs/README.md

@@ -1 +1,3 @@
 foo
+
+## Home H2

e2e/docs/router/navigate-by-link.md

@@ -0,0 +1,34 @@
+## Markdown Links with html
+
+- [Home with query](/?home=true)
+- [Home with query and hash](/?home=true#home)
+- [404 with hash](/404.html#404)
+- [404 with hash and query](/404.html#404?notFound=true)
+
+## Markdown Links with md
+
+- [Home with query](/README.md?home=true)
+- [Home with query and hash](/README.md?home=true#home)
+- [404 with hash](/404.md#404)
+- [404 with hash and query](/404.md#404?notFound=true)
+
+## Markdown Clean Links
+
+- [Home with query](/?home=true)
+- [Home with query and hash](/?home=true#home)
+- [404 with hash](/404#404)
+- [404 with hash and query](/404#404?notFound=true)
+
+## HTML Full Links
+
+<a :href="$withBase('/?home=true')" class="home-with-query">Home</a>
+<a :href="$withBase('/?home=true#home')" class="home-with-query-and-hash">Home</a>
+<a :href="$withBase('/404.html#404')" class="not-found-with-hash">404</a>
+<a :href="$withBase('/404.html#404?notFound=true')" class="not-found-with-hash-and-query">404</a>
+
+## HTML Clean Links
+
+<a :href="$withBase('/?home=true')" class="home-with-query">Home</a>
+<a :href="$withBase('/?home=true#home')" class="home-with-query-and-hash">Home</a>
+<a :href="$withBase('/404#404')" class="not-found-with-hash">404</a>
+<a :href="$withBase('/404#404?notFound=true')" class="not-found-with-hash-and-query">404</a>

e2e/docs/router/navigate-by-router.md

@@ -0,0 +1,51 @@
+<div id="full">
+  <button class="home-with-query" @click="goHomeWithQuery">Home</button>
+  <button class="home-with-query-and-hash" @click="goHomeWithQueryAndHash">Home</button>
+  <button class="not-found-with-hash" @click="go404WithHash">404</button>
+  <button class="not-found-with-hash-and-query" @click="go404WithHashAndQuery">404</button>
+</div>
+
+<div id="clean">
+  <button class="home-with-query" @click="goHomeWithQuery">Home</button>
+  <button class="home-with-query-and-hash" @click="goHomeWithQueryAndHash">Home</button>
+  <button class="not-found-with-hash" @click="go404WithHash">404</button>
+  <button class="not-found-with-hash-and-query" @click="go404WithHashAndQuery">404</button>
+</div>
+
+<script setup lang="ts">
+import { useRouter } from 'vuepress/client';
+
+const router = useRouter();
+
+const goHomeWithQuery = (event) => {
+  if (event.currentTarget.parentElement.id === 'full') {
+    router.push('/index.html?home=true');
+  } else {
+    router.push('/?home=true');
+  }
+}
+
+const goHomeWithQueryAndHash = (event) => {
+  if (event.currentTarget.parentElement.id === 'full') {
+    router.push('/index.html?home=true#home');
+  } else {
+    router.push('/?home=true#home');
+  }
+}
+
+const go404WithHash = (event) => {
+  if (event.currentTarget.parentElement.id === 'full') {
+    router.push('/404.html#404');
+  } else {
+    router.push('/404#404');
+  }
+}
+
+const go404WithHashAndQuery = (event) => {
+  if (event.currentTarget.parentElement.id === 'full') {
+    router.push('/404.html#404?notFound=true');
+  } else {
+    router.push('/404#404?notFound=true');
+  }
+}
+</script>

e2e/docs/router/resolve-route-query-hash.md

@@ -0,0 +1,12 @@
+# Resolve Route FullPath
+
+## Includes Query And Hash
+
+- Search Query: {{ JSON.stringify(resolveRoute('/?query=1')) }}
+- Hash: {{ JSON.stringify(resolveRoute('/#hash')) }}
+- Search Query And Hash: {{ JSON.stringify(resolveRoute('/?query=1#hash')) }}
+- Permalink And Search Query: {{ JSON.stringify(resolveRoute('/routes/permalinks/ascii-non-ascii.md?query=1')) }}
+
+<script setup>
+import { resolveRoute } from 'vuepress/client'
+</script>

e2e/tests/router/navigate-by-link.spec.ts

@@ -0,0 +1,134 @@
+import { expect, test } from '@playwright/test'
+import { BASE } from '../../utils/env'
+
+test.beforeEach(async ({ page }) => {
+  await page.goto('router/navigate-by-link.html')
+})
+
+test.describe('should preserve query', () => {
+  test('markdown links with html suffix', async ({ page }) => {
+    await page.locator('#markdown-links-with-html + ul > li > a').nth(0).click()
+    await expect(page).toHaveURL(`${BASE}?home=true`)
+    await expect(page.locator('#home-h2')).toHaveText('Home H2')
+  })
+
+  test('markdown links with md suffix', async ({ page }) => {
+    await page.locator('#markdown-links-with-md + ul > li > a').nth(0).click()
+    await expect(page).toHaveURL(`${BASE}?home=true`)
+    await expect(page.locator('#home-h2')).toHaveText('Home H2')
+  })
+
+  test('markdown clean links', async ({ page }) => {
+    await page.locator('#markdown-clean-links + ul > li > a').nth(0).click()
+    await expect(page).toHaveURL(`${BASE}?home=true`)
+    await expect(page.locator('#home-h2')).toHaveText('Home H2')
+  })
+
+  test('html full links', async ({ page }) => {
+    await page.locator('#html-full-links + p > a').nth(0).click()
+    await expect(page).toHaveURL(`${BASE}?home=true`)
+    await expect(page.locator('#home-h2')).toHaveText('Home H2')
+  })
+
+  test('html clean links', async ({ page }) => {
+    await page.locator('#html-clean-links + p > a').nth(0).click()
+    await expect(page).toHaveURL(`${BASE}?home=true`)
+    await expect(page.locator('#home-h2')).toHaveText('Home H2')
+  })
+})
+
+test.describe('should preserve query and hash', () => {
+  test('markdown links with html suffix', async ({ page }) => {
+    await page.locator('#markdown-links-with-html + ul > li > a').nth(1).click()
+    await expect(page).toHaveURL(`${BASE}?home=true#home`)
+    await expect(page.locator('#home-h2')).toHaveText('Home H2')
+  })
+
+  test('markdown links with md suffix', async ({ page }) => {
+    await page.locator('#markdown-links-with-md + ul > li > a').nth(1).click()
+    await expect(page).toHaveURL(`${BASE}?home=true#home`)
+    await expect(page.locator('#home-h2')).toHaveText('Home H2')
+  })
+
+  test('markdown clean links', async ({ page }) => {
+    await page.locator('#markdown-clean-links + ul > li > a').nth(1).click()
+    await expect(page).toHaveURL(`${BASE}?home=true#home`)
+    await expect(page.locator('#home-h2')).toHaveText('Home H2')
+  })
+
+  test('html full links', async ({ page }) => {
+    await page.locator('#html-full-links + p > a').nth(1).click()
+    await expect(page).toHaveURL(`${BASE}?home=true#home`)
+    await expect(page.locator('#home-h2')).toHaveText('Home H2')
+  })
+
+  test('html clean links', async ({ page }) => {
+    await page.locator('#html-clean-links + p > a').nth(1).click()
+    await expect(page).toHaveURL(`${BASE}?home=true#home`)
+    await expect(page.locator('#home-h2')).toHaveText('Home H2')
+  })
+})
+
+test.describe('should preserve hash', () => {
+  test('markdown links with html suffix', async ({ page }) => {
+    await page.locator('#markdown-links-with-html + ul > li > a').nth(2).click()
+    await expect(page).toHaveURL(`${BASE}404.html#404`)
+    await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
+  })
+
+  test('markdown links with md suffix', async ({ page }) => {
+    await page.locator('#markdown-links-with-md + ul > li > a').nth(2).click()
+    await expect(page).toHaveURL(`${BASE}404.html#404`)
+    await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
+  })
+
+  test('markdown clean links', async ({ page }) => {
+    await page.locator('#markdown-clean-links + ul > li > a').nth(2).click()
+    await expect(page).toHaveURL(`${BASE}404.html#404`)
+    await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
+  })
+
+  test('html full links', async ({ page }) => {
+    await page.locator('#html-full-links + p > a').nth(2).click()
+    await expect(page).toHaveURL(`${BASE}404.html#404`)
+    await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
+  })
+
+  test('html clean links', async ({ page }) => {
+    await page.locator('#html-clean-links + p > a').nth(2).click()
+    await expect(page).toHaveURL(`${BASE}404.html#404`)
+    await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
+  })
+})
+
+test.describe('should preserve hash and query', () => {
+  test('markdown links with html suffix', async ({ page }) => {
+    await page.locator('#markdown-links-with-html + ul > li > a').nth(3).click()
+    await expect(page).toHaveURL(`${BASE}404.html#404?notFound=true`)
+    await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
+  })
+
+  test('markdown links with md suffix', async ({ page }) => {
+    await page.locator('#markdown-links-with-md + ul > li > a').nth(3).click()
+    await expect(page).toHaveURL(`${BASE}404.html#404?notFound=true`)
+    await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
+  })
+
+  test('markdown clean links', async ({ page }) => {
+    await page.locator('#markdown-clean-links + ul > li > a').nth(3).click()
+    await expect(page).toHaveURL(`${BASE}404.html#404?notFound=true`)
+    await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
+  })
+
+  test('html full links', async ({ page }) => {
+    await page.locator('#html-full-links + p > a').nth(3).click()
+    await expect(page).toHaveURL(`${BASE}404.html#404?notFound=true`)
+    await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
+  })
+
+  test('html clean links', async ({ page }) => {
+    await page.locator('#html-clean-links + p > a').nth(3).click()
+    await expect(page).toHaveURL(`${BASE}404.html#404?notFound=true`)
+    await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
+  })
+})

e2e/tests/router/navigate-by-router.spec.ts

@@ -0,0 +1,62 @@
+import { expect, test } from '@playwright/test'
+import { BASE } from '../../utils/env'
+
+test.beforeEach(async ({ page }) => {
+  await page.goto('router/navigate-by-router.html')
+})
+
+test.describe('should preserve query', () => {
+  test('full', async ({ page }) => {
+    await page.locator('#full .home-with-query').click()
+    await expect(page).toHaveURL(`${BASE}?home=true`)
+    await expect(page.locator('#home-h2')).toHaveText('Home H2')
+  })
+
+  test('clean', async ({ page }) => {
+    await page.locator('#clean .home-with-query').click()
+    await expect(page).toHaveURL(`${BASE}?home=true`)
+    await expect(page.locator('#home-h2')).toHaveText('Home H2')
+  })
+})
+
+test.describe('should preserve query and hash', () => {
+  test('full', async ({ page }) => {
+    await page.locator('#full .home-with-query-and-hash').click()
+    await expect(page).toHaveURL(`${BASE}?home=true#home`)
+    await expect(page.locator('#home-h2')).toHaveText('Home H2')
+  })
+
+  test('clean', async ({ page }) => {
+    await page.locator('#clean .home-with-query-and-hash').click()
+    await expect(page).toHaveURL(`${BASE}?home=true#home`)
+    await expect(page.locator('#home-h2')).toHaveText('Home H2')
+  })
+})
+
+test.describe('should preserve  hash', () => {
+  test('full', async ({ page }) => {
+    await page.locator('#full .not-found-with-hash').click()
+    await expect(page).toHaveURL(`${BASE}404.html#404`)
+    await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
+  })
+
+  test('clean', async ({ page }) => {
+    await page.locator('#clean .not-found-with-hash').click()
+    await expect(page).toHaveURL(`${BASE}404.html#404`)
+    await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
+  })
+})
+
+test.describe('should preserve hash and query', () => {
+  test('full', async ({ page }) => {
+    await page.locator('#full .not-found-with-hash-and-query').click()
+    await expect(page).toHaveURL(`${BASE}404.html#404?notFound=true`)
+    await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
+  })
+
+  test('clean', async ({ page }) => {
+    await page.locator('#clean .not-found-with-hash-and-query').click()
+    await expect(page).toHaveURL(`${BASE}404.html#404?notFound=true`)
+    await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
+  })
+})

e2e/tests/router/resolve-route-query-hash.spec.ts

@@ -0,0 +1,35 @@
+import { expect, test } from '@playwright/test'
+
+const testCases = [
+  {
+    path: '/?query=1',
+    notFound: false,
+  },
+  {
+    path: '/#hash',
+    notFound: false,
+  },
+  {
+    path: '/?query=1#hash',
+    notFound: false,
+  },
+  {
+    path: encodeURI('/永久链接-ascii-中文/?query=1'),
+    notFound: false,
+  },
+]
+
+test('should resolve routes when including both the query and hash', async ({
+  page,
+}) => {
+  const listItemsLocator = await page
+    .locator('.e2e-theme-content #includes-query-and-hash + ul > li')
+    .all()
+
+  for (const [index, li] of listItemsLocator.entries()) {
+    const textContent = await li.textContent()
+    const resolvedRoute = JSON.parse(/: (\{.*\})\s*$/.exec(textContent!)![1])
+    expect(resolvedRoute.path).toEqual(testCases[index].path)
+    expect(resolvedRoute.notFound).toEqual(testCases[index].notFound)
+  }
+})