docs: update how to use site.config.ts

2023-01-23 05:40:26 +08:00 · 2023-01-23 05:40:26 +08:00 · 3e77ed81ed
parent 11f0e86236
commit 3e77ed81ed
8 changed files with 234 additions and 129 deletions
--- a/demo/yun/valaxy.config.ts
+++ b/demo/yun/valaxy.config.ts
@ -11,7 +11,8 @@ const safelist = [
 ]

 export default defineValaxyConfig<ThemeConfig>({
-  // site config see site.config.ts
+  // site config see site.config.ts or write in siteConfig
+  // siteConfig: {},

  theme: 'yun',
  themeConfig: {
--- a/docs/pages/guide/config.md
+++ b/docs/pages/guide/config.md
@ -1,106 +0,0 @@
---
-title: Config
-title_zh-CN: 配置
-categories:
-  - Guide
-end: false
---
-
-## 社交图标
-
-```ts
-export interface SocialLink {
-  /**
-   * The title of your link
-   */
-  name: string
-  link: string
-  /**
-   * 图标名称
-   * https://icones.js.org/
-   */
-  icon: string
-  color: string
-}
-```
-
-示例：
-
-```ts
-// valaxy.config.ts
-import { defineSite } from 'valaxy'
-export default defineConfig({
-  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
-// valaxy.config.ts
-import { defineSite } from 'valaxy'
-export default defineConfig({
-  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` 属性控制全局是否开启。
-
-```ts
-interface SponsorOption {
-  enable: boolean
-  title: string
-  methods: {
-    name: string
-    url: string
-    color: string
-    icon: string
-  }[]
-}
-```
-
-或为某篇文章的 Front Matter 单独设置：
-
-```md
---
-title: xxx
-sponsor: false
---
-```
--- a/docs/pages/guide/config/index.md
+++ b/docs/pages/guide/config/index.md
@ -0,0 +1,207 @@
+---
+title: Config
+title_zh-CN: 配置
+categories:
+  - Config
+end: false
+top: 10
+---
+
+## 配置说明
+
+为了便于配置，Valaxy 将配置分为了三种。
+
+`valaxy.config.ts` 是配置的主入口，。
+
+- `siteConfig`: 站点**信息**配置，这部分内容面向站点展示且在任何主题也是通用的格式
+- `themeConfig`: 主题配置，这部分内容仅在特定主题生效
+- `runtimeConfig`: 运行时的配置（由 Valaxy 自动生成），用户无需配置
+- 其他 Valaxy 通用配置内容（如需要在 Node 端处理的配置）
+
+譬如：
+
+```ts
+// valaxy.config.ts
+import { defineValaxyConfig } from 'valaxy'
+import type { ThemeConfig } from 'valaxy-theme-yun'
+import { addonComponents } from 'valaxy-addon-components'
+import Inspect from 'vite-plugin-inspect'
+
+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://github.com/antfu/vite-plugin-inspect
+    // Visit http://localhost:3333/__inspect/ to see the inspector
+    plugins: [Inspect()],
+  },
+
+  unocss: {
+    safelist,
+  },
+
+  addons: [
+    addonComponents()
+  ],
+})
+```
+
+## Site Config
+
+站点**信息**配置，这部分内容面向站点展示且在任何主题也是通用的格式。
+
+你也可以将其写在 `site.config.ts` 中。
+
+譬如：
+
+```ts
+// site.config.ts
+import { defineSiteConfig } from 'valaxy'
+
+export default defineSiteConfig({
+  lang: 'zh-CN',
+  title: 'Valaxy Theme Yun',
+  url: 'https://valaxy.yyj.moe/',
+  author: {
+    avatar: 'https://www.yunyoujun.cn/images/avatar.jpg',
+    name: '云游君',
+  },
+  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',
+      },
+    ],
+  },
+})
+```
+
+### 社交图标
+
+```ts
+export interface SocialLink {
+  /**
+   * The title of your link
+   */
+  name: string
+  link: string
+  /**
+   * 图标名称
+   * https://icones.js.org/
+   */
+  icon: string
+  color: string
+}
+```
+
+示例：
+
+```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` 属性控制全局是否开启。
+
+```ts
+interface SponsorOption {
+  enable: boolean
+  title: string
+  methods: {
+    name: string
+    url: string
+    color: string
+    icon: string
+  }[]
+}
+```
+
+或为某篇文章的 Front Matter 单独设置：
+
+```md
+---
+title: xxx
+sponsor: false
+---
+```
+
+## Theme Config
+
+参照 [使用主题](/themes/use) 及您所使用的主题文档进行配置。
--- a/docs/pages/guide/features.md
+++ b/docs/pages/guide/features.md
@ -151,8 +151,8 @@ Katex is enabled by default.

 ```ts
 // valaxy.config.ts
-import { defineConfig } from 'valaxy'
-export default defineConfig({
+import { defineValaxyConfig } from 'valaxy'
+export default defineValaxyConfig({
  features: {
    // disable katex
    katex: false
--- a/docs/valaxy.config.ts
+++ b/docs/valaxy.config.ts
@ -11,14 +11,16 @@ const safelist = [
 ]

 export default defineValaxyConfig<PressTheme.Config>({
-  title: 'Valaxy',
-  url: 'https://valaxy.site',
-  description: 'Valaxy Site Docs',
+  siteConfig: {
+    title: 'Valaxy',
+    url: 'https://valaxy.site',
+    description: 'Valaxy Site Docs',
+  },

  theme: 'press',
  themeConfig: {
    logo: '/favicon.svg',
-    sidebar: ['Getting Started', 'Guide', 'Migration', 'built-ins', 'Third', 'Custom', 'Theme', 'Addon', 'Dev'],
+    sidebar: ['Getting Started', 'Guide', 'Config', 'Migration', 'built-ins', 'Third', 'Custom', 'Theme', 'Addon', 'Dev'],
    socialLinks: [
      { icon: 'i-ri-github-line', link: 'https://github.com/YunYouJun/valaxy' },
    ],
--- a/packages/valaxy/node/config/index.ts
+++ b/packages/valaxy/node/config/index.ts
@ -1,7 +1,7 @@
 import type { VitePluginConfig as UnoCssConfig } from 'unocss/vite'
 import type { Awaitable } from '@antfu/utils'
 import type { SiteConfig, UserSiteConfig } from '../../types'
-import type { UserValaxyNodeConfig } from '../types'
+import type { UserValaxyNodeConfig, ValaxyNodeConfig } from '../types'

 export * from './addon'

@ -76,15 +76,12 @@ export const defaultSiteConfig: SiteConfig = {
  cdn: {
    prefix: 'https://unpkg.com/',
  },
-
-  features: {
-    katex: true,
-  },
 }

-export const defaultValaxyConfig = {
+export const defaultValaxyConfig: ValaxyNodeConfig = {
  ignoreDeadLinks: true,

+  siteConfig: defaultSiteConfig,
  theme: 'yun',
  themeConfig: {
    pkg: {
@ -97,6 +94,10 @@ export const defaultValaxyConfig = {
  //   excerpt: '<!-- more -->',
  // },
  runtimeConfig: { addons: {} },
+
+  features: {
+    katex: true,
+  },
 }

 export type UnoSetup = () => Awaitable<Partial<UnoCssConfig> | undefined>
--- a/packages/valaxy/node/types.ts
+++ b/packages/valaxy/node/types.ts
@ -17,6 +17,16 @@ export type ValaxyConfigFn<ThemeConfig = DefaultThemeConfig> = (options: Resolve
 export type ValaxyConfigExport<ThemeConfig = DefaultThemeConfig> = ValaxyNodeConfig<ThemeConfig> | ValaxyConfigFn<ThemeConfig>

 export interface ValaxyExtendConfig {
+  /**
+   * Markdown Feature
+   */
+  features: {
+    /**
+     * enable katex for global
+     */
+    katex: boolean
+  }
+
  vite?: ViteUserConfig
  vue?: Parameters<typeof Vue>[0]
  components?: Parameters<typeof Components>[0]
--- a/packages/valaxy/types/config.ts
+++ b/packages/valaxy/types/config.ts
@ -134,16 +134,6 @@ export interface SiteConfig {
    enable: boolean
  }

-  /**
-   * Markdown Feature
-   */
-  features: {
-    /**
-     * enable katex for global
-     */
-    katex: boolean
-  }
-
  /**
   * third-party plugin need cdn
   * aplayer, twikoo