外观与导航

本主题扩展自 VitePress 默认主题，保留原生搜索、导航、目录与深浅色切换，在此基础上与博客保持统一的视觉风格。

文件分工

文件	用途
docs/.vitepress/config.mts	站点名称、导航、目录、搜索与中文文案
docs/.vitepress/sidebar.json	可由在线工作台管理的文档目录
docs/.vitepress/theme/style.css	配色、字体、圆角和响应式样式
docs/.vitepress/theme/WikiHome.vue	首页介绍与文档入口
docs/.vitepress/theme/GlobalBackground.vue	全站背景图片与加载回退
docs/.vitepress/theme/wallpaper.ts	随机图片接口与提前加载
docs/.vitepress/theme/Layout.vue	全站页脚
docs/.vitepress/theme/AppearanceSettings.vue	统一外观设置面板
docs/.vitepress/theme/palette.ts	默认偏好与动态配色
docs/public/images/hero.webp	随机图片加载失败时的备用背景

修改标题与导航

在配置文件中修改 title 和 themeConfig.siteTitle。顶栏链接由 nav 控制，左侧文章目录由 sidebar.json 控制，也可以直接在在线工作台的“目录管理”中修改。

nav: [
  { text: '首页', link: '/' },
  { text: '文档', link: '/guide/getting-started' }
]

为侧栏添加一篇文档：

{ text: '使用说明', link: '/guide/example' }

更换全站背景

首页、文档和项目页共用固定的全屏背景。每次刷新或重新进入站点时请求一张随机图片，在站内切换文档时保持当前图片。

访客可以在外观面板的“背景图”开关中选择是否显示壁纸。关闭后使用主题底色，选择会保存到当前浏览器；刷新时不会请求随机图片。背景纹理仍可单独选择。

修改 wallpaper.ts 中的 wallpaperEndpoint 可以更换随机图片接口。接口加载失败或超过 12 秒时，自动使用 docs/public/images/hero.webp，可以替换这张备用图。

背景图使用清晰原图与遮罩来保证文字对比度，没有叠加模糊效果。建议使用横向构图，并在页面预览中检查手机裁切。

调整主题颜色

访客可以点击导航栏的调色板图标，实时更换主题色和配色风格。默认是黑白配色；调整色相或选择彩色预设时会切换为彩色主题。

如果要修改新访客的默认设置，请编辑 palette.ts 中的 defaults。其中 hue 是 0–360 的色相，style 是配色风格，spec 是配色规范。动态配色会同时生成深色与浅色的颜色变量，并应用到链接、按钮、导航和文档面板。

已有访客的个人设置会优先保留。面板右上角的恢复按钮可回到站点默认值。修改后同时检查深色和浅色模式，确保链接、正文与背景具有足够的对比度。

字体

正文沿用博客的字体，并设置系统字体回退。代码使用等宽字体，以便区分标点和字符。

浏览器加载字体期间会先显示回退字体，内容不会因为字体下载而长时间空白。

使用自定义字体

打开“外观设置 → 阅读字体 → 自定义”，填写字体文件的完整链接（WOFF2、WOFF、TTF、OTF），或者当前设备已安装的字体名称。点击“加载并预览”，确认效果后再点击“应用字体”。

字体链接建议使用 HTTPS，并允许跨域访问。字体加载失败时会显示原因，不会覆盖当前的阅读设置；已保存的字体暂时无法加载时，正文会使用系统字体。字体选择仅保存在当前浏览器，代码块保持等宽字体。