技术学习博客

Appearance

操作指南 ​

本文档说明如何向博客中添加新的学习资料、图片和业务流程文档。

🎯 导航结构说明 ​

博客采用分类导航结构：

  1. 首页 (/) - 网站首页，包含"开始阅读"按钮
  2. 分类页面 (/分类) - 区分技术和业务两大模块，点击"开始阅读"进入此页面
  3. 技术学习流程 (/技术学习流程/) - 技术学习笔记
  4. 业务流程 (/业务流程/) - 业务流程文档

注意： 业务流程不在首页直接跳转，需要通过分类页面进入。

📁 目录结构 ​

docs/
├── 分类.md                # 内容分类页面（技术和业务两大模块）
├── 技术学习流程/          # 技术学习笔记目录
│   ├── index.md          # 技术学习流程入口页面
│   ├── pic/              # 图片资源目录
│   ├── AQS学习.md        # 各个学习文档
│   ├── hashmap.md
│   └── ...
├── 业务流程/              # 业务流程文档目录
│   ├── index.md          # 业务流程入口页面
│   ├── pic/              # 图片资源目录
│   └── 存货核算流程.md   # 各个业务流程文档
└── index.md              # 网站首页

📝 添加新的学习资料 ​

1. 创建 Markdown 文件 ​

在 docs/技术学习流程/ 目录下创建新的 .md 文件，例如：

bash
docs/技术学习流程/新主题学习.md

2. 编写文档内容 ​

使用标准的 Markdown 语法编写内容：

markdown
# 新主题学习

## 概述

这里是内容...

## 详细说明

更多内容...

3. 配置侧边栏 ​

编辑 .vitepress/config.mts 文件，在 sidebar 配置中添加新文档的链接。

找到对应的分类（如 "Java 基础"、"框架学习" 等），在 items 数组中添加：

typescript
sidebar: {
  '/技术学习流程/': [
    {
      text: 'Java 基础',
      items: [
        // ... 现有文档
        { text: '新主题学习', link: '/技术学习流程/新主题学习' }  // 添加这一行
      ]
    },
    // ... 其他分类
  ]
}

注意：

  • 链接路径不需要 .md 扩展名
  • 路径中的文件名要与实际文件名一致（区分大小写）
  • 如果文件名包含中文，确保路径中的中文与文件名完全一致

4. 更新入口页面（可选） ​

编辑 docs/技术学习流程/index.md，在对应的分类下添加链接：

markdown
### Java 基础
- [新主题学习](/技术学习流程/新主题学习)  <!-- 添加这一行 -->

🖼️ 添加图片 ​

方法一：使用 pic 目录（推荐） ​

  1. 将图片文件放到 pic/ 目录
bash
docs/技术学习流程/pic/图片名称.png
  1. 在 Markdown 文件中引用图片
markdown
![图片描述](pic/图片名称.png)

示例：

markdown
![AQS原理图](pic/2023-04-02-17-16-15.png)

方法二：使用相对路径（子目录中的图片） ​

如果图片在文档所在目录的子目录中：

markdown
![图片描述](pic/子目录/图片名称.png)

示例：

  • 文档位置：docs/技术学习流程/mysql/mysql随笔.md
  • 图片位置：docs/技术学习流程/mysql/pic/图片.png
  • 引用方式：![描述](pic/图片.png)

图片命名建议 ​

  • 使用有意义的文件名，如：2023-04-02-17-16-15.png
  • 避免使用空格，使用 - 或 _ 分隔
  • 建议使用日期时间戳命名，便于管理

注意事项 ​

⚠️ 重要提示：

  1. 不要使用绝对路径，如 /Users/xxx/ 或 file:///，这些路径在构建时会失败
  2. 不要使用 ../ 相对路径，使用相对于文档的路径
  3. 确保图片文件已提交到 Git 仓库
  4. 图片路径区分大小写

📋 添加业务流程文档 ​

1. 创建业务流程文档 ​

在 docs/业务流程/ 目录下创建新的 .md 文件：

bash
docs/业务流程/新业务流程.md

2. 编写业务流程内容 ​

markdown
# 新业务流程

## 流程概述

这里是业务流程说明...

## 详细步骤

1. 步骤一
2. 步骤二

3. 配置侧边栏 ​

编辑 .vitepress/config.mts，在业务流程的侧边栏配置中添加：

typescript
sidebar: {
  '/业务流程/': [
    {
      text: '业务流程',
      items: [
        { text: '存货核算流程', link: '/业务流程/存货核算流程' },
        { text: '新业务流程', link: '/业务流程/新业务流程' }  // 添加这一行
      ]
    }
  ]
}

4. 更新入口页面 ​

编辑 docs/业务流程/index.md，添加新文档的链接：

markdown
## 📋 流程文档

- [存货核算流程](/业务流程/存货核算流程)
- [新业务流程](/业务流程/新业务流程)  <!-- 添加这一行 -->

注意： 新添加的业务流程文档会自动在分类页面的"业务流程"模块中显示，无需额外配置分类页面。

5. 添加业务流程图片 ​

业务流程的图片放在 docs/业务流程/pic/ 目录下：

bash
docs/业务流程/pic/业务流程图片.png

在文档中引用：

markdown
![流程图](pic/业务流程图片.png)

🔧 配置文件说明 ​

.vitepress/config.mts ​

这是 VitePress 的主配置文件，包含：

  • 导航栏配置 (nav): 顶部导航栏
  • 侧边栏配置 (sidebar): 左侧导航栏
  • 主题配置 (themeConfig): 主题相关设置

添加新分类 ​

如果需要在侧边栏添加新的分类，在 sidebar 配置中添加：

typescript
sidebar: {
  '/技术学习流程/': [
    // ... 现有分类
    {
      text: '新分类名称',
      items: [
        { text: '文档1', link: '/技术学习流程/文档1' },
        { text: '文档2', link: '/技术学习流程/文档2' }
      ]
    }
  ]
}

✅ 添加内容后的检查清单 ​

  • [ ] Markdown 文件已创建在正确目录
  • [ ] 文件内容编写完成
  • [ ] 侧边栏配置已更新（.vitepress/config.mts）
  • [ ] 入口页面已更新（index.md）
  • [ ] 图片文件已放到 pic/ 目录
  • [ ] 图片引用路径正确（相对路径，不使用绝对路径）
  • [ ] 运行 npm run build 测试构建是否成功
  • [ ] 运行 npm run dev 本地预览检查显示效果

🐛 常见问题 ​

1. 图片不显示 ​

原因：

  • 图片路径错误（使用了绝对路径）
  • 图片文件不存在
  • 路径大小写不匹配

解决：

  • 检查图片路径是否为相对路径（如 pic/图片.png）
  • 确认图片文件已放在正确的 pic/ 目录
  • 检查文件名大小写是否一致

2. 侧边栏不显示新文档 ​

原因：

  • 侧边栏配置未更新
  • 链接路径错误
  • 文件名与配置不一致

解决：

  • 检查 .vitepress/config.mts 中的配置
  • 确认链接路径与文件名一致（不含 .md 扩展名）
  • 重启开发服务器

3. 构建失败 ​

原因：

  • Markdown 语法错误
  • HTML 标签未转义（如 <K, V> 需要写成 &lt;K, V&gt;）
  • 图片路径错误

解决：

  • 检查 Markdown 文件语法
  • 将 HTML 标签转义（< → &lt;, > → &gt;）
  • 修复图片路径问题

4. 404 错误 ​

原因：

  • 目录缺少 index.md 文件
  • 链接路径错误

解决：

  • 确保目录下有 index.md 作为入口页面
  • 检查链接路径是否正确

📚 示例：完整添加流程 ​

示例：添加一个新的 Java 学习文档 ​

  1. 创建文件

    bash
    docs/技术学习流程/并发编程详解.md

  2. 编写内容

    markdown
    # 并发编程详解

## 概述
这里是并发编程的详细说明...

![并发模型图](pic/并发模型.png)

  3. 添加图片

    bash
    docs/技术学习流程/pic/并发模型.png

  4. 更新侧边栏配置 (.vitepress/config.mts)

    typescript
    {
  text: '并发编程',
  items: [
    { text: '阻塞队列', link: '/技术学习流程/阻塞队列' },
    { text: '并发编程详解', link: '/技术学习流程/并发编程详解' }  // 新增
  ]
}

  5. 更新入口页面 (docs/技术学习流程/index.md)

    markdown
    ### 并发编程
- [并发编程详解](/技术学习流程/并发编程详解)  <!-- 新增 -->

  6. 测试

    bash
    npm run dev  # 本地预览
npm run build  # 测试构建

🚀 快速命令 ​

bash
# 启动开发服务器（预览效果）
npm run dev

# 构建生产版本（测试是否有错误）
npm run build

# 预览构建结果
npm run preview

提示： 添加内容后，建议先运行 npm run dev 本地预览，确认无误后再提交代码。

基于 VitePress 构建

Copyright © 2025