feat: support route option

.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'],

packages/bundler-vite/src/plugins/vuepressMainPlugin.ts

@@ -205,6 +205,7 @@ const resolveDefine = async ({
   const define: UserConfig['define'] = {
     __VUEPRESS_VERSION__: JSON.stringify(app.version),
     __VUEPRESS_BASE__: JSON.stringify(app.options.base),
+    __VUEPRESS_CLEAN_URL__: JSON.stringify(app.options.route.cleanUrl),
     __VUEPRESS_DEV__: JSON.stringify(!isBuild),
     __VUEPRESS_SSR__: JSON.stringify(isServer),
     // @see http://link.vuejs.org/feature-flags

packages/bundler-webpack/src/config/handlePluginDefine.ts

@@ -21,6 +21,7 @@ export const handlePluginDefine = async ({
     {
       __VUEPRESS_VERSION__: JSON.stringify(app.version),
       __VUEPRESS_BASE__: JSON.stringify(app.options.base),
+      __VUEPRESS_CLEAN_URL__: JSON.stringify(app.options.route.cleanUrl),
       __VUEPRESS_DEV__: JSON.stringify(!isBuild),
       __VUEPRESS_SSR__: JSON.stringify(isServer),
       // @see http://link.vuejs.org/feature-flags

packages/cli/src/commands/dev/watchPageFiles.ts

@@ -41,7 +41,7 @@ export const watchPageFiles = (app: App): FSWatcher[] => {
   app.pages.forEach((page) => addDeps(page))
 
   // watch page files
-  const pagesWatcher = chokidar.watch(app.options.pagePatterns, {
+  const pagesWatcher = chokidar.watch(app.options.route.pagePatterns, {
     cwd: app.dir.source(),
     ignoreInitial: true,
   })

packages/client/src/router/resolveRoutePath.ts

@@ -1,6 +1,8 @@
 import { normalizeRoutePath } from '@vuepress/shared'
 import { redirects, routes } from '../internal/routes.js'
 
+declare const __VUEPRESS_CLEAN_URL__: boolean
+
 /**
  * Resolve route path with given raw path
  */
@@ -9,7 +11,11 @@ export const resolveRoutePath = (
   currentPath?: string,
 ): string => {
   // normalized path
-  const normalizedPath = normalizeRoutePath(path, currentPath)
+  const normalizedPath = normalizeRoutePath(
+    path,
+    currentPath,
+    __VUEPRESS_CLEAN_URL__,
+  )
   if (routes.value[normalizedPath]) return normalizedPath
 
   // encoded path

packages/client/types.d.ts

@@ -1,6 +1,7 @@
 declare const __VUEPRESS_VERSION__: string
 declare const __VUEPRESS_BASE__: string
 declare const __VUEPRESS_DEV__: boolean
+declare const __VUEPRESS_CLEAN_URL__: boolean
 declare const __VUEPRESS_SSR__: boolean
 declare const __VUE_HMR_RUNTIME__: Record<string, any>
 declare const __VUE_OPTIONS_API__: boolean

packages/core/src/app/prepare/prepareRoutes.ts

@@ -23,13 +23,21 @@ if (import.meta.hot) {
 /**
  * Resolve page redirects
  */
-const resolvePageRedirects = ({ path, pathInferred }: Page): string[] => {
+const resolvePageRedirects = (
+  app: App,
+  { path, pathInferred }: Page,
+): string[] => {
   // paths that should redirect to this page, use set to dedupe
   const redirectsSet = new Set<string>()
 
   // add redirect to the set when the redirect could not be normalized & encoded to the page path
   const addRedirect = (redirect: string): void => {
-    const normalizedPath = normalizeRoutePath(redirect)
+    const normalizedPath = normalizeRoutePath(
+      redirect,
+      '',
+      app.options.route.cleanUrl,
+    )
+
     if (normalizedPath === path) return
 
     const encodedPath = encodeURI(normalizedPath)
@@ -56,7 +64,10 @@ export const redirects = JSON.parse(${JSON.stringify(
     JSON.stringify(
       Object.fromEntries(
         app.pages.flatMap((page) =>
-          resolvePageRedirects(page).map((redirect) => [redirect, page.path]),
+          resolvePageRedirects(app, page).map((redirect) => [
+            redirect,
+            page.path,
+          ]),
         ),
       ),
     ),

packages/core/src/app/resolveAppOptions.ts

@@ -38,8 +38,16 @@ export const resolveAppOptions = ({
   bundler,
   debug = false,
   markdown = {},
-  pagePatterns = ['**/*.md', '!.vuepress', '!node_modules'],
-  permalinkPattern = null,
+  pagePatterns: _pagePatterns,
+  permalinkPattern: _permalinkPattern,
+  route: {
+    cleanUrl = false,
+    pagePatterns = ['**/*.md', '!.vuepress', '!node_modules'],
+    permalinkPattern = null,
+  } = {
+    pagePatterns: _pagePatterns,
+    permalinkPattern: _permalinkPattern,
+  },
   plugins = [],
   theme,
 }: AppConfig): AppOptions => ({
@@ -65,8 +73,11 @@ export const resolveAppOptions = ({
   bundler,
   debug,
   markdown,
-  pagePatterns,
-  permalinkPattern,
+  route: {
+    cleanUrl,
+    pagePatterns,
+    permalinkPattern,
+  },
   plugins,
   theme,
 })

packages/core/src/app/resolveAppPages.ts

@@ -11,7 +11,7 @@ export const resolveAppPages = async (app: App): Promise<Page[]> => {
   log('resolveAppPages start')
 
   // resolve page absolute file paths according to the page patterns
-  const pageFilePaths = await globby(app.options.pagePatterns, {
+  const pageFilePaths = await globby(app.options.route.pagePatterns, {
     absolute: true,
     cwd: app.dir.source(),
   })

packages/core/src/page/inferPagePath.ts

@@ -23,9 +23,15 @@ export const inferPagePath = ({
 
   // infer page route path from file path
   // foo/bar.md -> /foo/bar.html
-  const pathInferred = ensureLeadingSlash(filePathRelative)
-    .replace(/\.md$/, '.html')
-    .replace(/\/(README|index).html$/i, '/')
+  let pathInferred = ensureLeadingSlash(filePathRelative).replace(
+    /\/(README|index).md$/i,
+    '/',
+  )
+
+  if (pathInferred.endsWith('.md'))
+    pathInferred =
+      pathInferred.substring(0, pathInferred.length - 3) +
+      (app.options.route.cleanUrl ? '' : '.html')
 
   // resolve page locale path
   const pathLocale = resolveLocalePath(app.siteData.locales, pathInferred)

packages/core/src/page/resolvePagePermalink.ts

@@ -34,7 +34,7 @@ export const resolvePagePermalink = ({
   }
 
   const permalinkPattern =
-    frontmatter.permalinkPattern || app.options.permalinkPattern
+    frontmatter.permalinkPattern || app.options.route.permalinkPattern
 
   if (!isString(permalinkPattern)) {
     return null

packages/core/src/types/app/options.ts

@@ -5,6 +5,12 @@ import type { Bundler } from '../bundler.js'
 import type { PluginConfig } from '../plugin.js'
 import type { Theme } from '../theme.js'
 
+export interface RouteOptions {
+  cleanUrl?: boolean
+  pagePatterns?: string[]
+  permalinkPattern?: string | null
+}
+
 /**
  * Vuepress app common config that shared between dev and build
  */
@@ -14,11 +20,9 @@ export interface AppConfigCommon extends Partial<SiteData> {
   temp?: string
   cache?: string
   public?: string
-
   debug?: boolean
   markdown?: MarkdownOptions
-  pagePatterns?: string[]
-  permalinkPattern?: string | null
+  route?: RouteOptions
   bundler: Bundler
   theme: Theme
   plugins?: PluginConfig
@@ -95,9 +99,20 @@ export interface AppConfigBuild {
 /**
  * Vuepress app config
  */
-export type AppConfig = AppConfigCommon & AppConfigDev & AppConfigBuild
+export type AppConfig = AppConfigCommon &
+  AppConfigDev &
+  AppConfigBuild & {
+    /** @deprecated use route.pagePatterns instead */
+    pagePatterns?: string[]
+    /** @deprecated use route.permalinkPattern instead */
+    permalinkPattern?: string | null
+  }
 
 /**
  * Vuepress app options
  */
-export type AppOptions = Required<AppConfig>
+export type AppOptions = Required<
+  AppConfigCommon & AppConfigDev & AppConfigBuild
+> & {
+  route: Required<RouteOptions>
+}

packages/core/tests/app/resolveAppOptions.spec.ts

@@ -30,8 +30,11 @@ describe('core > app > resolveAppOptions', () => {
       host: '0.0.0.0',
       port: 8080,
       open: false,
-      pagePatterns: ['**/*.md', '!.vuepress', '!node_modules'],
-      permalinkPattern: null,
+      route: {
+        cleanUrl: false,
+        pagePatterns: ['**/*.md', '!.vuepress', '!node_modules'],
+        permalinkPattern: null,
+      },
       templateDev: path.normalize(
         require.resolve('@vuepress/client/templates/dev.html'),
       ),

packages/shared/src/utils/index.ts

@@ -7,7 +7,6 @@ export * from './isLinkExternal.js'
 export * from './isLinkHttp.js'
 export * from './isLinkWithProtocol.js'
 export * from './isPlainObject.js'
-export * from './inferRoutePath.js'
 export * from './normalizeRoutePath.js'
 export * from './omit.js'
 export * from './removeEndingSlash.js'

packages/shared/src/utils/inferRoutePath.ts

@@ -1,7 +1,7 @@
 /**
  * Infer route path according to the given (markdown file) path
  */
-export const inferRoutePath = (path: string): string => {
+export const inferRoutePath = (path: string, cleanUrl = false): string => {
   // if the pathname is empty or ends with `/`, return as is
   if (!path || path.endsWith('/')) return path
 
@@ -21,6 +21,10 @@ export const inferRoutePath = (path: string): string => {
   if (routePath.endsWith('/index.html')) {
     routePath = routePath.substring(0, routePath.length - 10)
   }
+  // convert /foo/bar.html to /foo/bar if cleanUrl is enabled
+  else if (cleanUrl) {
+    routePath = routePath.substring(0, routePath.length - 5)
+  }
 
   return routePath
 }

packages/shared/src/utils/normalizeRoutePath.ts

@@ -5,17 +5,21 @@ const FAKE_HOST = 'http://.'
 /**
  * Normalize the given path to the final route path
  */
-export const normalizeRoutePath = (path: string, current?: string): string => {
+export const normalizeRoutePath = (
+  path: string,
+  current?: string,
+  cleanUrl = false,
+): string => {
   if (!path.startsWith('/') && current) {
     // the relative path should be resolved against the current path
     const loc = current.slice(0, current.lastIndexOf('/'))
 
     const { pathname, search, hash } = new URL(`${loc}/${path}`, FAKE_HOST)
 
-    return inferRoutePath(pathname) + search + hash
+    return inferRoutePath(pathname, cleanUrl) + search + hash
   }
 
   const [pathname, ...queryAndHash] = path.split(/(\?|#)/)
 
-  return inferRoutePath(pathname) + queryAndHash.join('')
+  return inferRoutePath(pathname, cleanUrl) + queryAndHash.join('')
 }