Merge branch 'main' into meteorlxy-markdown-to-vue

e2e/docs/.vuepress/plugins/foo/fooPlugin.ts

@@ -1,8 +1,9 @@
+import type { Plugin } from 'vuepress/core'
 import { getDirname, path } from 'vuepress/utils'
 
 const __dirname = getDirname(import.meta.url)
 
-export const fooPlugin = {
+export const fooPlugin: Plugin = {
   name: 'test-plugin',
   clientConfigFile: path.resolve(
     __dirname,

packages/cli/tests/config/loadUserConfig.spec.ts

@@ -47,31 +47,29 @@ const MJS_CASES: [string, unknown][] = [
   ],
 ]
 
-describe('cli > config > loadUserConfig', () => {
-  describe('should load ts config file correctly', () => {
-    TS_CASES.forEach(([source, expected]) => {
-      it(JSON.stringify(source), async () => {
-        const { userConfig } = await loadUserConfig(source)
-        expect(userConfig).toEqual(expected)
-      })
+describe('should load ts config file correctly', () => {
+  TS_CASES.forEach(([source, expected]) => {
+    it(JSON.stringify(source), async () => {
+      const { userConfig } = await loadUserConfig(source)
+      expect(userConfig).toEqual(expected)
     })
   })
+})
 
-  describe('should load js config file correctly', () => {
-    JS_CASES.forEach(([source, expected]) => {
-      it(JSON.stringify(source), async () => {
-        const { userConfig } = await loadUserConfig(source)
-        expect(userConfig).toEqual(expected)
-      })
+describe('should load js config file correctly', () => {
+  JS_CASES.forEach(([source, expected]) => {
+    it(JSON.stringify(source), async () => {
+      const { userConfig } = await loadUserConfig(source)
+      expect(userConfig).toEqual(expected)
     })
   })
+})
 
-  describe('should load mjs config file correctly', () => {
-    MJS_CASES.forEach(([source, expected]) => {
-      it(JSON.stringify(source), async () => {
-        const { userConfig } = await loadUserConfig(source)
-        expect(userConfig).toEqual(expected)
-      })
+describe('should load mjs config file correctly', () => {
+  MJS_CASES.forEach(([source, expected]) => {
+    it(JSON.stringify(source), async () => {
+      const { userConfig } = await loadUserConfig(source)
+      expect(userConfig).toEqual(expected)
     })
   })
 })

packages/cli/tests/config/resolveUserConfigConventionalPath.spec.ts

@@ -14,13 +14,11 @@ const TEST_CASES: [string, string][] = [
   [resolveFixtures('case6'), '.vuepress/config.mjs'],
 ]
 
-describe('cli > config > resolveUserConfigConventionalPath', () => {
-  describe('should resolve conventional config file correctly', () => {
-    TEST_CASES.forEach(([source, expected]) => {
-      it(expected, () => {
-        const configFile = resolveUserConfigConventionalPath(source, source)
-        expect(configFile).toEqual(path.resolve(source, expected))
-      })
+describe('should resolve conventional config file correctly', () => {
+  TEST_CASES.forEach(([source, expected]) => {
+    it(expected, () => {
+      const configFile = resolveUserConfigConventionalPath(source, source)
+      expect(configFile).toEqual(path.resolve(source, expected))
     })
   })
 })

packages/cli/tests/config/resolveUserConfigPath.spec.ts

@@ -1,32 +1,30 @@
 import { path } from '@vuepress/utils'
-import { describe, expect, it, vi } from 'vitest'
+import { expect, it, vi } from 'vitest'
 import { resolveUserConfigPath } from '../../src/index.js'
 
 const resolveFixtures = (str: string): string =>
   path.resolve(__dirname, '../__fixtures__/config', str)
 
-describe('cli > config > resolveUserConfigPath', () => {
-  it('should resolve absolute file path correctly', () => {
-    const absolutePath = resolveFixtures('custom-config.ts')
-    const configFile = resolveUserConfigPath(absolutePath)
-    expect(configFile).toEqual(absolutePath)
-  })
+it('should resolve absolute file path correctly', () => {
+  const absolutePath = resolveFixtures('custom-config.ts')
+  const configFile = resolveUserConfigPath(absolutePath)
+  expect(configFile).toEqual(absolutePath)
+})
 
-  it('should resolve relative file path correctly', () => {
-    const relativePath = 'custom-config.ts'
-    const configFile = resolveUserConfigPath(relativePath, resolveFixtures(''))
-    expect(configFile).toEqual(resolveFixtures(relativePath))
-  })
+it('should resolve relative file path correctly', () => {
+  const relativePath = 'custom-config.ts'
+  const configFile = resolveUserConfigPath(relativePath, resolveFixtures(''))
+  expect(configFile).toEqual(resolveFixtures(relativePath))
+})
 
-  it('should throw an error if file does not exist', () => {
-    const consoleError = console.error
-    console.error = vi.fn()
+it('should throw an error if file does not exist', () => {
+  const consoleError = console.error
+  console.error = vi.fn()
 
-    expect(() => {
-      resolveUserConfigPath('4-0-4')
-    }).toThrow()
-    expect(console.error).toHaveBeenCalled()
+  expect(() => {
+    resolveUserConfigPath('4-0-4')
+  }).toThrow()
+  expect(console.error).toHaveBeenCalled()
 
-    console.error = consoleError
-  })
+  console.error = consoleError
 })

packages/core/src/app/appInit.ts

@@ -9,6 +9,8 @@ const log = debug('vuepress:core/app')
  * Initialize a vuepress app
  *
  * Plugins should be used before initialization.
+ *
+ * @internal
  */
 export const appInit = async (app: App): Promise<void> => {
   log('init start')

packages/core/src/app/appPrepare.ts

@@ -16,6 +16,8 @@ const log = debug('vuepress:core/app')
  * - routes
  * - site data
  * - other files that generated by plugins
+ *
+ * @internal
  */
 export const appPrepare = async (app: App): Promise<void> => {
   log('prepare start')

packages/core/src/app/appUse.ts

@@ -4,6 +4,13 @@ import { resolvePluginObject } from './resolvePluginObject.js'
 
 const log = debug('vuepress:core/app')
 
+/**
+ * Use a plugin in vuepress app.
+ *
+ * Should be called before initialization.
+ *
+ * @internal
+ */
 export const appUse = (app: App, rawPlugin: Plugin): App => {
   const pluginObject = resolvePluginObject(app, rawPlugin)
 

packages/core/src/app/createBaseApp.ts

@@ -1,5 +1,10 @@
 import { createPluginApi } from '../pluginApi/index.js'
-import type { App, AppConfig, Plugin } from '../types/index.js'
+import type {
+  App,
+  AppConfig,
+  AppPropertiesBase,
+  Plugin,
+} from '../types/index.js'
 import { appInit } from './appInit.js'
 import { appPrepare } from './appPrepare.js'
 import { appUse } from './appUse.js'
@@ -12,12 +17,16 @@ import { resolveAppWriteTemp } from './resolveAppWriteTemp.js'
 import { setupAppThemeAndPlugins } from './setupAppThemeAndPlugins.js'
 
 /**
- * Create vuepress app
+ * Create base vuepress app.
+ *
+ * Notice that the base app could not be used for dev nor build.
+ *
+ * It would be used for creating dev app or build app, or for testing.
  */
-export const createBaseApp = (config: AppConfig, isBuild = false): App => {
+export const createBaseApp = (config: AppConfig): App => {
   const options = resolveAppOptions(config)
   const dir = resolveAppDir(options)
-  const env = resolveAppEnv(options, isBuild)
+  const env = resolveAppEnv(options)
   const pluginApi = createPluginApi()
   const siteData = resolveAppSiteData(options)
   const version = resolveAppVersion()
@@ -38,7 +47,7 @@ export const createBaseApp = (config: AppConfig, isBuild = false): App => {
     use: (plugin: Plugin) => appUse(app, plugin),
     init: async () => appInit(app),
     prepare: async () => appPrepare(app),
-  } as App
+  } satisfies AppPropertiesBase as App
 
   // setup theme and plugins
   // notice that we setup theme before plugins,

packages/core/src/app/createBuildApp.ts

@@ -2,10 +2,14 @@ import type { AppConfig, BuildApp } from '../types/index.js'
 import { createBaseApp } from './createBaseApp.js'
 
 /**
- * Create vuepress build app
+ * Create vuepress build app.
  */
 export const createBuildApp = (config: AppConfig): BuildApp => {
-  const app = createBaseApp(config, true) as BuildApp
+  const app = createBaseApp(config) as BuildApp
+
+  // set env flag and add build method
+  app.env.isBuild = true
   app.build = async () => app.options.bundler.build(app)
+
   return app
 }

packages/core/src/app/createDevApp.ts

@@ -2,10 +2,14 @@ import type { AppConfig, DevApp } from '../types/index.js'
 import { createBaseApp } from './createBaseApp.js'
 
 /**
- * Create vuepress dev app
+ * Create vuepress dev app.
  */
 export const createDevApp = (config: AppConfig): DevApp => {
-  const app = createBaseApp(config, false) as DevApp
+  const app = createBaseApp(config) as DevApp
+
+  // set env flag and add dev method
+  app.env.isDev = true
   app.dev = async () => app.options.bundler.dev(app)
+
   return app
 }

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

@@ -2,6 +2,8 @@ import type { App } from '../../types/index.js'
 
 /**
  * Generate client configs temp file
+ *
+ * @internal
  */
 export const prepareClientConfigs = async (app: App): Promise<void> => {
   // plugin hook: clientConfigFile

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

@@ -21,6 +21,8 @@ if (import.meta.hot) {
 
 /**
  * Resolve page redirects
+ *
+ * @internal
  */
 const resolvePageRedirects = ({ path, pathInferred }: Page): string[] => {
   // paths that should redirect to this page, use set to dedupe

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

@@ -17,6 +17,8 @@ if (import.meta.hot) {
 
 /**
  * Generate site data temp file
+ *
+ * @internal
  */
 export const prepareSiteData = async (app: App): Promise<void> => {
   let content = `\

packages/core/src/app/resolveAppDir.ts

@@ -6,6 +6,8 @@ const require = createRequire(import.meta.url)
 
 /**
  * Create directory util function
+ *
+ * @internal
  */
 export const createAppDirFunction =
   (baseDir: string): AppDirFunction =>

packages/core/src/app/resolveAppEnv.ts

@@ -2,12 +2,11 @@ import type { AppEnv, AppOptions } from '../types/index.js'
 
 /**
  * Resolve environment flags for vuepress app
+ *
+ * @internal
  */
-export const resolveAppEnv = (
-  options: AppOptions,
-  isBuild: boolean,
-): AppEnv => ({
-  isBuild,
-  isDev: !isBuild,
+export const resolveAppEnv = (options: AppOptions): AppEnv => ({
+  isBuild: false,
+  isDev: false,
   isDebug: options.debug,
 })

packages/core/src/app/resolveAppMarkdown.ts

@@ -4,6 +4,8 @@ import type { App } from '../types/index.js'
 
 /**
  * Resolve markdown-it instance for vuepress app
+ *
+ * @internal
  */
 export const resolveAppMarkdown = async (app: App): Promise<Markdown> => {
   // plugin hook: extendsMarkdownOptions

packages/core/src/app/resolveAppOptions.ts

@@ -6,6 +6,8 @@ const require = createRequire(import.meta.url)
 
 /**
  * Create app options with default values
+ *
+ * @internal
  */
 export const resolveAppOptions = ({
   // site config
@@ -34,6 +36,7 @@ export const resolveAppOptions = ({
   templateBuild = path.normalize(
     require.resolve('@vuepress/client/templates/build.html'),
   ),
+  templateBuildRenderer = templateRenderer,
   // common config
   bundler,
   debug = false,
@@ -61,7 +64,7 @@ export const resolveAppOptions = ({
   shouldPreload,
   shouldPrefetch,
   templateBuild,
-  templateBuildRenderer: templateRenderer,
+  templateBuildRenderer,
   bundler,
   debug,
   markdown,

packages/core/src/app/resolveAppPages.ts

@@ -6,6 +6,8 @@ const log = debug('vuepress:core/app')
 
 /**
  * Resolve pages for vuepress app
+ *
+ * @internal
  */
 export const resolveAppPages = async (
   app: App,

packages/core/src/app/resolveAppSiteData.ts

@@ -4,6 +4,8 @@ import type { AppOptions, SiteData } from '../types/index.js'
  * Resolve site data for vuepress app
  *
  * Site data will also be used in client
+ *
+ * @internal
  */
 export const resolveAppSiteData = (options: AppOptions): SiteData => ({
   base: options.base,

packages/core/src/app/resolveAppVersion.ts

@@ -5,6 +5,8 @@ const require = createRequire(import.meta.url)
 
 /**
  * Resolve version of vuepress app
+ *
+ * @internal
  */
 export const resolveAppVersion = (): string => {
   const pkgJson = fs.readJsonSync(

packages/core/src/app/resolveAppWriteTemp.ts

@@ -3,6 +3,8 @@ import type { AppDir, AppWriteTemp } from '../types/index.js'
 
 /**
  * Resolve write temp file util for vuepress app
+ *
+ * @internal
  */
 export const resolveAppWriteTemp = (dir: AppDir): AppWriteTemp => {
   const writeTemp: AppWriteTemp = async (file: string, content: string) => {

packages/core/src/app/resolvePluginObject.ts

@@ -3,6 +3,8 @@ import type { App, Plugin, PluginObject } from '../types/index.js'
 
 /**
  * Resolve a plugin object according to name / path / module and config
+ *
+ * @internal
  */
 export const resolvePluginObject = <T extends PluginObject = PluginObject>(
   app: App,

packages/core/src/app/resolveThemeInfo.ts

@@ -3,6 +3,8 @@ import { resolvePluginObject } from './resolvePluginObject.js'
 
 /**
  * Resolve theme info and its parent theme info
+ *
+ * @internal
  */
 export const resolveThemeInfo = (app: App, theme: Theme): ThemeInfo => {
   // resolve current theme info

packages/core/src/app/setupAppThemeAndPlugins.ts

@@ -3,6 +3,8 @@ import { resolveThemeInfo } from './resolveThemeInfo.js'
 
 /**
  * Setup theme and plugins for vuepress app
+ *
+ * @internal
  */
 export const setupAppThemeAndPlugins = (app: App, config: AppConfig): void => {
   // recursively resolve theme info

packages/core/src/page/createPage.ts

@@ -12,6 +12,9 @@ import { resolvePagePermalink } from './resolvePagePermalink.js'
 import { resolvePageRouteMeta } from './resolvePageRouteMeta.js'
 import { resolvePageSlug } from './resolvePageSlug.js'
 
+/**
+ * Create vuepress page object
+ */
 export const createPage = async (
   app: App,
   options: PageOptions,