Merge branch 'main' into new-router

CONTRIBUTING.md

@@ -38,34 +38,91 @@ Build source code:
 pnpm build
 ```
 
-Main tools that used in this project:
+### Tools
 
 - [TypeScript](https://www.typescriptlang.org/) as the development language
-- [Vitest](https://vitest.dev/) for unit testing
 - [ESLint](https://eslint.org/) + [Prettier](https://prettier.io/) for code linting and formatting
+- [Vitest](https://vitest.dev/) for unit testing
+- [Cypress](https://www.cypress.io/) for end-to-end testing
 
-## Scripts
+### Scripts
 
-### `pnpm build`
+#### `pnpm build`
 
 The `build` script uses `tsup` to compile TypeScript source files to JavaScript dist files.
 
 You may need to run this script first after your clone this repository, because the dist files are ignored by `.gitignore`.
 
-### `pnpm clean`
+#### `pnpm clean`
 
 The `clean` script runs `clean` script in all packages, cleaning all the dist files and caches. In other words, it will remove all the files that generated by `build` scripts.
 
 It's used before you want to re-build source files from a clean / initial state.
 
-### `pnpm lint`
+#### `pnpm format`
+
+The `format` script uses Prettier to format all source files.
+
+#### `pnpm lint`
 
 The `lint` script uses ESLint to check all source files.
 
-### `pnpm test`
+#### `pnpm test`
 
 The `test` script uses Vitest to run unit testings.
 
-## Documentation
+## End-to-end Testing
+
+All end-to-end (e2e) tests are located in `e2e` directory.
+
+You can also make use of the e2e site to test features during development. The source code of the e2e site is located in `e2e/docs`.
+
+To run e2e tests, you need to change the working directory to `e2e` first:
+
+```bash
+cd e2e
+```
+
+### Using E2E Site
+
+The e2e site is a normal VuePress setup, you can run `dev` and `build` commands in it:
+
+```bash
+# start dev server
+pnpm e2e:dev
+# build and start preview server
+pnpm e2e:build
+pnpm e2e:serve
+```
+
+### Run E2E Tests
+
+After starting a dev server or a preview server, you can run e2e tests in another terminal:
+
+```bash
+# open Cypress GUI
+pnpm e2e:open
+# or, run tests in command line
+pnpm e2e:run
+```
+
+If you don't want to start a server and run tests in two different terminals, you can make use of the CI commands to do both in one command:
+
+```bash
+# run e2e tests in dev mode
+pnpm e2e:ci:dev
+# run e2e tests in build mode
+pnpm e2e:ci:build
+```
+
+## Repositories
+
+Current repository only maintains the core packages of VuePress. The following repositories are also part of the VuePress project.
+
+### Documentation
+
+VuePress official documentation is maintained in [vuepress/docs](https://github.com/vuepress/docs) repository.
+
+### Plugins and Themes
 
-VuePress documentation is maintained in [vuepress/docs](https://github.com/vuepress/docs) repository.
+VuePress official plugins and themes are maintained in [vuepress/ecosystem](https://github.com/vuepress/ecosystem) repository.

CONTRIBUTING_zh.md

@@ -38,34 +38,91 @@ pnpm install
 pnpm build
 ```
 
-本项目开发使用的一些主要工具：
+### 主要工具
 
 - [TypeScript](https://www.typescriptlang.org/) 作为开发语言
-- [Vitest](https://vitest.dev/) 用于单元测试
 - [ESLint](https://eslint.org/) + [Prettier](https://prettier.io/) 用于代码检查和格式化
+- [Vitest](https://vitest.dev/) 用于单元测试
+- [Cypress](https://www.cypress.io/) 用于端到端测试
 
-## 开发脚本
+### 开发脚本
 
-### `pnpm build`
+#### `pnpm build`
 
 `build` 命令会使用 `tsup` 将 TypeScript 源文件编译为 JavaScript 文件。
 
 你在克隆代码仓库后，可能需要先执行该命令来确保项目代码可以顺利运行，因为编译后的输出目录被 `.gitignore` 排除在仓库以外了。
 
-### `pnpm clean`
+#### `pnpm clean`
 
 `clean` 命令会执行所有子 Package 中的 `clean` 命令，清除所有的输出文件目录和缓存文件。换言之，它将移除所有通过 `build` 命令生成的文件。
 
 当你想要从最初状态重新构建源代码时，你可以执行该命令。
 
-### `pnpm lint`
+#### `pnpm format`
+
+`format` 命令使用 Prettier 来格式化所有源文件。
+
+#### `pnpm lint`
 
 `lint` 命令使用 ESLint 来检查所有源文件。
 
-### `pnpm test`
+#### `pnpm test`
 
 `test` 命令使用 Vitest 来运行单元测试。
 
-## 文档
+## 端到端测试
+
+所有和端到端 (e2e) 测试相关的代码都在 `e2e` 目录下。
+
+你也可以通过 e2e 站点在开发过程中进行功能测试。 e2e 站点的源代码位于 `e2e/docs` 目录下。
+
+要运行 e2e 测试，你需要先切换到 `e2e` 目录：
+
+```bash
+cd e2e
+```
+
+### 使用 E2E 站点
+
+e2e 站点就是一个正常的 VuePress 项目，你可以在其中运行 `dev` 和 `build` 命令：
+
+```bash
+# 启动开发服务器
+pnpm e2e:dev
+# 构建静态站点并启动预览服务器
+pnpm e2e:build
+pnpm e2e:serve
+```
+
+### 运行 E2E 测试
+
+在启动开发服务器或预览服务器后，你可以在另一个终端中运行 e2e 测试：
+
+```bash
+# 启动 Cypress 图形界面
+pnpm e2e:open
+# 或者，直接在命令行中运行测试
+pnpm e2e:run
+```
+
+如果你不想在两个不同终端内启动服务器和运行测试，你可以使用 CI 命令，用单条命令来完成这两个操作：
+
+```bash
+# 在开发模式下运行 e2e 测试
+pnpm e2e:ci:dev
+# 在构建模式下运行 e2e 测试
+pnpm e2e:ci:build
+```
+
+## 项目仓库
+
+当前仓库包含了 VuePress 的核心模块。下述仓库也同样是 VuePress 项目的一部分。
+
+### 文档
+
+VuePress 的官方文档在 [vuepress/docs](https://github.com/vuepress/docs) 仓库中进行维护。
+
+### 插件和主题
 
-VuePress 的文档在 [vuepress/docs](https://github.com/vuepress/docs) 仓库中进行维护。
+VuePress 的官方插件和主题在 [vuepress/ecosystem](https://github.com/vuepress/ecosystem) 仓库中进行维护。

e2e/package.json

@@ -11,6 +11,7 @@
     "e2e:clean": "rimraf docs/.vuepress/.temp docs/.vuepress/.cache docs/.vuepress/dist",
     "e2e:dev": "vuepress dev docs --clean-cache --clean-temp",
     "e2e:dev-webpack": "E2E_BUNDLER=webpack pnpm e2e:dev",
+    "e2e:open": "cypress open",
     "e2e:run": "cypress run",
     "e2e:serve": "anywhere -s -h localhost -p 9080 -d docs/.vuepress/dist"
   },

e2e/tests/markdown/anchors.cy.ts

@@ -10,15 +10,11 @@ it('should render anchors and navigate correctly', () => {
     .should('have.attr', 'href', '#title')
     .click()
 
-  cy.location().should((location) => {
-    expect(location.hash).to.eq('#title')
-  })
+  cy.hash().should('eq', '#title')
 
   cy.get('#anchor-1-1 > a')
     .should('have.attr', 'class', 'header-anchor')
     .click()
 
-  cy.location().should((location) => {
-    expect(location.hash).to.eq('#anchor-1-1')
-  })
+  cy.hash().should('eq', '#anchor-1-1')
 })

e2e/tests/markdown/links.cy.ts

@@ -9,27 +9,21 @@ it('should render links and navigate between pages correctly', () => {
     .should('have.text', 'bar')
     .click()
 
-  cy.location().should((location) => {
-    expect(location.pathname).to.eq(`${E2E_BASE}markdown/links/bar.html`)
-  })
+  cy.location('pathname').should('eq', `${E2E_BASE}markdown/links/bar.html`)
 
   cy.get('.e2e-theme-content ul li a')
     .should('have.length', 2)
     .last()
     .should('have.text', 'baz')
     .click()
 
-  cy.location().should((location) => {
-    expect(location.pathname).to.eq(`${E2E_BASE}markdown/links/baz.html`)
-  })
+  cy.location('pathname').should('eq', `${E2E_BASE}markdown/links/baz.html`)
 
   cy.get('.e2e-theme-content ul li a')
     .should('have.length', 2)
     .first()
     .should('have.text', 'foo')
     .click()
 
-  cy.location().should((location) => {
-    expect(location.pathname).to.eq(`${E2E_BASE}markdown/links/foo.html`)
-  })
+  cy.location('pathname').should('eq', `${E2E_BASE}markdown/links/foo.html`)
 })

e2e/tests/routes/non-ascii-paths.cy.ts

@@ -15,11 +15,10 @@ it('should support rendering non-ASCII paths links and navigate to it correctly'
     .should('have.text', '中文路径')
     .click()
 
-  cy.location().should((location) => {
-    expect(location.pathname).to.eq(
-      encodeURI(`${E2E_BASE}routes/non-ascii-paths/中文目录名/中文文件名.html`),
-    )
-  })
+  cy.location('pathname').should(
+    'eq',
+    encodeURI(`${E2E_BASE}routes/non-ascii-paths/中文目录名/中文文件名.html`),
+  )
 
   cy.get('.e2e-theme-content p').should('have.text', '这是一个中文文件')
 })

packages/client/src/setupGlobalComputed.ts

@@ -63,11 +63,8 @@ export const setupGlobalComputed = (
   router: Router,
   clientConfigs: ClientConfig[],
 ): GlobalComputed => {
-  // route path and locale
+  // route path of current page
   const routePath = computed(() => router.currentRoute.value.path)
-  const routeLocale = computed(() =>
-    resolvers.resolveRouteLocale(siteData.value.locales, routePath.value),
-  )
 
   // load page data from route meta
   const pageData = computedWithControl(
@@ -87,6 +84,9 @@ export const setupGlobalComputed = (
 
   // create other global computed
   const layouts = computed(() => resolvers.resolveLayouts(clientConfigs))
+  const routeLocale = computed(() =>
+    resolvers.resolveRouteLocale(siteData.value.locales, routePath.value),
+  )
   const siteLocaleData = computed(() =>
     resolvers.resolveSiteLocaleData(siteData.value, routeLocale.value),
   )

packages/markdown/src/plugins/codePlugin/codePlugin.ts

@@ -1,4 +1,5 @@
 import type { PluginWithOptions } from 'markdown-it'
+import { resolveAttr } from './resolveAttr.js'
 import {
   isHighlightLine,
   resolveHighlightLines,
@@ -27,7 +28,7 @@ export interface CodePluginOptions {
    *
    * - Required for `highlightLines`
    * - Required for `lineNumbers`
-   * - Required for language display of default theme
+   * - Required for title display of default theme
    */
   preWrapper?: boolean
 
@@ -130,9 +131,12 @@ export const codePlugin: PluginWithOptions<CodePluginOptions> = (
       result = `${result}<div class="line-numbers" aria-hidden="true">${lineNumbersCode}</div>`
     }
 
+    // resolve title from token info
+    const title = resolveAttr(info, 'title') ?? language.ext
+
     result = `<div class="${languageClass}${
       useLineNumbers ? ' line-numbers-mode' : ''
-    }" data-ext="${language.ext}">${result}</div>`
+    }" data-ext="${language.ext}" data-title="${title}">${result}</div>`
 
     return result
   }

packages/markdown/src/plugins/codePlugin/resolveAttr.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve the specified attribute from token info
+ */
+export const resolveAttr = (info: string, attr: string): string | null => {
+  // try to match specified attr mark
+  const pattern = `\\b${attr}\\s*=\\s*(?<quote>['"])(?<content>.+)\\k<quote>(\\s|$)`
+  const regex = new RegExp(pattern, 'i')
+  const match = info.match(regex)
+
+  // return content if matched, null if not specified
+  return match?.groups?.content ?? null
+}