diff --git a/packages/@vuepress/theme-default/index.js b/packages/@vuepress/theme-default/index.js index db3e8feb51..4ad75e7355 100644 --- a/packages/@vuepress/theme-default/index.js +++ b/packages/@vuepress/theme-default/index.js @@ -1,6 +1,8 @@ const path = require('path') -// Theme API. +/** + * @type {import('@vuepress/types'.UserThemeEntry)} + */ module.exports = (options, ctx) => { const { themeConfig, siteConfig } = ctx diff --git a/packages/@vuepress/theme-default/package.json b/packages/@vuepress/theme-default/package.json index d574cd7d80..0cbbbcd481 100644 --- a/packages/@vuepress/theme-default/package.json +++ b/packages/@vuepress/theme-default/package.json @@ -24,6 +24,7 @@ "@vuepress/plugin-active-header-links": "1.9.1", "@vuepress/plugin-nprogress": "1.9.1", "@vuepress/plugin-search": "1.9.1", + "@vuepress/types": "1.9.1", "docsearch.js": "^2.5.2", "lodash": "^4.17.15", "stylus": "^0.54.8", diff --git a/packages/@vuepress/types/lib/config.ts b/packages/@vuepress/types/lib/config.ts index 2cef5e7a7d..3e4a5d8bb9 100644 --- a/packages/@vuepress/types/lib/config.ts +++ b/packages/@vuepress/types/lib/config.ts @@ -3,7 +3,8 @@ import { PostCssLoaderOptions } from "./style"; import { MarkdownConfig } from "./markdown"; import { LocaleConfig } from "./locale"; import { ThemeConfig } from "./theme"; -import { PluginTuple, PluginObject } from "./plugin"; +import { Plugins } from "./plugin"; +import { Context } from "./context"; /** * HTML tag name @@ -123,7 +124,7 @@ export interface Config { * * @see https://vuepress.vuejs.org/config/#plugins */ - plugins?: PluginObject | Array; + plugins?: Plugins; /** * Markdown options. * @@ -187,3 +188,10 @@ export interface Config { */ evergreen?: boolean; } + +/** + * Expose `VuePress` config with function support + */ +export type UserConfig = + | Config + | ((ctx: Context>) => Config); \ No newline at end of file diff --git a/packages/@vuepress/types/lib/context.ts b/packages/@vuepress/types/lib/context.ts index 158f82903e..8a41a38c06 100644 --- a/packages/@vuepress/types/lib/context.ts +++ b/packages/@vuepress/types/lib/context.ts @@ -1,3 +1,6 @@ +import { ThemeConfig } from "./theme"; +import { Config } from "./config"; + /** * Page instance. * @@ -24,7 +27,10 @@ export interface Page { * * @see https://vuepress.vuejs.org/plugin/context-api.html */ -export interface Context { +export interface Context< +T extends ThemeConfig = ThemeConfig, +C extends Config = Config +> { /** * Whether VuePress run in production environment mode. */ @@ -53,4 +59,12 @@ export interface Context { * A utility for writing temporary files to tempPath. */ writeTemp(filename: string, content: string): Promise; + /** + * Current theme config. + */ + themeConfig: T; + /** + * VuePress Config. + */ + siteConfig: C; } diff --git a/packages/@vuepress/types/lib/index.ts b/packages/@vuepress/types/lib/index.ts index fd0e666272..93516041ee 100644 --- a/packages/@vuepress/types/lib/index.ts +++ b/packages/@vuepress/types/lib/index.ts @@ -4,3 +4,4 @@ export * from './markdown' export * from './style' export * from './context' export * from './theme-default' +export * from './theme' diff --git a/packages/@vuepress/types/lib/plugin-api.ts b/packages/@vuepress/types/lib/plugin-api.ts new file mode 100644 index 0000000000..e69de29bb2 diff --git a/packages/@vuepress/types/lib/plugin.ts b/packages/@vuepress/types/lib/plugin.ts index 31e89d6ba2..335b352eee 100644 --- a/packages/@vuepress/types/lib/plugin.ts +++ b/packages/@vuepress/types/lib/plugin.ts @@ -63,3 +63,9 @@ export type PluginObject = Partial [k: string]: Record; } +/** + * Specify plugins. + * + * @see https://vuepress.vuejs.org/config/#plugins + */ +export type Plugins= PluginObject | Array; \ No newline at end of file diff --git a/packages/@vuepress/types/lib/theme.ts b/packages/@vuepress/types/lib/theme.ts index 1837ea6563..fa08347e68 100644 --- a/packages/@vuepress/types/lib/theme.ts +++ b/packages/@vuepress/types/lib/theme.ts @@ -1,4 +1,55 @@ +import { Plugins } from "./plugin"; +import { Context } from "./context"; +import { Config } from "./config"; + /** * Default theme config type */ export type ThemeConfig = any; + +/** + * Export type of theme entry + * + * @see https://vuepress.vuejs.org/theme/option-api.html + */ +export type ThemeEntry = { + /** + * plugins + */ + plugins?: Plugins; + /** + * HTML template path used in dev mode. + * + * @default https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/core/lib/client/index.dev.html + * @see https://vuepress.vuejs.org/theme/option-api.html#devtemplate + */ + devTemplate?: string; + /** + * HTML template path used in build mode + * + * @default https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/core/lib/client/index.ssr.html + * @see https://vuepress.vuejs.org/theme/option-api.html#ssrtemplate + */ + ssrTemplate?: string; + /** + * Extends a theme + * + * @see https://vuepress.vuejs.org/theme/option-api.html#extend + */ + extend?: string; + /** + * Global layout component is a component responsible for the global layout strategy. + * + * @see https://vuepress.vuejs.org/theme/option-api.html#globallayout + */ + globalLayout?: string; +}; + +/** + * Export type of theme entry with function support + * + * @see https://vuepress.vuejs.org/theme/option-api.html + */ +export type UserThemeEntry = + | ThemeEntry + | ((themeConfig: T, ctx: Context>) => ThemeEntry); diff --git a/packages/vuepress/config.d.ts b/packages/vuepress/config.d.ts index d9e272c364..84829078de 100644 --- a/packages/vuepress/config.d.ts +++ b/packages/vuepress/config.d.ts @@ -1,15 +1,31 @@ -import { Context, Config, ThemeConfig, DefaultThemeConfig } from '@vuepress/types' +import { + UserConfig, + ThemeConfig, + DefaultThemeConfig, + ThemeEntry +} from '@vuepress/types' export * from '@vuepress/types' -export type UserConfig = - | Config - | ((ctx: Context) => Config); - /** - * Helper for type prompt and type checking. + * A helper function to define VuePress config file. + * + * @see https://vuepress.vuejs.org/config/ */ export function defineConfig(config: UserConfig): void; + +/** + * A helper function to define VuePress config file, for custom theme. + * + * @see https://vuepress.vuejs.org/config/ + */ export function defineConfig4CustomTheme( config: UserConfig ): void; + +/** + * A helper function to define VuePress theme entry file. + * + * @see https://vuepress.vuejs.org/theme/option-api.html + */ +export function defineThemeEntry(config: ThemeEntry): void; diff --git a/packages/vuepress/config.js b/packages/vuepress/config.js index 4f67f7ae82..e9aff7a4b3 100644 --- a/packages/vuepress/config.js +++ b/packages/vuepress/config.js @@ -1,6 +1,6 @@ -exports.defineConfig = function (config) { - return config -} -exports.defineConfig4CustomTheme = function (config) { - return config +function define (config) { + config } +exports.defineConfig = define +exports.defineConfig4CustomTheme = define +exports.defineThemeEntry = define