工程目录

my-project/
├── docs/                           ← 网站内容根目录（所有 .md 都会变成网页）
│   ├── .vuepress/                  ← 配置文件和静态资源
│   │   ├── config.ts               ← VuePress 主配置（入口）
│   │   ├── plume.config.ts         ← 主题配置
│   │   ├── navbar.ts               ← 顶部导航
│   │   ├── collections.ts          ← 内容集合定义
│   │   ├── client.ts               ← 客户端增强
│   │   ├── layouts/                ← 自定义布局组件
│   │   │   └── Layout.vue          ← 覆盖主题默认布局，注入自定义插槽内容
│   │   ├── public/                 ← 静态资源（图片、favicon 等，原样复制到网站）
│   │   │   └── plume.svg           ← 站点 logo / 主题图标（可在 config 中引用）
│   │   └── theme/                  ← 自定义主题覆盖
│   │       ├── components/         ← 自定义 Vue 组件
│   │       │   ├── Custom.vue
│   │       │   ├── PinnedCardDeck.vue
│   │       │   └── PostListSidebar.vue
│   │       ├── styles/             ← 自定义 CSS/SCSS 样式
│   │       ├── shim.d.ts           ← TypeScript 类型声明/模块补充
│   │       └── tagSlots.ts         ← 主题标签插槽配置（自定义标签渲染）
│   ├── README.md                   ← 首页
│   ├── blog/                       ← 博客栏目
│   │   ├── blog_documents/         ← 实际文章存放处（Git 子模块）
│   │   │   ├── hardware/           ← 硬件类文章
│   │   │   ├── software/           ← 软件类文章
│   │   │   ├── skill/              ← 技能/方法论文章
│   │   │   └── draft/              ← 半成品草稿（draft: true 隐藏）
│   │   └── essays/                 ← 随笔集合（post 类型）
│   ├── notes/                      ← 笔记栏目（doc 类型集合）
│   │   └── brushless-motor/        ← 无刷电机系列
│   └── demo/                       ← 实验场（语法速查、组件预览）
├── dev-notes/                      ← 开发自用笔记（不参与构建）
│   ├── 主页置顶标签index.html
│   ├── 文章排布标签article.html
│   ├── 赞助打赏标签sponsor.html
│   ├── needtodo.md
│   └── ai_q&a/                     ← AI 问答纪要
├── AGENTS.md                       ← AI 协作约定
├── scripts/                        ← 辅助脚本
│   └── compress-images.mjs         ← 图片压缩脚本
├── package.json                    ← 依赖和脚本命令
├── pnpm-lock.yaml                  ← 锁定依赖版本
└── README.md                       ← 项目说明

• 与官方初始化完毕后的工程目录存在部分差异，其中：

  1.博客文章独立在docs/blog/blog_documents：通过 Git 子模块单独拉取，方便独立管理博客内容，和站点工程解耦。

  2.dev-notes文件夹：里面放置 HTML 草稿文件，主要使用 vibe coding 设计出初稿，方便后续 AI 根据初稿转换为VuePress主题代码；ai_q&a子目录存放与 AI 协作的关键问答纪要。

• 目录结构说明：

  1.docs/.vuepress/layouts目录存放Layout.vue，用于覆盖主题默认布局、向主题插槽注入自定义组件（如自定义侧边栏、顶部卡片）。一般自定义页面级布局组件也可放于该目录

  2.docs/.vuepress/public目录：存放项目公用素材，如图片、图标、二维码、封面图等。其中plume.svg用于站点 logo 或主题图标，可以在config.ts或plume.config.ts中通过/plume.svg引用。

  3.docs/.vuepress/theme/components：存放开发过程中新增的 Vue 组件，比如自定义的置顶卡片、文章列表侧边栏等。

  4.docs/.vuepress/theme/styles：统一放置 CSS 文件，对网站、博客的整体样式进行自定义覆盖。

  5.docs/.vuepress/theme/shim.d.ts：用于 TypeScript 类型补充声明，比如让 TS 识别 .vue 文件、声明非 TS 模块（如图片、CSS 模块）等。

  6.docs/.vuepress/tagSlots.ts：新增用于配置主题的标签插槽（tag slots），即自定义文章标签、分类标签在不同位置如何渲染。（该文件非官方初始化文件）

docs/.vuepress目录下的.ts文件

• config.ts：VuePress 框架的主要配置文件。不支持热更新的配置项通常写在这里。

  • 主要用于配置 VuePress 原生支持的功能标签，比如 search（搜索）、codeHighlighter（代码高亮）、watermark（水印）等。
  • 原代码中对大部分功能做了注释，只做最基础的框架说明，实际可根据注释提示自行启用和配置。
  • 通过该文件搭建出博客整体所需的基础骨架。

• plume.config.ts：Plume 主题的配置文件。此处更新的配置支持热更新。

  • 不要在两个两个配置文件中重复配置相同的项，当前文件的配置项会覆盖 .vuepress/config.ts 文件中的配置。
  • 主要用于配置 Plume 主题支持的自定义功能标签，比如 bulletin（公告板）、encrypt（加密）、copyright（文章版权）等
  • 原代码中对大部分功能做了注释，做最基础的框架说明，实际可根据提示自定义添加。
  • 通过该文件搭建出博客使用主题时可新增的特色骨架。

• navbar.ts和collections.ts：这两个文件是由于在配置plume.config.ts时，navbar和collections两个功能标签的配置较复杂，所以独立出来维护。footer功能标签配置较简单，因此未独立出footer.ts，直接内联在plume.config.ts里。

  • 标准用法有两种：

    // 用法一：直接内联在 plume.config.ts 中
    export default defineThemeConfig({
    navbar: [
        { text: '首页', link: '/' },
        { text: '博客', link: '/blog/' },
    ],
    collections: {
        post: { ... },
        doc: { ... },
    },
    footer: {
        message: 'Power by VuePress',
    },
    })

    // 用法二：拆分到独立文件，再在 plume.config.ts 中导入
    import navbar from './navbar.ts'
    import collections from './collections.ts'
    
    export default defineThemeConfig({
    navbar,       // 等价于 navbar: navbar
    collections,  // 等价于 collections: collections
    footer: {
        message: 'Power by VuePress',
    },
    })

  • 举例：以后 bulletin（公告板）配置也变得复杂，同样可以新建 bulletin.ts，然后按用法二导入。

• client.ts：客户端增强配置文件。在浏览器端 Vue 应用创建后执行，常用于：

  • 注册全局 Vue 组件
  • 导入额外的 CSS/JS
  • 挂载第三方客户端库（如统计、动画）
  • 增强页面交互行为

.vue 单文件组件与 HTML 的区别

.vue 文件是 Vue 3 的“单文件组件”（Single File Component，SFC）。它把一个组件的 HTML、CSS、JS/TS 三种内容打包在一个文件里，组成一个可复用的功能模块。

一个 .vue 文件通常由三个顶层块组成：

<script setup lang="ts"> /* 逻辑层：数据、计算、函数 */ </script>

<template>              /* 视图层：HTML 结构 */ </template>

<style scoped>          /* 样式层：CSS */ </style>

区块	里面写什么	作用	类比
<script setup lang="ts">	TypeScript 逻辑	数据处理、业务逻辑、导入导出	MCU 主程序
<template>	HTML + Vue 指令	页面结构、条件渲染、循环、事件绑定	显示屏界面布局
<style scoped>	CSS 样式	颜色、字体、布局、动画、响应式	外壳喷漆、指示灯颜色

关键点

• <script setup> 是 Vue 3 的组合式 API 写法，setup 表示组件初始化时执行一次，lang="ts" 表示用 TypeScript。
• <template> 看起来像 HTML，但它不是纯 HTML，里面包含 Vue 指令，例如：
  • v-if：条件渲染
  • v-for：循环渲染
  • :href="card.path"：属性绑定
  • :class="[card.cls, { empty: card.empty }]"：动态类名
• <style scoped> 里的 CSS 只作用于当前组件，不会污染其他组件，类似 C 里的 static 关键字。

为什么这样设计？

传统前端会把 HTML、CSS、JS 分成三个文件。Vue 认为一个组件的这三部分本来就是紧密相关的，放到一个 .vue 文件里更像一个完整的“功能模块”，便于维护。

下一页mermaid学习笔记