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 中的 wordCountreadingTime 字段。

  • 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: