Extend Config
TIP提示
扩展配置是 Valaxy 提供的高阶配置,允许你自定义更多与底层/构建相关的配置。
以下是所有的扩展配置项与相关类型。
package/valaxy/node/types.ts ValaxyExtendConfig
ts
import type Vue from '@vitejs/plugin-vue'
import type { Options as BeastiesOptions } from 'beasties'
import type { Hookable } from 'hookable'
import type { PluginVisualizerOptions } from 'rollup-plugin-visualizer'
import type { presetAttributify, presetIcons, presetTypography, presetUno } from 'unocss'
import type { VitePluginConfig as UnoCSSConfig } from 'unocss/vite'
import type Components from 'unplugin-vue-components/vite'
import type Markdown from 'unplugin-vue-markdown/vite'
import type { EditableTreeNode } from 'unplugin-vue-router'
import type Router from 'unplugin-vue-router/vite'
import type { DefaultTheme, PartialDeep, ValaxyAddon, ValaxyConfig } from 'valaxy/types'
import type { UserConfig as ViteUserConfig } from 'vite'
import type Layouts from 'vite-plugin-vue-layouts'
import type { createValaxyNode } from './app'
import type { ResolvedValaxyOptions } from './options'
import type { MarkdownOptions } from './plugins/markdown/types'
export type ValaxyNodeConfig<ThemeConfig = DefaultTheme.Config> = ValaxyConfig<ThemeConfig> & ValaxyExtendConfig
export type UserValaxyNodeConfig<ThemeConfig = DefaultTheme.Config> = PartialDeep<ValaxyNodeConfig<ThemeConfig>>
/**
* fn with options for theme config
*/
export type ValaxyConfigFn<ThemeConfig = DefaultTheme.Config> = (options: ResolvedValaxyOptions<ThemeConfig>) => ValaxyNodeConfig | Promise<ValaxyNodeConfig>
export type ValaxyConfigExport<ThemeConfig = DefaultTheme.Config> = ValaxyNodeConfig<ThemeConfig> | ValaxyConfigFn<ThemeConfig>
export type HookResult = Promise<void> | void
export interface ValaxyHooks {
'options:resolved': () => HookResult
'config:init': () => HookResult
/**
* @see valaxy/node/plugins/vueRouter.ts extendRoute
*/
'vue-router:extendRoute': (route: EditableTreeNode) => HookResult
'build:before': () => HookResult
'build:after': () => HookResult
}
export interface ValaxyNode {
version: string
hooks: Hookable<ValaxyHooks>
hook: ValaxyNode['hooks']['hook']
options: ResolvedValaxyOptions
}
export interface ValaxyExtendConfig {
/**
* Don't fail builds due to dead links.
*
* @default false
* @deprecated use `build.ignoreDeadLinks` instead
*/
ignoreDeadLinks?:
| boolean
| 'localhostLinks'
| (string | RegExp | ((link: string) => boolean))[]
/**
* options for `valaxy build`
*/
build: {
/**
* Don't fail builds due to dead links.
* @zh 忽略死链
* @default false
*/
ignoreDeadLinks?:
| boolean
| 'localhostLinks'
| (string | RegExp | ((link: string) => boolean))[]
/**
* Enable SSG for pagination
* @en When enabled, it will generate pagination pages for you. `/page/1`, `/page/2`, ...
* @zh 启用 SSG 分页,将单独构建分页页面 `/page/1`, `/page/2`, ...
* @default false
*/
ssgForPagination: boolean
}
/**
* @experimental
* Deploy to gh-pages/remote server
*/
deploy: {
/**
* @zh 部署类型
* @en deploy type
*/
type?: 'gh-pages' | 'remote'
}
/**
* internal modules
*/
modules: {
rss: {
/**
* enable rss
*/
enable: boolean
/**
* @zh 全文输出
* @en full text output
* @default false
*/
fullText: boolean
}
}
/**
* Markdown Feature
*/
features: {
/**
* enable katex for global
* @see [Example | Valaxy](https://valaxy.site/examples/katex)
* @see https://katex.org/
*/
katex: boolean
}
/**
* vite.config.ts options
* @see https://vite.dev/
*/
vite?: ViteUserConfig
/**
* @vitejs/plugin-vue options
* @see https://github.com/vitejs/vite-plugin-vue/blob/main/packages/plugin-vue/README.md
*/
vue?: Parameters<typeof Vue>[0] & {
isCustomElement?: ((tag: string) => boolean)[]
}
/**
* @see https://github.com/unplugin/unplugin-vue-components
*
* exclude @default components/.exclude
*/
components?: Parameters<typeof Components>[0]
/**
* @see https://github.com/JohnCampionJr/vite-plugin-vue-layouts
*/
layouts?: Parameters<typeof Layouts>[0]
/**
* @see https://github.com/posva/unplugin-vue-router
*/
router?: Parameters<typeof Router>[0]
/**
* @see https://unocss.dev/config/
*/
unocss?: UnoCSSConfig
/**
* rollup-plugin-visualizer
* @see https://github.com/btd/rollup-plugin-visualizer
*/
visualizer?: PluginVisualizerOptions
/**
* unocss presets
* @see https://unocss.dev/guide/presets
*/
unocssPresets?: {
uno?: Parameters<typeof presetUno>[0]
attributify?: Parameters<typeof presetAttributify>[0]
icons?: Parameters<typeof presetIcons>[0]
typography?: Parameters<typeof presetTypography>[0]
}
fuse?: {
/**
* @en_US Extends the metadata fields returned by the search
* @zh_CN 扩展搜索返回的元数据字段
* @default []
* @description:en-US By default, returns the following fields: title, tags, categories, author, excerpt, link
* @description:zh-CN 默认返回以下字段:title、tags、categories、author、excerpt、link
*/
extendKeys?: string[]
}
/**
* @experimental
* Enable Vue Devtools & Valaxy Devtools
* @see https://devtools-next.vuejs.org/
*/
devtools?: boolean
/**
* @en config for markdown (include markdown-it plugins)
* @zh markdown 相关配置
* {@link MarkdownOptions}
*/
markdown?: MarkdownOptions & Parameters<typeof Markdown>[0]
/**
* @en Extend markdown, you can modify the markdown content/excerpt
* @zh 扩展 markdown
*/
extendMd?: (ctx: {
route: EditableTreeNode
data: Readonly<Record<string, any>>
content: string
excerpt?: string
path: string
}) => void
/**
* @en Addons system
* @zh 插件系统
* @see 为什么需要插件? [Why Addon? | Valaxy](https://valaxy.site/addons/why)
* @see 插件橱窗 [Addons Gallery | Valaxy](https://valaxy.site/addons/gallery)
* @example
* ```ts
* import { defineValaxyConfig } from 'valaxy'
* import { addonTest } from 'valaxy-addon-test'
*
* export default defineValaxyConfig({
* addons: [
* // we always recommend to use function, so that you can pass options
* addonTest(),
* ]
* })
* ```
*/
addons?: ValaxyAddons
/**
* @en Hooks system, you can customize each stage of the lifecycle.
* @zh 钩子系统,你可以对生命周期的各个阶段进行定制。
* @see https://valaxy.site/guide/custom/hooks
*/
hooks?: Partial<ValaxyHooks>
/**
* beastiesOptions
* @see https://github.com/danielroe/beasties
*/
beastiesOptions?: BeastiesOptions
}
export type ValaxyAddonLike = ValaxyAddon | false | null | undefined
export type ValaxyAddons = (ValaxyAddon | string)[] | Record<string, ValaxyAddonLike>
export type ValaxyAddonFn<ThemeConfig = DefaultTheme.Config> = (addonOptions: ValaxyAddonResolver, valaxyOptions: ResolvedValaxyOptions<ThemeConfig>) => ValaxyNodeConfig | Promise<ValaxyNodeConfig>
export type ValaxyAddonExport<ThemeConfig = DefaultTheme.Config> = ValaxyNodeConfig<ThemeConfig> | ValaxyAddonFn<ThemeConfig>
export interface ValaxyAddonResolver {
name: string
root: string
enable: boolean
global: boolean
props: Record<string, any>
options: Record<string, any>
configFile?: string
pkg: Record<string, any>
setup?: (node: ValaxyNode) => void
}
export type ValaxyApp = ReturnType<typeof createValaxyNode>
所以,你可以像这样使用:
So you can use it like this:
ts
import type { ThemeConfig } from 'valaxy-theme-yun'
// valaxy.config.ts
import { defineValaxyConfig } from 'valaxy'
import { addonComponents } from 'valaxy-addon-components'
import { VitePWA } from 'vite-plugin-pwa'
const safelist = [
'i-ri-home-line',
]
export default defineValaxyConfig<ThemeConfig>({
// site config see site.config.ts or write in siteConfig
siteConfig: {},
theme: 'yun',
themeConfig: {
banner: {
enable: true,
title: '云游君的小站',
},
},
vite: {
// https://vite-pwa-org.netlify.app/
plugins: [VitePWA()],
},
unocss: {
safelist,
},
addons: [
addonComponents()
],
})
@vitejs/plugin-vue
Valaxy 默认集成了 @vitejs/plugin-vue
插件,你可以通过 vue
配置项进行配置。
ts
// valaxy.config.ts
import { defineValaxyConfig } from 'valaxy'
export default defineValaxyConfig({
vue: {
template: {
compilerOptions: {
isCustomElement: tag => tag.startsWith('my-')
}
}
}
})
Vite
你可以参见 Vite 文档 自定义 Vite 相关配置。
ts
import { defineValaxyConfig } from 'valaxy'
export default defineValaxyConfig({
vite: {
plugins: []
}
})
Markdown
可自定义 Markdown 相关配置,如代码主题、区块内容、添加 markdown-it
插件、transformer 等。
效果参见: Markdown。
valaxy/node/plugins/markdown/types.ts
ts
import type {
HeadersPluginOptions,
} from '@mdit-vue/plugin-headers'
import type { SfcPluginOptions } from '@mdit-vue/plugin-sfc'
import type { TocPluginOptions } from '@mdit-vue/plugin-toc'
import type { KatexOptions } from 'katex'
import type MarkdownIt from 'markdown-it'
import type anchorPlugin from 'markdown-it-anchor'
import type {
BuiltinTheme,
Highlighter,
LanguageInput,
ShikiTransformer,
ThemeRegistration
,
} from 'shiki'
import type { PageData } from 'valaxy/types'
// import type { lazyloadOptions } from './plugins/markdown-it/lazyload'
import type { Blocks, ContainerOptions } from './plugins/markdown-it/container'
export type ThemeOptions =
| ThemeRegistration
| BuiltinTheme
| {
light: ThemeRegistration | BuiltinTheme
dark: ThemeRegistration | BuiltinTheme
}
/**
* Extend Markdown options
* @zh 扩展 Markdown 配置,包含代码高亮、Markdown-it 和插件配置
*/
export interface MarkdownOptions {
/**
* Setup markdown-it instance before applying plugins
*/
preConfig?: (md: MarkdownIt) => void
/**
* markdown-it options
*/
options?: MarkdownIt['options']
/**
* config markdown-it
*/
config?: (md: MarkdownIt) => void
anchor?: anchorPlugin.AnchorOptions
attrs?: {
leftDelimiter?: string
rightDelimiter?: string
allowedAttributes?: string[]
disable?: boolean
}
/* ==================== Syntax Highlighting ==================== */
/**
* Custom theme for syntax highlighting.
*
* You can also pass an object with `light` and `dark` themes to support dual themes.
*
* @see You can use an existing theme. https://shiki.style/themes
* @see Or add your own theme. https://shiki.style/guide/load-theme
*
* @example { theme: 'github-dark' }
* @example light and dark themes
* ```js
* { theme: { light: 'github-light', dark: 'github-dark' } }
* ```
*/
theme?: ThemeOptions
/**
* Languages for syntax highlighting.
* @see https://shiki.style/languages
*/
languages?: LanguageInput[]
/**
* Custom language aliases.
*
* @example { 'my-lang': 'js' }
* @see https://shiki.style/guide/load-lang#custom-language-aliases
*/
languageAlias?: Record<string, string>
/**
* Show line numbers in code blocks
* @default false
*/
lineNumbers?: boolean
/**
* Fallback language when the specified language is not available.
*/
defaultHighlightLang?: string
/**
* Transformers applied to code blocks
* @see https://shiki.style/guide/transformers
*/
codeTransformers?: ShikiTransformer[]
/**
* Setup Shiki instance
*/
shikiSetup?: (shiki: Highlighter) => void | Promise<void>
/* ==================== Markdown It Plugins ==================== */
// mdit-vue plugins
/**
* Options for `@mdit-vue/plugin-headers`
* @see https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-headers
*/
headers?: HeadersPluginOptions | boolean
/**
* Options for `@mdit-vue/plugin-sfc`
* @see https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-sfc
*/
sfc?: SfcPluginOptions
/**
* Options for `@mdit-vue/plugin-toc`
* @see https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc
*/
toc?: TocPluginOptions
/**
* Options for `markdown-it-container`
* @see https://github.com/markdown-it/markdown-it-container
*/
container?: ContainerOptions
/**
* Custom block configurations based on `markdown-it-container`
*/
blocks?: Blocks
/**
* @see [markdown-it-image-figures](https://www.npmjs.com/package/markdown-it-image-figures)
*/
imageFigures?: {
lazy: boolean
removeSrc: boolean
async: boolean
classes: string
}
/**
* @see https://katex.org/docs/options.html
*/
katex?: KatexOptions
externalLinks?: Record<string, string>
/* lazyload?: {
enabled?: boolean
options: lazyloadOptions
} */
}
export interface MarkdownCompileResult {
vueSrc: string
pageData: PageData
deadLinks: { url: string, file: string }[]
includes: string[]
}
ts
import { defineValaxyConfig } from 'valaxy'
export default defineValaxyConfig({
markdown: {
// default material-theme-palenight
// theme: 'material-theme-palenight',
theme: {
// light: 'material-theme-lighter',
light: 'github-light',
// dark: 'material-theme-darker',
dark: 'github-dark',
},
blocks: {
tip: {
icon: 'i-carbon-thumbs-up',
text: 'ヒント',
langs: {
'zh-CN': '提示',
},
},
warning: {
icon: 'i-carbon-warning-alt',
text: '注意',
},
danger: {
icon: 'i-carbon-warning',
text: '警告',
},
info: {
text: 'información',
},
},
codeTransformers: [
// We use `[!code` in demo to prevent transformation, here we revert it back.
{
postprocess(code) {
return code.replace(/\[!!code/g, '[!code')
},
},
],
config(md) {
// md.use(xxx)
}
},
})
DevTools
设置 devtools: false
以关闭 DevTools。
插件 addons
参见 使用插件。
UnoCSS
参见 UnoCSS。