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',
      },
    ],
  },
})

作者信息 ​

更多字段可参考上文类型或直接在编辑器提示中查看。

ts
import { defineSiteConfig } from 'valaxy'

export default defineSiteConfig({
  author: {
    name: '你的名字',
    // 你的头像
    avatar: 'https://xxx',
    intro: '个人简介'
  }
})

时区 ​

如果你使用 CI/CD 构建部署，远程机器可能处于其他时区，你可以设置时区。

此时将会默认使用该时区格式化时间，并设置 process.env.TZ 变量。

如果你托管于其他平台，你可能需要在对应平台添加环境变量。

ts
import { defineSiteConfig } from 'valaxy'

export default defineSiteConfig({
  timezone: 'Asia/Shanghai'
})

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: false so 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',
    },
  ]
})

赞助 ​

在每篇文章末尾，展示赞助（打赏）信息。

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 进行图片预览，默认关闭。

Medium Zoom Demo

  • mediumZoom

譬如开启 Medium Zoom：

Valaxy has built-in medium-zoom to preview the pictures, which is disabled by default.

Medium Zoom Demo

  • mediumZoom

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,
  }
})

更多配置 ​

更多详细配置可参见 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>>

主题配置 ​

Theme Config ​

参照 使用主题 及您所使用的主题文档进行配置。

Please refer to Using Themes and the theme you are using to configure it.

扩展配置 ​

更多高阶配置请参见 扩展配置。

Contributors

To Be Continued.
Edit this page on GitHub

Last updated: