Config
配置说明
Configurations
为了便于配置，Valaxy 将配置分为了三种。
valaxy.config.ts 是配置的主入口，它包含了以下配置。
siteConfig: 站点信息配置，这部分内容面向站点展示，且在不同主题中也是通用的格式themeConfig: 主题配置，这部分内容仅在特定主题生效runtimeConfig: 运行时的配置（由 Valaxy 自动生成），用户无需配置- 其他 Valaxy 通用配置内容（如需要在 Node 端处理的配置
unocss/addons）
譬如：
To simplify config, Valaxy divided the configuration into 3.
valaxy.config.ts is the main entry of configuration.
siteConfig: Site info config. This affects info displayed on the site, and is independent of themes.themeConfig: Theme config. This part is effective only when the specific theme is in use.runtimeConfig: Runtime config (generated by Valaxy). You don’t need to modify the config.- Other general Valaxy config (e.g., config that’s needed for Node)
For example:
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()
],
})站点配置
Site Config
更多详细配置可参见 types/config.ts。
packages/valaxy/types/config.ts SiteConfig
ts
import type { FuseOptions } from '@vueuse/integrations/useFuse'
import type { ZoomOptions } from 'medium-zoom'
import type { ILazyLoadOptions } from 'vanilla-lazyload'
import type { RouteRecordRaw } from 'vue-router'
import type { ValaxyAddon } from '../types'
import type { DefaultTheme } from './default-theme'
import type { PostFrontMatter } from './frontmatter'
import type { FuseListItem } from './node'
import './default-theme'
/**
* @zh 社交链接
*/
export interface SocialLink {
/**
* The title of your link
*/
name: string
link: string
/**
* 图标名称
* https://icones.js.org/
*/
icon: string
/**
* @zh 图标颜色
*/
color: string
}
export interface RedirectRule {
to: string
from: string | string[]
}
export interface RedirectItem {
from: string
to: string
}
// shared with valaxy node and client
export interface SiteConfig {
/**
* enable auto (light/dark mode)
* @default 'auto'
*/
mode: 'light' | 'dark' | 'auto'
/**
* Default language
* @description 默认语言，设置 `zh-CN` 以改变默认语言为中文
* @default 'en'
*/
lang: string
/**
* alternative languages
* @description 可选语言
* @en If you want to disable multi-language support for your site, you can set this to only include one language (e.g. `['en']`)
* @zh 如果你想要禁言站点的多语言支持，可以将此项设置为仅包含一个语言 (例如 `['zh-CN']`)
* @default ['en', 'zh-CN']
* @see https://ogp.me/#optional
*/
languages: string[]
/**
* You site url in web, required for ssg & rss
* @description 站点的完整 URL，SSG & RSS 需要（譬如生成版权处文章永久链接）
* @example 'https://valaxy.site'
* @default '/'
*/
/**
* @see https://wikipedia.org/wiki/List_of_tz_database_time_zones
* @en_US Timezone configuration
* @zh_CN 时区配置，国内推荐使用 'Asia/Shanghai'
* @description:en-US This configuration is used to generate times with timezone when no timezone is set
* @description:zh-CN 当时间没有设置时区时，使用该配置生成带时区的时间
* @default ''
*/
timezone: string
url: string
/**
* Site title
* @description 站点标题
*/
title: string
/**
* 副标题
*/
subtitle: string
/**
* 站点描述
*/
description: string
/**
* The owner of this blog
* @description 博客作者
*/
author: {
/**
* Your name
* @description 你的名字
*/
name: string
email: string
link: string
avatar: string
/**
* The status of you
* @description 状态
*/
status: {
/**
* Emoji representation of your status like '👨💻'
* @description 你的状态的 Emoji 表示，如 '👨💻'
*/
emoji: string
/**
* show when hover emoji
* @description 当鼠标悬浮在图标上时显示
*/
message: string
}
/**
* @zh 个人简介
*/
intro?: string
}
/**
* show last updated time by git/mtime
*/
lastUpdated: boolean
/**
* icon for your website
*/
favicon: string
feed: {
/**
* name: feed -> feed.xml / feed.atom / feed.json
* @default '' -> feed.xml / atom.xml / feed.json
*/
name: string
favicon: string
}
/**
* 社交链接
*/
social: SocialLink[]
/**
* @en search engine for your site
* @zh 搜索功能
*/
search: {
/**
* @zh 是否启用
*/
enable: boolean
/**
* Search Type
* - algolia: Algolia Search
* - engine: Engine Search, like Google/Baidu
* - fuse: Local Search by fuse.js
*/
type: 'algolia' | 'engine' | 'fuse'
}
/**
*
* fuse search
* @see https://fusejs.io/
* @description 本地搜索
* Please set search.type to 'fuse'
*/
fuse: {
/**
* @default 'valaxy-fuse-list.json'
* @description 搜索结果列表数据所在路径
*/
dataPath: string
/**
* @see https://fusejs.io/api/options.html
*/
options: FuseOptions<FuseListItem> & {
/**
* @en_US The fields to be searched.
* @zh_CN 搜索的字段
* @default ['title', 'tags', 'categories', 'excerpt']
* @description:en-US List of keys that will be searched. This supports nested paths, weighted search, and searching in arrays of strings and objects
* @description:zh-CN 搜索将会涉及的字段列表，支持嵌套路径、加权搜索以及在字符串和对象数组中进行搜索
* @see https://fusejs.io/api/options.html#keys
*/
keys: FuseOptions<FuseListItem>['keys']
}
}
/**
* set post default frontmatter
*/
frontmatter: Partial<PostFrontMatter>
/**
* comment: waline/...
*/
comment: {
enable: boolean
}
/**
* third-party plugin need cdn
* aplayer, twikoo
* @default 'https://unpkg.com/'
*/
cdn: {
/**
* prefix for your third-party
* @default 'https://unpkg.com/'
*/
prefix: string
}
/**
* The license of your posts
* @description 文章所使用的协议，默认使用 Creative Commons
* @default https://creativecommons.org/licenses/
*/
license: {
/**
* Whether to show at the bottom of the article
* @description 是否显示在文章底部
* @default true
*/
enabled: boolean
/**
* Creative License Language, same with your config.lang
* when lang === 'zh-CN', use 'zh'
* @description 默认与站点语言相同
* @default 'en'
*/
language: string
/**
* Type of license
* @description 证书类型
* @default 'by-nc-sa'
*/
type: 'zero' | 'by-sa' | 'by-nd' | 'by-nc' | 'by-nc-sa' | 'by-nc-nd'
}
/**
* donate for author
* @description 打赏/赞助
*/
sponsor: {
enable: boolean
/**
* Donate button title attribute
* @description 打赏按钮的 title 属性
* @default zh:'打赏' en:'Donate'
*/
title?: string
/**
* Donate content description
* @description 打赏的描述内容，在按钮下方所有图片上方，与图片一起折叠
* @default undefined 不显示内容
*/
description?: string
/**
* @zh 赞助方式
*/
methods: {
name: string
url: string
color: string
icon: string
}[]
}
/**
* image preview by medium-zoom
* @url https://github.com/francoischalifour/medium-zoom
*/
mediumZoom: {
/**
* @zh 启用图片预览
*/
enable: boolean
/**
* For example: '.markdown-body img'
* @default '' content.value querySelectorAll('img')
*/
selector: string | HTMLElement | HTMLElement[]
/**
* @zh 配置项
* @see https://github.com/francoischalifour/medium-zoom#options
*/
options: ZoomOptions
}
/**
* lazyload by vanilla-lazyload and markdown-it-image-figures
* when vanillaLazyLoad.enable is true, imageFigures removeSrc is true, classes is 'lazy'
* @see https://github.com/verlok/vanilla-lazyload
*/
vanillaLazyload: {
enable: boolean
options: ILazyLoadOptions
}
/**
* Floating Vue configuration for floating footnote tooltips.
* @see https://floating-vue.starpad.dev/guide/config
*/
floatingVue: any // FloatingVueConfig is an alias of any, consult the documentation for actual type
/**
* displayed posts length in every page
* @default 7
*/
pageSize: number
/**
* statistics readingTime and wordCount
* @description 统计阅读时间和字数
*/
statistics: {
enable: boolean
readTime: {
speed: {
/**
* Chinese word count speed
* @description 中文每分钟阅读字数
* @default 300 (300 字/分钟)
*/
cn: number
/**
* English word count speed
* @description 英文每分钟阅读字数
* @default 100 (200 字/分钟)
*/
en: number
}
}
}
/**
* @description Encrypt article
* @description:zh-CN 加密文章
* default algorithm: AES-CBC
*/
encrypt: {
enable: boolean
/**
* [encrypt](https://developer.mozilla.org/zh-CN/docs/Web/API/SubtleCrypto/encrypt#%E6%94%AF%E6%8C%81%E7%9A%84%E7%AE%97%E6%B3%95)
* @default AES-CBC
*/
algorithm: string
iv: Uint8Array
salt: Uint8Array
/**
* @description:zh-CN 全局加密密码 todo
*/
// password: string
}
/**
* @description:en-US Limit the height of the code block in px
* @description:zh-CN 限制代码块的高度，单位是 px
*/
codeHeightLimit?: number
/**
* @description:en-US client redirect rules
* @description:zh-CN 客户端重定向规则
*/
redirects?: {
useVueRouter?: boolean
rules?: RedirectRule[]
}
}
export type PartialDeep<T> = {
[P in keyof T]?: T[P] extends object ? PartialDeep<T[P]> : T[P]
}
/**
* config generated by runtime
*/
export interface RuntimeConfig {
addons: Record<string, ValaxyAddon>
redirects: {
useVueRouter: boolean
redirectRoutes: RouteRecordRaw[]
}
}
export interface Pkg {
name: string
version: string
homepage?: string
[key: string]: any
}
export interface ValaxyConfig<ThemeConfig = DefaultTheme.Config> {
/**
* @en Site **info** config. This affects info displayed on the site, and is independent of themes.
* @zh 站点**信息**配置，这部分内容面向站点展示，且在不同主题中也是通用的格式
* @see [站点配置 | Valaxy](https://valaxy.site/guide/config#%E7%AB%99%E7%82%B9%E9%85%8D%E7%BD%AE)
* @see [Site Config | Valaxy](https://valaxy.site/guide/config#site-config)
*/
siteConfig: SiteConfig
/**
* The name of theme
* @description 主题名称
* @see 主题橱窗 [Valaxy Themes Gallery](https://valaxy.site/themes/gallery)
* @see 如何编写主题？ [How to write a theme? | Valaxy](https://valaxy.site/themes/write)
* @see [默认 Yun 主题示例](https://yun.valaxy.site/)
*/
theme: string
/**
* The config of theme
* @zh 请参考对应主题的相关文档
* @description 主题配置
* @see [默认 Yun 主题文档](https://github.com/YunYouJun/valaxy/blob/main/packages/valaxy-theme-yun/docs/README.md)
*/
themeConfig: ThemeConfig & {
pkg: Pkg
}
/**
* @en Generated in runtime, do not modify manually
* @zh 在运行时生成，请勿手动修改
*/
runtimeConfig: RuntimeConfig
}
/**
* user site config
*/
export type UserSiteConfig = PartialDeep<SiteConfig>
/**
* Valaxy User Config
* @description Valaxy 用户配置
*/
export type UserValaxyConfig<ThemeConfig = DefaultTheme.Config> = PartialDeep<ValaxyConfig<ThemeConfig>>站点信息配置，这部分内容面向站点展示且在任何主题也是通用的格式。
你也可以将其写在 site.config.ts 中。
譬如：
ts
// site.config.ts
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
lang: 'zh-CN',
title: 'Valaxy Theme Yun',
url: 'https://valaxy.site/',
author: {
name: '云游君',
avatar: 'https://www.yunyoujun.cn/images/avatar.jpg',
},
/**
* 站点图标
*/
favicon: 'https://www.yunyoujun.cn/favicon.svg',
/**
* 副标题
*/
subtitle: 'All at sea.',
description: 'Valaxy Theme Yun Preview.',
social: [
{
name: 'RSS',
link: '/atom.xml',
icon: 'i-ri-rss-line',
color: 'orange',
}
],
sponsor: {
enable: true,
methods: [
{
name: '支付宝',
url: 'https://cdn.yunyoujun.cn/img/donate/alipay-qrcode.jpg',
color: '#00A3EE',
icon: 'i-ri-alipay-line',
},
],
},
})Site info config. This affects info displayed on the site, and is independent of themes.
You can also write it in site.config.ts.
For example:
ts
// site.config.ts
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
lang: 'zh-CN',
title: 'Valaxy Theme Yun',
url: 'https://valaxy.site/',
author: {
name: 'Yunyoujun',
avatar: 'https://www.yunyoujun.cn/images/avatar.jpg',
},
/**
* Site favicon
*/
favicon: 'https://www.yunyoujun.cn/favicon.svg',
/**
* Subtitle
*/
subtitle: 'All at sea.',
description: 'Valaxy Theme Yun Preview.',
social: [
{
name: 'RSS',
link: '/atom.xml',
icon: 'i-ri-rss-line',
color: 'orange',
}
],
sponsor: {
enable: true,
methods: [
{
name: 'Alipay',
url: 'https://cdn.yunyoujun.cn/img/donate/alipay-qrcode.jpg',
color: '#00A3EE',
icon: 'i-ri-alipay-line',
},
],
},
})Default Frontmatter
为所有文章设置默认的 Frontmatter。
譬如：
设置
time_warning: false，则所有文章都不会显示阅读时间警告。
ts
// site.config.ts
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
/**
* 默认 Frontmatter
*/
frontmatter: {
time_warning: false,
}
})Set the default Frontmatter for all posts.
For example:
Set
time_warning: falseso that all articles won’t show reading time warnings.
ts
// site.config.ts
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
/**
* Default Frontmatter
*/
frontmatter: {
time_warning: false,
}
})社交图标
Social Icons
ts
export interface SocialLink {
/**
* 社交链接名称
*/
name: string
link: string
/**
* 图标名称
* https://icones.js.org/
*/
icon: string
color: string
}示例：
ts
export interface SocialLink {
/**
* The title of your link
*/
name: string
link: string
/**
* Icon name
* https://icones.js.org/
*/
icon: string
color: string
}Example:
ts
// site.config.ts
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
social: [
{
name: 'RSS',
link: '/atom.xml',
icon: 'i-ri-rss-line',
color: 'orange',
},
{
name: 'QQ 群 1050458482',
link: 'https://qm.qq.com/cgi-bin/qm/qr?k=kZJzggTTCf4SpvEQ8lXWoi5ZjhAx0ILZ&jump_from=webapi',
icon: 'i-ri-qq-line',
color: '#12B7F5',
},
{
name: 'GitHub',
link: 'https://github.com/YunYouJun',
icon: 'i-ri-github-line',
color: '#6e5494',
},
]
})赞助
Sponsor
在每篇文章末尾，展示赞助（打赏）信息。
ts
// site.config.ts
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
sponsor: {
enable: true,
methods: [
{
name: '支付宝',
url: 'https://cdn.yunyoujun.cn/img/donate/alipay-qrcode.jpg',
color: '#00A3EE',
icon: 'i-ri-alipay-line',
},
{
name: '微信支付',
url: 'https://cdn.yunyoujun.cn/img/donate/wechatpay-qrcode.jpg',
color: '#2DC100',
icon: 'i-ri-wechat-pay-line',
},
],
},
})你可以通过 sponsor 属性控制全局是否开启。
At the end of each post, show sponsor information.
ts
// site.config.ts
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
sponsor: {
enable: true,
methods: [
{
name: 'Alipay',
url: 'https://cdn.yunyoujun.cn/img/donate/alipay-qrcode.jpg',
color: '#00A3EE',
icon: 'i-ri-alipay-line',
},
{
name: 'WeChat Pay',
url: 'https://cdn.yunyoujun.cn/img/donate/wechatpay-qrcode.jpg',
color: '#2DC100',
icon: 'i-ri-wechat-pay-line',
},
],
},
})You can use the sponsor property to globally toggle if it’s shown.
ts
interface SponsorOption {
enable: boolean
title: string
methods: {
name: string
url: string
color: string
icon: string
}[]
}或为某篇文章的 Front Matter 单独设置：
Or you can set for each post using front matter:
md
---
title: xxx
sponsor: false
---阅读统计
开启阅读统计，将会在每篇文章开头展示阅读统计信息。
需要主题进行适配，即展示
frontmatter中的wordCount和readingTime字段。
wordCount：字数统计readingTime：阅读时长（分钟）- 可以设置不同语言的阅读速度，默认
cn为 300 字/分钟，en为 200 字/分钟。
- 可以设置不同语言的阅读速度，默认
ts
// site.config.ts
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
/**
* 开启阅读统计
*/
statistics: {
enable: true,
readTime: {
/**
* 阅读速度
*/
speed: {
cn: 300,
en: 200,
},
},
}
})代码块高度限制
Code Height Limit
你可以为每篇文章设置代码块高度限制。
You can set the height limit for each article.
譬如设置 codeHeightLimit: 300，则文章中所有代码块高度都不会超过 300px，并自动折叠。
For example, if you set codeHeightLimit: 300, the height of all code blocks in the article will not exceed 300px and will be automatically collapsed.
ts
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
// ...
codeHeightLimit: 300,
})你也可以在文章的 Front Matter 中单独设置：
You can also set it separately in the Front Matter of the article:
md
---
codeHeightLimit: 300
---示例可参见 代码块高度限制。
Example can refer to Code Height Limit.
内容加密
Content Encryption
首先在 site.config.ts 中开启加密
Firstly, enable encryption in site.config.ts.
ts
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
// ...
encrypt: {
enable: true,
}
})- 加密整篇文章
- encrypt the entire article
在文章的 Front Matter 中设置 password：
Set password in the Front Matter of the article:
md
---
password: your_password
---- 加密部分内容
- encrypt partial content
TIP提示
如果在文章的 Front Matter 中设置了 `password`，文章中的部分加密将被忽略。
If you set `password` in Front Matter, partial encryption will be ignored.
将待加密的内容包裹在 <!-- valaxy-encrypt-start:your_password --><!-- valaxy-encrypt-end --> 中。
Wrap content to be encrypted in <!-- valaxy-encrypt-start:your_password --><!-- valaxy-encrypt-end -->.
示例可参见 部分内容加密。
Examples can be found in Partial Content Encryption。
客户端重定向
Client Redirects
ts
interface Redirects {
// https://router.vuejs.org/guide/essentials/redirect-and-alias.html
// Whether to use VueRouter, default is true
useVueRouter?: boolean
rules?: RedirectRule[]
}
interface RedirectRule {
// Redirect original route
from: string | string[]
// Redirect target route
to: string
}示例：
For example:
ts
// site.config.ts
export default defineSiteConfig({
redirects: {
useVueRouter: true,
rules: [
{
from: ['/foo', '/bar'],
to: '/about',
},
{
from: '/v1/about',
to: '/about',
},
]
},
})/foo, /bar, /v1/about 这些路由会被重定向到 /about。
/foo, /bar, /v1/about these routes will be redirected to /about。
你也可以在 Front Matter 中配置：
You can also set it in the Front Matter:
md
<!-- pages/posts/redirect.md -->
---
from:
- /redirect/old1
- /redirect/old2
---md
<!-- pages/posts/redirect.md -->
---
from: /v1/redirect
---/redirect/old1, /redirect/old2, /v1/redirect 这些路由会被重定向到 /posts/redirect。
/redirect/old1, /redirect/old2, /v1/redirect these routes will be redirected to /posts/redirect。
TIP提示
在 SSG 构建时，如果 useVueRouter 为 false，则会为每一个源路由生成一个 html 文件
When building SSG, if useVueRouter is false, an html file will be generated for each original route
图片预览（Medium Zoom）
Image Preview (Medium Zoom)
Valaxy 内置了 medium-zoom 进行图片预览，默认关闭。
- mediumZoom
enable: 是否开启selector: 可自定义传入选择器options: 与 options | medium-zoom 一致
譬如开启 Medium Zoom：
Valaxy has built-in medium-zoom to preview the pictures, which is disabled by default.
- mediumZoom
enable: Set to true to enable itselector: Custom CSS selectoroptions: Refer to options | medium-zoom
a2bbd86 (docs: update vanillaLazyLoad)
ts
// site.config.ts
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
mediumZoom: { enable: true }
})除此之外，你也可以单独控制是否在某篇文章中开启。
In addition, you can also enable it in a certain article independently.
md
---
title: Test Medium Zoom
medium_zoom: true
---懒加载 Vanilla Lazyload
Lazyload Vanilla Lazyload
Valaxy 内置了 vanilla-lazyload。
vanillaLazyload 默认不开启。 因为 Valaxy 本身会为所有的图片添加 loading="lazy"，它是浏览器的特性，但如果你希望得到更广泛的兼容，你可以手动开启 vanillaLazyload。
Valaxy has built-in vanilla-lazyload。
vanillaLazyload is disabled by default. Because Valaxy itself will add loading="lazy" to all images, which is a browser feature, but if you want to get more extensive compatibility, you can manually enable it.
ts
export default defineSiteConfig({
vanillaLazyload: {
// 默认不开启
enable: true,
}
})主题配置
Theme Config
参照 使用主题 及您所使用的主题文档进行配置。
Please refer to Using Themes and the theme you are using to configure it.
To Be Continued.