跳至主要內容

项目分析

源码

项目分析

当前使用版本

{
  "name": "linczero-websize",
  "version": "1.0.0",
  "description": "LincZero WebSize",
  "license": "LGPL-2.1",
  "type": "module",
  "scripts": {
    "docs:build": "vuepress build src",
    "docs:clean-dev": "vuepress dev src --clean-cache",
    "docs:dev": "vuepress dev src",
    "docs:update-package": "pnpm dlx vp-update"
  },
  "devDependencies": {
    "@vuepress/client": "2.0.0-beta.67",
    "vue": "^3.3.4",
    "vuepress": "2.0.0-beta.67",
    "vuepress-theme-hope": "2.0.0-beta.237"
  }
}

结构分析

路径分析

  • /src/
    • .vuepress/
      • config.ts； 第一批加载项，全局配置，使用 "./theme.js"
      • theme.ts； 第二批加载项，主题配置，使用 "./navbar/" 和 "./sidebar/"
      • navbar/； 第三批加载项，存储导航栏
      • sidebar/； 第三批加载项，存储侧边栏
      • public/； 共有资源，图标图片等
      • styles/； 自定义样式等
      • .cache/； (gitignore)
      • .temp/； (gitignore)
      • dist； (gitignore)
    • README.md
    • ... (other md)
  • /.gitignore
  • /package.json
  • /pnpm-lock.yaml

文件分析

config.ts

该文件的大部分配置可以查这个页面：https://vuejs.press/zh/reference/config.html

简化目录版

import { defineUserConfig } from "vuepress"; // 从 "vuepress" 导入定义用户配置的方法
import theme from "./theme.js"; // 从当前目录下的 "theme.js" 文件导入主题

// 使用定义的用户配置导出一个默认的配置对象
export default defineUserConfig({
  base: "/", // 设置基本目录路径

  locales: {}, // 设置多语言配置

  theme, // 使用导入的主题
});

完整版

import { defineUserConfig } from "vuepress"; // 从 "vuepress" 导入定义用户配置的方法
import theme from "./theme.js"; // 从当前目录下的 "theme.js" 文件导入主题

// 使用定义的用户配置导出一个默认的配置对象
export default defineUserConfig({
  base: "/", // 设置基本目录路径

  locales: { // 设置多语言配置
    "/": {
      lang: "en-US", // 设定语言为美式英语
      title: "Docs Demo", // 设定标题
      description: "A docs demo for vuepress-theme-hope", // 设定描述
    },
    "/zh/": {
      lang: "zh-CN",
      title: "文档演示",
      description: "vuepress-theme-hope 的文档演示",
    },
  },

  theme, // 使用导入的主题

  // 使网页成为PWA
  // shouldPrefetch: false, // 是否预获取
});

theme.ts

该文件的大部分配置可以查这两个页面：

  • 默认主题：https://vuejs.press/zh/reference/default-theme/config.html
  • Hope独有：https://theme-hope.vuejs.press/zh/config/theme/layout.html

简化目录版

// 导出默认的主题配置
export default hopeTheme({
  // 信息类
  hostname: "http://192.168.0.101:8080/", //设置网站主机名
  author: { // 设置作者信息
    name: "LincZero", // 作者姓名
    url: "https://github.com/LincZero/", // 作者网站链接
  },
  repo: "LincZero/LincZero-Vuepress", // 仓库地址
  iconAssets: "fontawesome-with-brands", // 使用 FontAwesome 图标库
  logo: "/logo.svg", // 设置 logo 路径

  // 配置类
  docsDir: "src", // 存放文档的目录
  locales: {}, // 多语言设置 ?
  encrypt: {}, // 加密配置
  plugins: { // 插件配置
    comment: {}, // 评论系统的配置
    mdEnhance: {}, // 扩展 Markdown 的功能
    pwa: {} // PWA 的设置
});

完整版

import { hopeTheme } from "vuepress-theme-hope"; // 从 "vuepress-theme-hope" 导入 hope 主题
import { enNavbar, zhNavbar } from "./navbar/index.js"; // 导入英语和中文导航栏配置
import { enSidebar, zhSidebar } from "./sidebar/index.js"; // 导入英语和中文侧边栏配置

// 导出默认的主题配置
export default hopeTheme({
  hostname: "https://vuepress-theme-hope-docs-demo.netlify.app", //设置主机名

  author: { // 设置作者信息
    name: "Mr.Hope", // 作者姓名
    url: "https://mister-hope.com", // 作者网站链接
  },

  iconAssets: "fontawesome-with-brands", // 使用 FontAwesome 图标库

  logo: "/logo.svg", // 设置 logo 路径

  repo: "vuepress-theme-hope/vuepress-theme-hope", // 仓库地址

  docsDir: "src", // 存放文档的目录
  
  locales: {
    "/": { // 英文
      navbar: enNavbar, // 导航栏
      sidebar: enSidebar, // 侧边栏
      footer: "Default footer", // 页脚文本
      displayFooter: true, // 显示页脚
      metaLocales: {
        editLink: "Edit this page on GitHub", // Github上编辑该页的文本
      },
    },

    "/zh/": {
      navbar: zhNavbar,
      sidebar: zhSidebar,
      footer: "默认页脚",
      displayFooter: true,
      metaLocales: {
        editLink: "在 GitHub 上编辑此页",
      },
    },
  },

  encrypt: { // 加密配置
    config: {
      "/demo/encrypt.html": ["1234"], // "/demo/encrypt.html" 需要使用 "1234" 进行解密
      "/zh/demo/encrypt.html": ["1234"], // "/zh/demo/encrypt.html" 需要使用 "1234" 进行解密
    },
  },

  plugins: { // 插件配置
    comment: { // 评论系统的配置
      provider: "Giscus", // 评论系统提供商
      repo: "vuepress-theme-hope/giscus-discussions", // 用于存放讨论的仓库
      repoId: "R_kgDOG_Pt2A", // 仓库 ID
      category: "Announcements", // 类别
      categoryId: "DIC_kwDOG_Pt2M4COD69", // 类别的 ID
    },

    mdEnhance: { // 扩展 Markdown 的功能
      align: true, // 对齐
      attrs: true, // 属性
      chart: true, // 图表
      codetabs: true, // 代码标签
      demo: true, // 演示
      echarts: true, // Echarts 图表工具
      figure: true, // Figure 图表工具
      flowchart: true, // 流程图
      gfm: true, // GitHub 风格的 Markdown
      imgLazyload: true, // 懒加载图片
      imgSize: true, // 图片大小
      include: true, // 包括
      katex: true, // Katex 数学公式渲染工具
      mark: true, // 标记
      mermaid: true, // Mermaid 图表工具
      playground: { // 在线代码演示设置
        presets: ["ts", "vue"], // 预设
      },
      presentation: ["highlight", "math", "search", "notes", "zoom"], // 展示工具
      stylize: [ // 样式化工具
        {
          matcher: "Recommended", // 匹配器
          replacer: ({ tag }) => { // 替换器
            if (tag === "em") // 如果标签为 "em"
              return {
                tag: "Badge", // 替换为 "Badge" 标签
                attrs: { type: "tip" }, // 设置属性
                content: "Recommended", // 设置内容
              };
          },
        },
      ],
      sub: true, // 子项
      sup: true, // 上标
      tabs: true, // 标签
      vPre: true, // Vue 预处理
      vuePlayground: true, // Vue 种植场
    },

    // PWA 的设置
    // pwa: {
    //   favicon: "/favicon.ico",
    //   cacheHTML: true,
    //   cachePic: true,
    //   appendBase: true,
    //   apple: {
    //     icon: "/assets/icon/apple-icon-152.png",
    //     statusBarColor: "black",
    //   },
    //   msTile: {
    //     image: "/assets/icon/ms-icon-144.png",
    //     color: "#ffffff",
    //   },
    //   manifest: {
    //     icons: [
    //       {
    //         src: "/assets/icon/chrome-mask-512.png",
    //         sizes: "512x512",
    //         purpose: "maskable",
    //         type: "image/png",
    //       },
    //       {
    //         src: "/assets/icon/chrome-mask-192.png",
    //         sizes: "192x192",
    //         purpose: "maskable",
    //         type: "image/png",
    //       },
    //       {
    //         src: "/assets/icon/chrome-512.png",
    //         sizes: "512x512",
    //         type: "image/png",
    //       },
    //       {
    //         src: "/assets/icon/chrome-192.png",
    //         sizes: "192x192",
    //         type: "image/png",
    //       },
    //     ],
    //     shortcuts: [
    //       {
    //         name: "Demo",
    //         short_name: "Demo",
    //         url: "/demo/",
    //         icons: [
    //           {
    //             src: "/assets/icon/guide-maskable.png",
    //             sizes: "192x192",
    //             purpose: "maskable",
    //             type: "image/png",
    //           },
    //         ],
    //       },
    //     ],
    //   },
    // },
});

解析顺序

有的地方是不是重复了？还是说是不同的、有区别的？我不太懂。

例如config.ts和theme.ts都有locales字段来设置多语言 (en和zh两种语言)？

然后这两个文件，一般哪个是“更大”的配置，哪个是“较小”的配置，会先解析哪个先

这是一个很好的问题。在许多项目中，你会看到配置信息散布在多个不同的文件和位置。这主要是因为每个文件都有各自的责任和用途。

config.ts 和 theme.ts 都有 locales 字段是因为 Vuepress 的 locales 是多层级的。

  1. 在 config.ts 文件中， locales 字段设置的是全局层次的语言配置，例如整个网站的语言、标题、描述等。
  2. 在 theme.ts 文件中，locales 字段则是在 主题层次做语言配置，例如主题的导航栏、侧边栏、页脚等按照语言的不同来设置。

一个简单的理解方式是 config.ts 提供了全局（"更大"）的配置，theme.ts 对特定主题（"较小"）的配置进行了更为细致的定义和调整。虽然它们看起来可能有一些重复，但这种设计让配置更加灵活，可以在不同的层级进行不同的定制。

解析顺序上，通常先解析 config.ts 的全局配置，然后 theme.ts 的主题配置会覆盖或添加到全局配置中。所以，如果你在 theme.ts 中设置了与 config.ts 中同名的字段，theme.ts 中的设置将会生效。

功能分析

Hope主题将主题配置分成了个六维度：

  1. 基本
  2. 功能
  3. 布局
  4. 外观
  5. 多语言
  6. 行为
链接到当前文件 0
没有文件链接到当前文件