Config
Configurations
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:
import type { ThemeConfig } from 'valaxy-theme-yun'
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: {
// Theme layout type: 'nimbo' (default, modern) or 'strato' (classic sidebar)
// See: https://github.com/YunYouJun/valaxy/blob/main/packages/valaxy-theme-yun/docs
type: 'nimbo',
banner: {
enable: true,
title: '云游君的小站',
},
},
vite: {
// https://vite-pwa-org.netlify.app/
plugins: [
VitePWA({
workbox: {
// SSG pages need their own HTML; disable the SPA fallback.
navigateFallback: null,
},
}),
],
},
unocss: {
safelist,
},
addons: [
addonComponents()
],
})See Using vite-plugin-pwa for SSG configuration and updating or removing an existing service worker.
Site Config
For more details, see types/config.ts.
packages/valaxy/types/config.ts SiteConfig
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 './addon'
import type { DefaultTheme } from './default-theme'
import type { PostFrontMatter } from './frontmatter'
import type { ExcerptType } from './frontmatter/post'
import type { FuseListItem } from './node'
import './default-theme'
/**
* @zh 社交链接
*/
export interface SocialLink {
/**
* The title of your link
*/
name: string
link: string
/**
* @description:en-US Set false for navigation links that do not identify the author (e.g. groups or custom subscriptions).
* @description:zh-CN 非作者身份主页(如群聊、自定义订阅入口)设为 false,仅从 JSON-LD sameAs 中排除,不影响导航。
*/
sameAs?: boolean
/**
* 图标名称
* 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
/**
* @description:en-US Public email. Omitted from RSS and JSON-LD when empty. Valaxy does not fill this in.
* @description:zh-CN 公开邮箱。留空时不会写入 RSS 和 JSON-LD,框架不会代填。
*/
email: string
/**
* @description:en-US Author URL. Omitted from RSS and JSON-LD when empty. Valaxy does not fill this in.
* @description:zh-CN 作者链接。留空时不会写入 RSS 和 JSON-LD,框架不会代填。
*/
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
}
/**
* order posts by 'date' or 'updated'
*
* - date: 按创建时间排序
* - updated: 按最后更新时间排序
*
* 当开启 `lastUpdated` 时,`updated` 会按照文件的更新时间自动赋值
*
* @default 'date'
*/
orderBy: 'date' | 'updated'
/**
* show last updated time by git/mtime
* @default false
*/
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
* - local: Local Search by MiniSearch
*/
provider: 'algolia' | 'engine' | 'fuse' | 'local'
}
/**
*
* fuse search
* @see https://fusejs.io/
* @description 本地搜索
* Please set search.provider to 'fuse'
*/
fuse: {
/**
* @default 'valaxy-fuse-list.json'
* @description 搜索结果列表数据所在路径
*/
dataPath: string
/**
* Glob pattern (tinyglobby) to match Fuse List Data
* @default `pages\/**\/*.md`
* ```ts
* await glob(`${userRoot}/pages/posts/**\/*.md`)
* ```
*/
pattern?: 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']
}
}
/**
* Excerpt configuration
* @description:en-US Global excerpt settings for posts
* @description:zh-CN 全局摘要配置
*/
excerpt: {
/**
* @description:en-US Default excerpt render type for `<!-- more -->` and auto-generated excerpts.
* Can be overridden per-post via frontmatter `excerpt_type`.
* Does not apply when frontmatter `excerpt` is set manually (used as-is).
* @description:zh-CN `<!-- more -->` 及自动摘要的默认渲染类型,可通过 frontmatter `excerpt_type` 逐篇覆盖。
* 当 frontmatter 手动指定 `excerpt` 时不生效(直接使用原始字符串)。
* @default 'html'
*/
type: ExcerptType
/**
* @description:en-US Auto-generate excerpt from post content when no manual excerpt is provided
* @description:zh-CN 当没有手动指定摘要时,自动从文章内容截取摘要
* @default false
*/
auto: boolean
/**
* @description:en-US Maximum length of auto-generated excerpt (in characters)
* @description:zh-CN 自动摘要的最大长度(字符数)
* @default 200
*/
length: number
}
/**
* Which source files are published.
* @description:en-US Controls drafts, underscore paths, and README pages. Development still previews `draft: true`.
* @description:zh-CN 控制草稿、下划线路径和 README 页面。开发模式仍会预览 `draft: true`。
*/
publishing: {
/**
* @description:en-US Include `draft: true` pages in production HTML, the sitemap, RSS, and llms output.
* @description:zh-CN 在生产 HTML、sitemap、RSS 和 llms 中包含 `draft: true` 的页面。
* @default false
*/
drafts: boolean
/**
* @description:en-US Publish files and directories under `pages/` whose names start with `_`, including `pages/_drafts`.
* @description:zh-CN 发布 `pages/` 下名称以 `_` 开头的文件和目录,包括 `pages/_drafts`。
* @default false
*/
underscore: boolean
/**
* @description:en-US Publish `README.md` files under `pages/` as routes.
* @description:zh-CN 将 `pages/` 下的 `README.md` 发布为路由。
* @default false
*/
readme: boolean
}
/**
* 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
}
/**
* 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:en-US Global encryption password, read from env `VALAXY_ENCRYPT_PASSWORD`.
* When a post has `encrypt: true` in frontmatter but no `password`, this is used.
* Do NOT put passwords in config files — use `.env` or CI secrets.
* @description:zh-CN 全局加密密码,从环境变量 `VALAXY_ENCRYPT_PASSWORD` 读取。
* 当文章 frontmatter 设置了 `encrypt: true` 但未指定 `password` 时使用。
* 请勿在配置文件中设置密码——请使用 `.env` 文件或 CI secrets。
*/
// password is read from process.env.VALAXY_ENCRYPT_PASSWORD at build time
}
/**
* @description:en-US Limit the height of the code block in px
* @description:zh-CN 限制代码块的高度,单位是 px
*/
codeHeightLimit?: number
/**
* @zh llms.txt 及原始 Markdown 文件输出
* @en llms.txt and raw Markdown file output
* @see https://llmstxt.org/
*/
llms: {
/**
* @zh 是否开启 llms.txt 和 .md 原始文件输出
* @en Enable llms.txt and raw .md file output
* @default false
*/
enable: boolean
/**
* @zh 是否生成 llms-full.txt(包含所有文章完整内容)
* @en Whether to generate llms-full.txt (with all post content inlined)
* @default true
*/
fullText: boolean
/**
* @zh 是否为每篇文章生成独立的 .md 文件(可通过 /posts/xxx.md 访问)
* @en Whether to generate individual .md files for each post (accessible via /posts/xxx.md)
* @default true
*/
files: boolean
/**
* @zh 自定义提示词(添加到 llms.txt blockquote 部分)
* @en Custom prompt text (added to the llms.txt blockquote section)
* @default ''
*/
prompt: string
/**
* @zh 要包含的 markdown 文件 glob 模式(相对于 pages/ 目录)。
* 默认为 `['posts\/**\/*.md']` 仅包含 posts。
* 设为 `['**\/*.md']` 可包含所有 pages 下的 markdown 文件。
* 也可以指定多个目录,如 `['posts\/**\/*.md', 'guide\/**\/*.md']`。
* @en Glob patterns for markdown files to include (relative to pages/ directory).
* Defaults to `['posts\/**\/*.md']` to only include posts.
* Set to `['**\/*.md']` to include all markdown files under pages/.
* You can also specify multiple directories, e.g. `['posts\/**\/*.md', 'guide\/**\/*.md']`.
* @default ['posts\/**\/*.md']
*/
include?: string[]
/**
* @zh 从 `llms.txt` 和 `llms-full.txt` 排除的 glob(相对于 `pages/`,语法与 `include` 相同)。
* `files` 仍会写出对应的 `.md` 文件。
* 不设置时不做排除,因此只开启 `enable` 的站点保持原有输出。
* @en Glob patterns, relative to `pages/` and using the same syntax as `include`, omitted from `llms.txt` and `llms-full.txt`.
* Individual `.md` files are still written when `files` is true.
* Unset means nothing is excluded, so sites that only enable llms keep their previous output.
*/
exclude?: string[]
/**
* @zh `llms.txt` 分组标题的顺序,例如 `['Guide', 'Posts']`。未列出的分组按原顺序排在后面。匹配时忽略大小写。
* @en Section headings in `llms.txt`, first to last, for example `['Guide', 'Posts']`. Headings you omit keep their original order after these. Matching ignores case.
*/
sectionOrder?: string[]
/**
* @zh 作为语言而不是栏目的 URL 前缀,例如 `['zh']`。
* `/zh/guide/why` 会归入 `Guide (zh)`,而不是把所有中文页放进一个 `Zh` 分组。
* 不设置时仍用路径的第一段作为分组名。
* @en URL prefixes that are languages rather than sections, for example `['zh']`.
* `/zh/guide/why` is grouped as `Guide (zh)` instead of placing every Chinese page in one `Zh` section.
* Unset keeps the first path segment as the section name.
*/
locales?: string[]
/**
* @zh 在 `llms.txt` 开头置顶的页面。
* @en Pages pinned to the start of `llms.txt`.
*/
featured?: LlmsFeatured
/**
* @zh 把一批页面折叠成 `llms.txt` 中的一条链接,并从不写入 `llms-full.txt`。
* 对应的 `.md` 文件仍会生成。适合把 API 参考收成一个 `/api/` 入口。
* @en Replace a set of pages with one `llms.txt` link and omit them from `llms-full.txt`.
* The `.md` files are still generated. Use this to collapse an API reference to a single `/api/` entry.
*/
collapse?: LlmsCollapse[]
}
/**
* @description:en-US client redirect rules
* @description:zh-CN 客户端重定向规则
*/
redirects?: {
useVueRouter?: boolean
rules?: RedirectRule[]
}
}
/**
* One `llms.txt` link that stands in for every page matching `match`.
*/
export interface LlmsCollapse {
/**
* @zh 相对于 `pages/` 的 glob,语法与 `include` 相同,例如 `api/**\/*.md`。
* @en Glob relative to `pages/`, same syntax as `include`, for example `api/**\/*.md`.
*/
match: string
/**
* @zh 索引里这条链接的标题
* @en Title of the index link
*/
title: string
/**
* @zh 链接路径。以 `/` 结尾时保持目录地址(如 `/api/`);否则像普通条目一样补上 `.md`。
* @en Link path. A trailing slash stays a directory URL (for example `/api/`). Other paths gain a `.md` suffix, like normal entries.
*/
href: string
/**
* @zh 可选描述,写在链接后面
* @en Optional description appended after the link
*/
description?: string
/**
* @zh 可选分组标题。默认由 `href` 推断:`/api/` 为 `Api`;设置 `locales: ['zh']` 时 `/zh/api/` 为 `Api (zh)`。
* @en Optional section heading. Defaults from `href`: `/api/` becomes `Api`, and `/zh/api/` becomes `Api (zh)` when `locales` includes `zh`.
*/
section?: string
}
/**
* Pages lifted to the front of `llms.txt`.
*/
export interface LlmsFeatured {
/**
* @zh 置顶分组的标题
* @en Heading for the leading section
* @default 'Docs'
*/
title?: string
/**
* @zh 按此顺序置顶的站点路径,例如 `/guide/getting-started`。这些页面不会在后面的分组里再次出现。
* @en Site paths pinned first, in this order, for example `/guide/getting-started`. They are not repeated in later sections.
*/
paths: string[]
}
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> {
/** Enable development tools and the page inspection bridge. */
devtools?: boolean
/**
* @en Site **info** config. This affects info displayed on the site, and is independent of themes.
* @zh 站点**信息**配置,这部分内容面向站点展示,且在不同主题中也是通用的格式
* @see [站点配置 | Valaxy](https://valaxy.site/zh/guide/config#site-config)
* @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 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:
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',
},
],
},
})Author Info
More fields can be found in the type definitions above or via editor IntelliSense.
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
author: {
name: 'Your Name',
/**
* Your avatar
*/
avatar: 'https://xxx',
intro: 'A brief introduction'
}
})Timezone
If you use CI/CD for building and deployment, the remote machine may be in a different timezone. You can set the timezone.
This will format the time using the specified timezone by default and set the process.env.TZ variable.
If you’re hosting on other platforms, you may need to add environment variables on the corresponding platform.
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
timezone: 'Asia/Shanghai'
})Post Sorting
Set siteConfig.orderBy to control the sorting method of the article list.
date: Sort by the date of the article (default)updated: Sort by the last update time of the article
When lastUpdated is enabled, articles without updated use the file’s latest Git commit time, falling back to its filesystem modification time when Git history is unavailable. Articles without date use the file’s earliest Git commit time when available. Explicit frontmatter dates are preserved.
Git dates require complete commit history. When deploying with GitHub Actions, set fetch-depth: 0 for actions/checkout; shallow clones cannot recover article dates outside the fetched history. Uncommitted local edits do not change Git dates.
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
orderBy: 'updated',
})Default Frontmatter
Set the default Frontmatter for all posts.
For example:
Set
time_warning: falseso that all articles won’t show reading time warnings.
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
/**
* Default Frontmatter
*/
frontmatter: {
time_warning: false,
}
})Social Icons
social also supplies the author’s JSON-LD sameAs. Only valid HTTP(S) URLs are retained. With siteConfig.url: 'https://example.com/blog/', ./about resolves to https://example.com/blog/about, and /about resolves to https://example.com/about. Empty values and duplicates are removed, preserving query strings and fragments. Mail links, common feed files (such as atom.xml, feed.json, .atom, and .rss), and the site feeds configured by feed.name are excluded. Set sameAs: false for group invitations, custom subscriptions, or other navigation links that do not identify the author. Social navigation is unaffected. Filtering does not guess from platform domains, icons, or account names.
export interface SocialLink {
/**
* The title of your link
*/
name: string
link: string
sameAs?: boolean
/**
* Icon name
* https://icones.js.org/
*/
icon: string
color: string
}Example:
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
social: [
{
name: 'RSS',
link: '/atom.xml',
icon: 'i-ri-rss-line',
color: 'orange',
},
{
name: 'QQ 群 1050458482',
sameAs: false,
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
At the end of each post, show sponsor information.
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.
interface SponsorOption {
enable: boolean
title: string
methods: {
name: string
url: string
color: string
icon: string
}[]
}Or you can set for each post using front matter:
---
title: xxx
sponsor: false
---Reading Statistics
Enable reading statistics to display word count and reading time at the beginning of each post.
Requires theme support, i.e., displaying
wordCountandreadingTimefields fromfrontmatter.
wordCount: Word countreadingTime: Reading time (minutes)- You can set reading speed for different languages. Default:
cn300 words/min,en200 words/min.
- You can set reading speed for different languages. Default:
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
statistics: {
enable: true,
readTime: {
/**
* Reading speed
*/
speed: {
cn: 300,
en: 200,
},
},
}
})Code Height Limit
You can set the height limit for each article.
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.
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
// ...
codeHeightLimit: 300,
})You can also set it separately in the Front Matter of the article:
---
codeHeightLimit: 300
---Example can refer to Code Height Limit.
Content Encryption
Firstly, enable encryption in site.config.ts.
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
// ...
encrypt: {
enable: true,
}
})- encrypt the entire article
Set password in the Front Matter of the article:
---
password: your_password
password_hint: Custom Password Hint
---- encrypt partial content
TIP
If you set password in Front Matter, partial encryption will be ignored.
Wrap content to be encrypted in <!-- valaxy-encrypt-start:your_password --><!-- valaxy-encrypt-end -->.
Examples can be found in Partial Content Encryption。
Client Redirects
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:
export default defineSiteConfig({
redirects: {
useVueRouter: true,
rules: [
{
from: ['/foo', '/bar'],
to: '/about',
},
{
from: '/v1/about',
to: '/about',
},
]
},
})/foo, /bar, /v1/about these routes will be redirected to /about。
You can also set it in the Front Matter:
<!-- pages/posts/redirect.md -->
---
from:
- /redirect/old1
- /redirect/old2
---<!-- pages/posts/redirect.md -->
---
from: /v1/redirect
---/redirect/old1, /redirect/old2, /v1/redirect these routes will be redirected to /posts/redirect。
TIP
When building SSG, if useVueRouter is false, an html file will be generated for each original route
Image Preview (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
import { defineSiteConfig } from 'valaxy'
export default defineSiteConfig({
mediumZoom: { enable: true }
})In addition, you can also enable it in a certain article independently.
---
title: Test Medium Zoom
medium_zoom: true
---Lazyload Vanilla Lazyload
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.
export default defineSiteConfig({
vanillaLazyload: {
// Disabled by default
enable: true,
}
})More Configurations
For more details, see types/config.ts.
packages/valaxy/types/config.ts SiteConfig
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 './addon'
import type { DefaultTheme } from './default-theme'
import type { PostFrontMatter } from './frontmatter'
import type { ExcerptType } from './frontmatter/post'
import type { FuseListItem } from './node'
import './default-theme'
/**
* @zh 社交链接
*/
export interface SocialLink {
/**
* The title of your link
*/
name: string
link: string
/**
* @description:en-US Set false for navigation links that do not identify the author (e.g. groups or custom subscriptions).
* @description:zh-CN 非作者身份主页(如群聊、自定义订阅入口)设为 false,仅从 JSON-LD sameAs 中排除,不影响导航。
*/
sameAs?: boolean
/**
* 图标名称
* 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
/**
* @description:en-US Public email. Omitted from RSS and JSON-LD when empty. Valaxy does not fill this in.
* @description:zh-CN 公开邮箱。留空时不会写入 RSS 和 JSON-LD,框架不会代填。
*/
email: string
/**
* @description:en-US Author URL. Omitted from RSS and JSON-LD when empty. Valaxy does not fill this in.
* @description:zh-CN 作者链接。留空时不会写入 RSS 和 JSON-LD,框架不会代填。
*/
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
}
/**
* order posts by 'date' or 'updated'
*
* - date: 按创建时间排序
* - updated: 按最后更新时间排序
*
* 当开启 `lastUpdated` 时,`updated` 会按照文件的更新时间自动赋值
*
* @default 'date'
*/
orderBy: 'date' | 'updated'
/**
* show last updated time by git/mtime
* @default false
*/
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
* - local: Local Search by MiniSearch
*/
provider: 'algolia' | 'engine' | 'fuse' | 'local'
}
/**
*
* fuse search
* @see https://fusejs.io/
* @description 本地搜索
* Please set search.provider to 'fuse'
*/
fuse: {
/**
* @default 'valaxy-fuse-list.json'
* @description 搜索结果列表数据所在路径
*/
dataPath: string
/**
* Glob pattern (tinyglobby) to match Fuse List Data
* @default `pages\/**\/*.md`
* ```ts
* await glob(`${userRoot}/pages/posts/**\/*.md`)
* ```
*/
pattern?: 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']
}
}
/**
* Excerpt configuration
* @description:en-US Global excerpt settings for posts
* @description:zh-CN 全局摘要配置
*/
excerpt: {
/**
* @description:en-US Default excerpt render type for `<!-- more -->` and auto-generated excerpts.
* Can be overridden per-post via frontmatter `excerpt_type`.
* Does not apply when frontmatter `excerpt` is set manually (used as-is).
* @description:zh-CN `<!-- more -->` 及自动摘要的默认渲染类型,可通过 frontmatter `excerpt_type` 逐篇覆盖。
* 当 frontmatter 手动指定 `excerpt` 时不生效(直接使用原始字符串)。
* @default 'html'
*/
type: ExcerptType
/**
* @description:en-US Auto-generate excerpt from post content when no manual excerpt is provided
* @description:zh-CN 当没有手动指定摘要时,自动从文章内容截取摘要
* @default false
*/
auto: boolean
/**
* @description:en-US Maximum length of auto-generated excerpt (in characters)
* @description:zh-CN 自动摘要的最大长度(字符数)
* @default 200
*/
length: number
}
/**
* Which source files are published.
* @description:en-US Controls drafts, underscore paths, and README pages. Development still previews `draft: true`.
* @description:zh-CN 控制草稿、下划线路径和 README 页面。开发模式仍会预览 `draft: true`。
*/
publishing: {
/**
* @description:en-US Include `draft: true` pages in production HTML, the sitemap, RSS, and llms output.
* @description:zh-CN 在生产 HTML、sitemap、RSS 和 llms 中包含 `draft: true` 的页面。
* @default false
*/
drafts: boolean
/**
* @description:en-US Publish files and directories under `pages/` whose names start with `_`, including `pages/_drafts`.
* @description:zh-CN 发布 `pages/` 下名称以 `_` 开头的文件和目录,包括 `pages/_drafts`。
* @default false
*/
underscore: boolean
/**
* @description:en-US Publish `README.md` files under `pages/` as routes.
* @description:zh-CN 将 `pages/` 下的 `README.md` 发布为路由。
* @default false
*/
readme: boolean
}
/**
* 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
}
/**
* 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:en-US Global encryption password, read from env `VALAXY_ENCRYPT_PASSWORD`.
* When a post has `encrypt: true` in frontmatter but no `password`, this is used.
* Do NOT put passwords in config files — use `.env` or CI secrets.
* @description:zh-CN 全局加密密码,从环境变量 `VALAXY_ENCRYPT_PASSWORD` 读取。
* 当文章 frontmatter 设置了 `encrypt: true` 但未指定 `password` 时使用。
* 请勿在配置文件中设置密码——请使用 `.env` 文件或 CI secrets。
*/
// password is read from process.env.VALAXY_ENCRYPT_PASSWORD at build time
}
/**
* @description:en-US Limit the height of the code block in px
* @description:zh-CN 限制代码块的高度,单位是 px
*/
codeHeightLimit?: number
/**
* @zh llms.txt 及原始 Markdown 文件输出
* @en llms.txt and raw Markdown file output
* @see https://llmstxt.org/
*/
llms: {
/**
* @zh 是否开启 llms.txt 和 .md 原始文件输出
* @en Enable llms.txt and raw .md file output
* @default false
*/
enable: boolean
/**
* @zh 是否生成 llms-full.txt(包含所有文章完整内容)
* @en Whether to generate llms-full.txt (with all post content inlined)
* @default true
*/
fullText: boolean
/**
* @zh 是否为每篇文章生成独立的 .md 文件(可通过 /posts/xxx.md 访问)
* @en Whether to generate individual .md files for each post (accessible via /posts/xxx.md)
* @default true
*/
files: boolean
/**
* @zh 自定义提示词(添加到 llms.txt blockquote 部分)
* @en Custom prompt text (added to the llms.txt blockquote section)
* @default ''
*/
prompt: string
/**
* @zh 要包含的 markdown 文件 glob 模式(相对于 pages/ 目录)。
* 默认为 `['posts\/**\/*.md']` 仅包含 posts。
* 设为 `['**\/*.md']` 可包含所有 pages 下的 markdown 文件。
* 也可以指定多个目录,如 `['posts\/**\/*.md', 'guide\/**\/*.md']`。
* @en Glob patterns for markdown files to include (relative to pages/ directory).
* Defaults to `['posts\/**\/*.md']` to only include posts.
* Set to `['**\/*.md']` to include all markdown files under pages/.
* You can also specify multiple directories, e.g. `['posts\/**\/*.md', 'guide\/**\/*.md']`.
* @default ['posts\/**\/*.md']
*/
include?: string[]
/**
* @zh 从 `llms.txt` 和 `llms-full.txt` 排除的 glob(相对于 `pages/`,语法与 `include` 相同)。
* `files` 仍会写出对应的 `.md` 文件。
* 不设置时不做排除,因此只开启 `enable` 的站点保持原有输出。
* @en Glob patterns, relative to `pages/` and using the same syntax as `include`, omitted from `llms.txt` and `llms-full.txt`.
* Individual `.md` files are still written when `files` is true.
* Unset means nothing is excluded, so sites that only enable llms keep their previous output.
*/
exclude?: string[]
/**
* @zh `llms.txt` 分组标题的顺序,例如 `['Guide', 'Posts']`。未列出的分组按原顺序排在后面。匹配时忽略大小写。
* @en Section headings in `llms.txt`, first to last, for example `['Guide', 'Posts']`. Headings you omit keep their original order after these. Matching ignores case.
*/
sectionOrder?: string[]
/**
* @zh 作为语言而不是栏目的 URL 前缀,例如 `['zh']`。
* `/zh/guide/why` 会归入 `Guide (zh)`,而不是把所有中文页放进一个 `Zh` 分组。
* 不设置时仍用路径的第一段作为分组名。
* @en URL prefixes that are languages rather than sections, for example `['zh']`.
* `/zh/guide/why` is grouped as `Guide (zh)` instead of placing every Chinese page in one `Zh` section.
* Unset keeps the first path segment as the section name.
*/
locales?: string[]
/**
* @zh 在 `llms.txt` 开头置顶的页面。
* @en Pages pinned to the start of `llms.txt`.
*/
featured?: LlmsFeatured
/**
* @zh 把一批页面折叠成 `llms.txt` 中的一条链接,并从不写入 `llms-full.txt`。
* 对应的 `.md` 文件仍会生成。适合把 API 参考收成一个 `/api/` 入口。
* @en Replace a set of pages with one `llms.txt` link and omit them from `llms-full.txt`.
* The `.md` files are still generated. Use this to collapse an API reference to a single `/api/` entry.
*/
collapse?: LlmsCollapse[]
}
/**
* @description:en-US client redirect rules
* @description:zh-CN 客户端重定向规则
*/
redirects?: {
useVueRouter?: boolean
rules?: RedirectRule[]
}
}
/**
* One `llms.txt` link that stands in for every page matching `match`.
*/
export interface LlmsCollapse {
/**
* @zh 相对于 `pages/` 的 glob,语法与 `include` 相同,例如 `api/**\/*.md`。
* @en Glob relative to `pages/`, same syntax as `include`, for example `api/**\/*.md`.
*/
match: string
/**
* @zh 索引里这条链接的标题
* @en Title of the index link
*/
title: string
/**
* @zh 链接路径。以 `/` 结尾时保持目录地址(如 `/api/`);否则像普通条目一样补上 `.md`。
* @en Link path. A trailing slash stays a directory URL (for example `/api/`). Other paths gain a `.md` suffix, like normal entries.
*/
href: string
/**
* @zh 可选描述,写在链接后面
* @en Optional description appended after the link
*/
description?: string
/**
* @zh 可选分组标题。默认由 `href` 推断:`/api/` 为 `Api`;设置 `locales: ['zh']` 时 `/zh/api/` 为 `Api (zh)`。
* @en Optional section heading. Defaults from `href`: `/api/` becomes `Api`, and `/zh/api/` becomes `Api (zh)` when `locales` includes `zh`.
*/
section?: string
}
/**
* Pages lifted to the front of `llms.txt`.
*/
export interface LlmsFeatured {
/**
* @zh 置顶分组的标题
* @en Heading for the leading section
* @default 'Docs'
*/
title?: string
/**
* @zh 按此顺序置顶的站点路径,例如 `/guide/getting-started`。这些页面不会在后面的分组里再次出现。
* @en Site paths pinned first, in this order, for example `/guide/getting-started`. They are not repeated in later sections.
*/
paths: string[]
}
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> {
/** Enable development tools and the page inspection bridge. */
devtools?: boolean
/**
* @en Site **info** config. This affects info displayed on the site, and is independent of themes.
* @zh 站点**信息**配置,这部分内容面向站点展示,且在不同主题中也是通用的格式
* @see [站点配置 | Valaxy](https://valaxy.site/zh/guide/config#site-config)
* @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>>Theme Config
Please refer to Using Themes and the theme you are using to configure it.
Extended Config
For more advanced configurations, see Extended Config.
To Be Continued.