@vuepress/core 2.0.0-rc.2 → 2.0.0-rc.20

package/README.md

@@ -5,7 +5,7 @@
 
 ## Documentation
 
-https://v2.vuepress.vuejs.org
+https://vuepress.vuejs.org
 
 ## License
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { MarkdownLink, MarkdownSfcBlocks, MarkdownOptions, Markdown, MarkdownHeader } from '@vuepress/markdown';
-import { PageBase, PageData, PageFrontmatter, SiteData } from '@vuepress/shared';
+import { MarkdownLink, MarkdownSfcBlocks, MarkdownOptions, Markdown } from '@vuepress/markdown';
+import { PageFrontmatter, PageBase, PageData, SiteData } from '@vuepress/shared';
 export { HeadAttrsConfig, HeadConfig, HeadTag, HeadTagEmpty, HeadTagNonEmpty, LocaleConfig, LocaleData, PageData, PageFrontmatter, PageHeader, SiteData, SiteLocaleConfig } from '@vuepress/shared';
 import { TemplateRenderer } from '@vuepress/utils';
 
@@ -11,15 +11,25 @@ import { TemplateRenderer } from '@vuepress/utils';
  * - build: bundle assets for deployment
  */
 interface Bundler {
+    /**
+     * Name of the bundler
+     */
     name: string;
+    /**
+     * Method to run vuepress app in dev mode, starting dev server
+     */
     dev: (app: App) => Promise<() => Promise<void>>;
+    /**
+     * Method to run vuepress app in build mode, generating static pages and assets
+     */
     build: (app: App) => Promise<void>;
 }
+type BundlerOptions = Record<string, unknown>;
 
 /**
  * Vuepress Page
  */
-type Page<ExtraPageData extends Record<any, any> = Record<never, never>, ExtraPageFrontmatter extends Record<any, any> = Record<string, unknown>, ExtraPageFields extends Record<any, any> = Record<never, never>> = PageBase<ExtraPageFrontmatter> & ExtraPageFields & {
+type Page<ExtraPageData extends Record<string, unknown> = Record<string, unknown>, ExtraPageFrontmatter extends Record<string, unknown> = Record<string, unknown>, ExtraPageFields extends Record<string, unknown> = Record<string, unknown>> = ExtraPageFields & PageBase<ExtraPageFrontmatter> & {
     /**
      * Data of the page, which will be available in client code
      */
@@ -73,9 +83,7 @@ type Page<ExtraPageData extends Record<any, any> = Record<never, never>, ExtraPa
      */
     permalink: string | null;
     /**
-     * Custom data to be attached to the page route record of vue-router
-     *
-     * @see https://router.vuejs.org/api/#meta
+     * Custom data to be attached to route record
      */
     routeMeta: Record<string, unknown>;
     /**
@@ -107,25 +115,19 @@ type Page<ExtraPageData extends Record<any, any> = Record<never, never>, ExtraPa
      */
     componentFilePathRelative: string;
     /**
-     * Component file chunk name
-     *
-     * Only take effect in webpack
+     * Chunk file path
      */
-    componentFileChunkName: string;
+    chunkFilePath: string;
     /**
-     * Page data file path
+     * Chunk file path relative to temp directory
      */
-    dataFilePath: string;
+    chunkFilePathRelative: string;
     /**
-     * Page data file path relative to temp directory
-     */
-    dataFilePathRelative: string;
-    /**
-     * Page data file chunk name
+     * Chunk name
      *
-     * Only take effect in webpack
+     * This will only take effect in webpack
      */
-    dataFileChunkName: string;
+    chunkName: string;
     /**
      * Rendered html file path
      */
@@ -140,11 +142,10 @@ type Page<ExtraPageData extends Record<any, any> = Record<never, never>, ExtraPa
  */
 interface PageOptions {
     /**
-     * If `filePath` is not set, this option will be used as the raw
-     * markdown content of the page.
+     * The raw markdown content of the page.
      *
-     * If `filePath` is set, this option will be ignored, while the
-     * content of the file will be used.
+     * If `content` is not provided, the file content of the `filePath`
+     * will be used.
      */
     content?: string;
     /**
@@ -167,7 +168,7 @@ type PromiseOrNot<T> = Promise<T> | T;
 interface Closable {
     close(): void;
 }
-interface Hook<Exposed, Normalized = Exposed, Result = Normalized extends (...args: any) => infer U ? U extends Promise<infer V> ? V : U : void> {
+interface Hook<Exposed, Normalized = Exposed, Result = Normalized extends (...args: any) => infer U ? U extends Promise<infer V> ? V : U : never> {
     exposed: Exposed;
     normalized: Normalized;
     result: Result;
@@ -175,7 +176,7 @@ interface Hook<Exposed, Normalized = Exposed, Result = Normalized extends (...ar
 type LifeCycleHook<T extends unknown[] = []> = Hook<(app: App, ...args: T) => PromiseOrNot<void>>;
 type ExtendsHook<T> = Hook<(extendable: T, app: App) => PromiseOrNot<void>>;
 type ClientConfigFileHook = Hook<string | ((app: App) => PromiseOrNot<string>), (app: App) => Promise<string>>;
-type AliasDefineHook = Hook<Record<string, any> | ((app: App, isServer: boolean) => PromiseOrNot<Record<string, any>>), (app: App, isServer: boolean) => Promise<Record<string, any>>>;
+type AliasDefineHook = Hook<Record<string, unknown> | ((app: App, isServer: boolean) => PromiseOrNot<Record<string, unknown>>), (app: App, isServer: boolean) => Promise<Record<string, unknown>>>;
 /**
  * List of hooks
  */
@@ -188,7 +189,7 @@ interface Hooks {
     extendsMarkdown: ExtendsHook<Markdown>;
     extendsPageOptions: ExtendsHook<PageOptions>;
     extendsPage: ExtendsHook<Page>;
-    extendsBundlerOptions: ExtendsHook<any>;
+    extendsBundlerOptions: ExtendsHook<BundlerOptions>;
     clientConfigFile: ClientConfigFileHook;
     alias: AliasDefineHook;
     define: AliasDefineHook;
@@ -263,7 +264,7 @@ interface PluginApi {
  *
  * A plugin package should have a `Plugin` as the default export
  */
-type Plugin<T extends PluginObject = PluginObject> = T | PluginFunction<T>;
+type Plugin<T extends PluginObject = PluginObject> = PluginFunction<T> | T;
 /**
  * Vuepress plugin function
  *
@@ -274,7 +275,13 @@ type PluginFunction<T extends PluginObject = PluginObject> = (app: App) => T;
  * Vuepress plugin object
  */
 interface PluginObject extends Partial<HooksExposed> {
+    /**
+     * Name of the plugin
+     */
     name: string;
+    /**
+     * Allow the plugin to be used multiple times or not
+     */
     multiple?: boolean;
 }
 /**
@@ -347,17 +354,87 @@ interface ThemeInfo {
  * Vuepress app common config that shared between dev and build
  */
 interface AppConfigCommon extends Partial<SiteData> {
+    /**
+     * Source directory of the markdown files.
+     *
+     * Vuepress will load markdown files from this directory.
+     *
+     * @required
+     */
     source: string;
+    /**
+     * Destination directory of the output files.
+     *
+     * Vuepress will output the static site files to this directory.
+     *
+     * @default `${source}/.vuepress/dist`
+     */
     dest?: string;
+    /**
+     * Temp files directory.
+     *
+     * Vuepress will write temp files to this directory.
+     *
+     * @default `${source}/.vuepress/.temp`
+     */
     temp?: string;
+    /**
+     * Cache files directory.
+     *
+     * Vuepress will write cache files to this directory.
+     *
+     * @default `${source}/.vuepress/.cache`
+     */
     cache?: string;
+    /**
+     * Public files directory.
+     *
+     * Vuepress will copy the files from public directory to the output directory.
+     *
+     * @default `${source}/.vuepress/public`
+     */
     public?: string;
+    /**
+     * Whether to enable debug mode
+     *
+     * @default false
+     */
     debug?: boolean;
+    /**
+     * Markdown options
+     *
+     * @default {}
+     */
     markdown?: MarkdownOptions;
+    /**
+     * Patterns to match the markdown files as pages
+     *
+     * @default ['**\/*.md', '!.vuepress', '!node_modules']
+     */
     pagePatterns?: string[];
+    /**
+     * Pattern to generate permalink for pages
+     *
+     * @default null
+     */
     permalinkPattern?: string | null;
+    /**
+     * Vuepress bundler
+     *
+     * @required
+     */
     bundler: Bundler;
+    /**
+     * Vuepress theme
+     *
+     * @required
+     */
     theme: Theme;
+    /**
+     * Vuepress plugins
+     *
+     * @default []
+     */
     plugins?: PluginConfig;
 }
 /**
@@ -399,14 +476,14 @@ interface AppConfigBuild {
      *
      * @default true
      */
-    shouldPreload?: ((file: string, type: string) => boolean) | boolean;
+    shouldPreload?: boolean | ((file: string, type: string) => boolean);
     /**
      * Determine what resource files should be prefetched. Use boolean value to
      * totally enable / disable.
      *
      * @default true
      */
-    shouldPrefetch?: ((file: string, type: string) => boolean) | boolean;
+    shouldPrefetch?: boolean | ((file: string, type: string) => boolean);
     /**
      * Specify the path of the HTML template to be used for build
      *
@@ -416,16 +493,20 @@ interface AppConfigBuild {
     /**
      * Specify the HTML template renderer to be used for build
      *
-     * @default templateRenderer from '@vuepress/utils'
+     * @default `import { templateRenderer } from '@vuepress/utils'`
      */
     templateBuildRenderer?: TemplateRenderer;
 }
 /**
- * Vuepress app config
+ * Vuepress app user config.
+ *
+ * It would be provided by user, typically via a config file.
  */
-type AppConfig = AppConfigCommon & AppConfigDev & AppConfigBuild;
+type AppConfig = AppConfigBuild & AppConfigCommon & AppConfigDev;
 /**
- * Vuepress app options
+ * Vuepress app options that resolved from user config.
+ *
+ * It fills all optional fields with a default value.
  */
 type AppOptions = Required<AppConfig>;
 
@@ -437,11 +518,29 @@ type AppDirFunction = (...args: string[]) => string;
  * Directory utils
  */
 interface AppDir {
+    /**
+     * Resolve file path in cache directory
+     */
     cache: AppDirFunction;
+    /**
+     * Resolve file path in temp directory
+     */
     temp: AppDirFunction;
+    /**
+     * Resolve file path in source directory
+     */
     source: AppDirFunction;
+    /**
+     * Resolve file path in dest directory
+     */
     dest: AppDirFunction;
+    /**
+     * Resolve file path in public directory
+     */
     public: AppDirFunction;
+    /**
+     * Resolve file path in client directory
+     */
     client: AppDirFunction;
 }
 /**
@@ -467,41 +566,33 @@ interface AppEnv {
 type AppWriteTemp = (file: string, content: string) => Promise<string>;
 
 /**
- * Vuepress app
+ * App base properties, will be available after creation, even before initialization
  */
-interface App {
+interface AppPropertiesBase {
     /**
-     * Directory utils
+     * Directory utils.
      */
     dir: AppDir;
     /**
-     * Environment flags
+     * Environment flags.
      */
     env: AppEnv;
     /**
-     * Options that filled all optional fields with a default value
+     * Options that filled all optional fields with a default value.
      */
     options: AppOptions;
     /**
-     * Plugin system
+     * Plugin system.
      */
     pluginApi: PluginApi;
     /**
-     * Site data, which will be used in client side
+     * Site data, which will be used in client side.
      */
     siteData: SiteData;
     /**
-     * Version of vuepress core
+     * Version of vuepress core.
      */
     version: string;
-    /**
-     * Write temp file
-     */
-    writeTemp: AppWriteTemp;
-    /**
-     * Use a plugin
-     */
-    use: (plugin: Plugin) => this;
     /**
      * Initialize app.
      *
@@ -515,6 +606,21 @@ interface App {
      * Should be called after `app.init()`.
      */
     prepare: () => Promise<void>;
+    /**
+     * Use a plugin.
+     *
+     * Should be called before `app.init()`.
+     */
+    use: (plugin: Plugin) => this;
+    /**
+     * Util to write temp file
+     */
+    writeTemp: AppWriteTemp;
+}
+/**
+ * App initialized properties, will only be available after initialization
+ */
+interface AppPropertiesInitialized {
     /**
      * Markdown-it instance.
      *
@@ -528,6 +634,10 @@ interface App {
      */
     pages: Page[];
 }
+/**
+ * Vuepress app instance
+ */
+type App = AppPropertiesBase & AppPropertiesInitialized;
 /**
  * Vuepress dev app
  */
@@ -552,294 +662,38 @@ interface BuildApp extends App {
 }
 
 /**
- * Generate client configs temp file
+ * Generate page chunk temp file of a single page
  */
-declare const prepareClientConfigs: (app: App) => Promise<void>;
+declare const preparePageChunk: (app: App, page: Page) => Promise<void>;
 
 /**
  * Generate page component temp file of a single page
  */
 declare const preparePageComponent: (app: App, page: Page) => Promise<void>;
 
-/**
- * Generate page data temp file of a single page
- */
-declare const preparePageData: (app: App, page: Page) => Promise<void>;
-
-/**
- * Generate page key to page component map temp file
- */
-declare const preparePagesComponents: (app: App) => Promise<void>;
-
-/**
- * Generate page path to page data map temp file
- */
-declare const preparePagesData: (app: App) => Promise<void>;
-
 /**
  * Generate routes temp file
  */
-declare const preparePagesRoutes: (app: App) => Promise<void>;
-
-/**
- * Generate site data temp file
- */
-declare const prepareSiteData: (app: App) => Promise<void>;
-
-/**
- * Initialize a vuepress app
- *
- * Plugins should be used before initialization.
- */
-declare const appInit: (app: App) => Promise<void>;
-
-/**
- * Prepare files for development or build
- *
- * - page components
- * - routes
- * - site data
- * - other files that generated by plugins
- */
-declare const appPrepare: (app: App) => Promise<void>;
-
-declare const appUse: (app: App, rawPlugin: Plugin) => App;
+declare const prepareRoutes: (app: App) => Promise<void>;
 
 /**
- * Create vuepress app
- */
-declare const createBaseApp: (config: AppConfig, isBuild?: boolean) => App;
-
-/**
- * Create vuepress build app
+ * Create vuepress build app.
  */
 declare const createBuildApp: (config: AppConfig) => BuildApp;
 
 /**
- * Create vuepress dev app
+ * Create vuepress dev app.
  */
 declare const createDevApp: (config: AppConfig) => DevApp;
 
-/**
- * Create directory util function
- */
-declare const createAppDirFunction: (baseDir: string) => AppDirFunction;
 /**
  * Resolve directory utils for vuepress app
  */
 declare const resolveAppDir: (options: AppOptions) => AppDir;
 
 /**
- * Resolve environment flags for vuepress app
- */
-declare const resolveAppEnv: (options: AppOptions, isBuild: boolean) => AppEnv;
-
-/**
- * Create app options with default values
+ * Create vuepress page object
  */
-declare const resolveAppOptions: ({ base, lang, title, description, head, locales, source, dest, temp, cache, public: publicDir, host, port, open, templateDev, shouldPreload, shouldPrefetch, templateBuild, bundler, debug, markdown, pagePatterns, permalinkPattern, plugins, theme, }: AppConfig) => AppOptions;
-
-/**
- * Resolve pages for vuepress app
- */
-declare const resolveAppPages: (app: App) => Promise<Page[]>;
-
-/**
- * Resolve site data for vuepress app
- *
- * Site data will also be used in client
- */
-declare const resolveAppSiteData: (options: AppOptions) => SiteData;
-
-/**
- * Resolve version of vuepress app
- */
-declare const resolveAppVersion: () => string;
-
-/**
- * Resolve write temp file util for vuepress app
- */
-declare const resolveAppWriteTemp: (dir: AppDir) => AppWriteTemp;
-
-/**
- * Resolve a plugin object according to name / path / module and config
- */
-declare const resolvePluginObject: <T extends PluginObject = PluginObject>(app: App, plugin: Plugin<T>) => T;
-
-/**
- * Resolve theme info and its parent theme info
- */
-declare const resolveThemeInfo: (app: App, theme: Theme) => ThemeInfo;
-
 declare const createPage: (app: App, options: PageOptions) => Promise<Page>;
 
-/**
- * Infer page path according to file path
- */
-declare const inferPagePath: ({ app, filePathRelative, }: {
-    app: App;
-    filePathRelative: string | null;
-}) => {
-    pathInferred: string | null;
-    pathLocale: string;
-};
-
-/**
- * Render page content and extract related info
- */
-declare const renderPageContent: ({ app, content, filePath, filePathRelative, options, }: {
-    app: App;
-    content: string;
-    filePath: string | null;
-    filePathRelative: string | null;
-    options: PageOptions;
-}) => {
-    contentRendered: string;
-    deps: string[];
-    markdownEnv: Record<string, unknown>;
-    frontmatter: PageFrontmatter;
-    headers: MarkdownHeader[];
-    links: MarkdownLink[];
-    sfcBlocks: MarkdownSfcBlocks;
-    title: string;
-};
-
-/**
- * Resolve page component and related info
- */
-declare const resolvePageComponentInfo: ({ app, htmlFilePathRelative, key, }: {
-    app: App;
-    htmlFilePathRelative: string;
-    key: string;
-}) => Promise<{
-    componentFilePath: string;
-    componentFilePathRelative: string;
-    componentFileChunkName: string;
-}>;
-
-/**
- * Resolve page data file path
- */
-declare const resolvePageDataInfo: ({ app, htmlFilePathRelative, key, }: {
-    app: App;
-    htmlFilePathRelative: string;
-    key: string;
-}) => {
-    dataFilePath: string;
-    dataFilePathRelative: string;
-    dataFileChunkName: string;
-};
-
-/**
- * Resolve page date according to frontmatter or file path
- *
- * It will be resolved as 'yyyy-MM-dd' format
- */
-declare const resolvePageDate: ({ frontmatter, filePathRelative, }: {
-    frontmatter: PageFrontmatter;
-    filePathRelative: string | null;
-}) => string;
-
-/**
- * Resolve page file content according to filePath or options content
- */
-declare const resolvePageFileContent: ({ filePath, options, }: {
-    filePath: string | null;
-    options: PageOptions;
-}) => Promise<string>;
-
-/**
- * Resolve absolute and relative path of page file
- */
-declare const resolvePageFilePath: ({ app, options, }: {
-    app: App;
-    options: PageOptions;
-}) => {
-    filePath: string | null;
-    filePathRelative: string | null;
-};
-
-/**
- * Resolve page rendered html file path
- */
-declare const resolvePageHtmlInfo: ({ app, path: pagePath, }: {
-    app: App;
-    path: string;
-}) => {
-    htmlFilePath: string;
-    htmlFilePathRelative: string;
-};
-
-/**
- * Resolve page key to identify the page
- */
-declare const resolvePageKey: ({ path }: {
-    path: string;
-}) => string;
-
-/**
- * Resolve language of page
- */
-declare const resolvePageLang: ({ app, frontmatter, pathLocale, }: {
-    app: App;
-    frontmatter: PageFrontmatter;
-    pathLocale: string;
-}) => string;
-
-/**
- * Resolve the final route path of a page
- */
-declare const resolvePagePath: ({ permalink, pathInferred, options, }: {
-    permalink: string | null;
-    pathInferred: string | null;
-    options: PageOptions;
-}) => string;
-
-/**
- * Resolve page permalink from frontmatter / options / pattern
- */
-declare const resolvePagePermalink: ({ app, frontmatter, slug, date, pathInferred, pathLocale, }: {
-    app: App;
-    frontmatter: PageFrontmatter;
-    slug: string;
-    date: string;
-    pathInferred: string | null;
-    pathLocale: string;
-}) => string | null;
-
-/**
- * Resolve page route meta
- */
-declare const resolvePageRouteMeta: ({ frontmatter, }: {
-    frontmatter: PageFrontmatter;
-}) => Record<string, unknown>;
-
-/**
- * Resolve page slug from filename
- */
-declare const resolvePageSlug: ({ filePathRelative, }: {
-    filePathRelative: string | null;
-}) => string;
-
-/**
- * Create hook queue for plugin system
- */
-declare const createHookQueue: <T extends keyof Hooks>(name: T) => HookQueue<T>;
-
-declare const createPluginApi: () => PluginApi;
-
-declare const createPluginApiHooks: () => PluginApi['hooks'];
-
-declare const createPluginApiRegisterHooks: (plugins: PluginApi['plugins'], hooks: PluginApi['hooks']) => PluginApi['registerHooks'];
-
-/**
- * Normalize alias and define hook
- */
-declare const normalizeAliasDefineHook: (hook: AliasDefineHook['exposed']) => AliasDefineHook['normalized'];
-
-/**
- * Normalize hook for client config file
- */
-declare const normalizeClientConfigFileHook: (hook: ClientConfigFileHook['exposed']) => ClientConfigFileHook['normalized'];
-
-export { type AliasDefineHook, type App, type AppConfig, type AppConfigBuild, type AppConfigCommon, type AppConfigDev, type AppDir, type AppDirFunction, type AppEnv, type AppOptions, type AppWriteTemp, type BuildApp, type Bundler, type ClientConfigFileHook, type DevApp, type ExtendsHook, type Hook, type HookItem, type HookQueue, type Hooks, type HooksExposed, type HooksName, type HooksNormalized, type HooksResult, type LifeCycleHook, type Page, type PageOptions, type Plugin, type PluginApi, type PluginConfig, type PluginFunction, type PluginObject, type Theme, type ThemeFunction, type ThemeInfo, type ThemeObject, appInit, appPrepare, appUse, createAppDirFunction, createBaseApp, createBuildApp, createDevApp, createHookQueue, createPage, createPluginApi, createPluginApiHooks, createPluginApiRegisterHooks, inferPagePath, normalizeAliasDefineHook, normalizeClientConfigFileHook, prepareClientConfigs, preparePageComponent, preparePageData, preparePagesComponents, preparePagesData, preparePagesRoutes, prepareSiteData, renderPageContent, resolveAppDir, resolveAppEnv, resolveAppOptions, resolveAppPages, resolveAppSiteData, resolveAppVersion, resolveAppWriteTemp, resolvePageComponentInfo, resolvePageDataInfo, resolvePageDate, resolvePageFileContent, resolvePageFilePath, resolvePageHtmlInfo, resolvePageKey, resolvePageLang, resolvePagePath, resolvePagePermalink, resolvePageRouteMeta, resolvePageSlug, resolvePluginObject, resolveThemeInfo };
+export { type AliasDefineHook, type App, type AppConfig, type AppConfigBuild, type AppConfigCommon, type AppConfigDev, type AppDir, type AppDirFunction, type AppEnv, type AppOptions, type AppPropertiesBase, type AppPropertiesInitialized, type AppWriteTemp, type BuildApp, type Bundler, type BundlerOptions, type ClientConfigFileHook, type DevApp, type ExtendsHook, type Hook, type HookItem, type HookQueue, type Hooks, type HooksExposed, type HooksName, type HooksNormalized, type HooksResult, type LifeCycleHook, type Page, type PageOptions, type Plugin, type PluginApi, type PluginConfig, type PluginFunction, type PluginObject, type Theme, type ThemeFunction, type ThemeInfo, type ThemeObject, createBuildApp, createDevApp, createPage, preparePageChunk, preparePageComponent, prepareRoutes, resolveAppDir };