PandaC's Blog

Appearance

④博客使用指南 ​

此为个人博客网搭建与维护全指南-④博客使用指南

大概内容为：

下一篇：博客网原理

内容使用方法 ​

博客文件命名 ​

随着博客文章数量的增加，为了彻底解决 URL 编码乱码、文件名过长导致 404 以及 跨平台兼容性 问题，将博客的文件系统进行了全面重构

核心原则：英核中皮 ​

我们采用 “英文文件名 + 中文标题” 的策略：博客文件名英文！frontmatter写上title中文标签即可

  • 文件名 (Filename)：使用英文（推荐 PascalCase 大驼峰），确保 URL 短且干净，兼容性 100%。
  • 标题 (Frontmatter Title)：在文章头部保留中文标题，确保侧边栏、归档页、浏览器标签页依然显示中文，阅读体验 100%。

为什么这样做？

  • 避坑：中文文件名在浏览器中会被转码为 %E4%B8%AD...，文件名一旦过长（超过 255 字节）会导致服务器（如 Cloudflare）报错 404
  • 专业：英文 URL (/TechStack.html) 看起来比乱码 URL 更简洁、更 Geek
  • 稳定：避免不同操作系统（Windows/Mac/Linux）对中文编码处理不一致导致的文件丢失

操作流程 ​

Step 1: 文件重命名

将 .md 文件名和文件夹名修改为英文

  • ❌ 错误：docs/01.Coding/个人开发技术栈/Web三件套.md
  • ✅ 正确：docs/01.Coding/TechStack/WebBasics.md

Step 2: 确保 Frontmatter 标题

打开重命名后的 Markdown 文件，必须检查头部是否有 title 字段

yaml
---
title: Web三件套基础  <-- 页面显示的中文标题全靠它！
date: 2025-12-20
tags: [HTML, CSS]
---
  • 原理：VitePress 的侧边栏、热力图、归档页都会优先读取这个 title，而不是文件名

Step 3: 更新配置文件

修改文件名后，docs/.vitepress/config.mjs 中的路径配置失效，必须手动更新：

  1. 导航栏 (Nav)：更新 link 路径
  2. 侧边栏 (Sidebar)：更新 scanStartPath (如果改了文件夹名)

Step 4: 修复内部链接

如果文章 A 引用了文章 B，记得修改引用路径：

  • ❌ [点击查看](../开发环境配置/git.md)
  • ✅ [点击查看](../EnvSetup/GitConfig.md)

博客目录命名 ​

名称含义 ​

当前博客网下，共有5个博客内容目录（01.Coding/02.Visuals/03.English/04.Share/05.Growth）和3个展示内容目录（util/blender/game），以及1个私人目录（private）

它们的作用是这样的：

  1. 博客内容目录负责分享博客文章，01是技术工程，02是视觉工坊，03是英语学习，04是资源分享，05是个人成长 对于这些目录，我有一句很好的结论可以用来分类他们：AI 已经从一个“独立技术”变成了一种“基础设施” 所以不用强调“AI”目录，而是把它当成很普通的基础来看待，这样目录分类要达成的目标就很明确： 01.Coding目录即技术工程，用来放与编程相关（环境配置、也包括AI自动化python自动化）、与产品“生产”相关（包括游戏生成、网站建设、个人制作产品的过程、甚至是AIPPT）、与技术理论相关（也包括AI理论） 02.Visuals目录即视觉工坊，用来放视觉产品，包括视频图片也包括AI辅助制图、视频，也有Blender这类3D制作的制作记录 03.English目录即英语学习，用来记录英语学习，没什么好说的，可以加一些其他语言例如中文日语等，不过重点还是英语学习 04.Share目录即资源分享，用来放生活分享、资源工具分享（包括个人制作产品的结果、编程工具分享） 05.Growth目录即个人成长，用来放人文社科类成长收获，人际关系、读书笔记、个人洞察、素材积累等等
  2. 博客展示目录负责利用博客网展现我的技能、想法，util是实用工具目录，game和blender是最终结果展示目录 不过目前还没有什么起色。。。额☺️
  3. 博客私人目录负责记录自己，包括日记、反思、感想等等

命名参考 ​

为了保持命名风格统一（PascalCase），请参考以下字典：

📂 01.Coding (技术工程)

  • 个人开发技术栈 → TechStack
    • Web三件套 → WebBasics.md
    • Vue框架 → VueFramework.md
  • 开发环境配置 → EnvSetup
  • AI编程 → AIProgramming
    • 个人开发 → IndieProjects
  • 网站建设指南 → WebBuilding
    • 博客使用指南 → BlogGuide.md
  • 自动化Work → Automation

📷 02.Visuals (视觉工坊)

  • 后期魔法 → PostProcessing
  • 摄影作品 → Gallery (存放作品集)
    • 25年四季度 → 2025Q4

🔤 03.English (英语学习)

  • 纠错积累 → MistakesCollection
  • 新概念1翻译 → NCE1Translation (NCE = New Concept English)

💎 04.Share (资源分享)

  • 工具软件分享 → SoftwareTools
    • 工作利器 → WorkTools
    • Mermaid教程 → MermaidTutorial.md
  • 网络服务配置 → NetworkConfig

🚀 05.Growth (个人成长)

  • 个人认知 → Insights
  • 名言金句 → Quotes.md

🎮 独立展厅 (Output / Showcase) 放在 docs/ 根目录下，侧重于沉浸式体验和交互，通常在 Frontmatter 设置 layout: page 隐藏侧边栏

🕹️ game (游戏厅)

  • 贪吃蛇 → Snake.md
  • 俄罗斯方块 → Tetris.md

🏛️ blender (3D博物馆)

  • 模型展示 → Models.md (嵌入交互式 3D 模型)
  • 渲染画廊 → Renders.md (静态渲染图作品流)

⚙️ util (实用工具页)

  • 存放 .md 页面文件，专门用于渲染和使用各种 Vue 组件
  • 生产力看板 → TodoList.md (内嵌 <TodoList /> 组件)
  • 热力图演示 → Heatmap.md (内嵌 <ActivityHeatmap /> 组件)
  • 照片墙演示 → PhotoWall.md (内嵌 <PhotoWall /> 组件)

🔒 private (私密树洞)

  • 存放日记、草稿或未完成的想法，配合构建过滤规则
  • 个人日记 → Diary/
  • 年度复盘 → Reviews/
  • 临时草稿 → Drafts/

常用内容插入指南 ​

插入内部链接 (引用兄弟文章) ​

在文章中引用站内的另一篇文章，确保在本地 Typora 写作和网页端查看时都能一键跳转。

核心规范：统一使用“相对路径”

  • 语法：[显示文字](相对路径/文件名.md)

  • 示例：

    同级目录：[查看指南](./BlogGuide.md)

    跨级目录：[阅读感悟](../../05.Growth/Insights/SunkCost.md)

为什么不再建议使用 /docs/ 根路径？

  1. 本地连通性：Typora 等本地编辑器不识别 Web 根目录，使用 /docs/ 会导致本地预览无法跳转
  2. 跨平台稳定性：相对路径仅依赖文件之间的“邻里关系”。只要文件夹结构不变，无论你是在 GitHub 还是 Cloudflare 部署，链接永远有效
  3. 零污染：避免了像 Obsidian 等管理软件因为找不到 /docs 而在仓库里胡乱创建空白文件夹的问题

高效插入技巧 (不要手敲！)

  1. AI 辅助 (推荐)：直接在 Trae/Cursor 中要求 AI “插入指向 XX 文件的相对链接”，让 AI 帮你计算层级
  2. IDE 快捷键：在 VS Code 文件树右键点击目标文件，选择 Copy Relative Path (复制相对路径) 后粘贴即可

插入图片 ​

通常配合 PicGo + 图床（OSS/R2）使用

语法：![图片描述](图片URL)

示例：

![中央公园夕阳](https://r2.pandac-blog.com/2026/01/sunset.jpg)

插入视频 ​

使用博客内置的播放器组件，支持封面图、倍速和 HLS 流媒体

语法：

html
<MyPlayer 
  url="视频链接 (mp4 或 m3u8)" 
  poster="封面图链接 (可选)" 
  title="视频标题" 
/>

插入Mermaid内容 ​

直接用代码画流程图、思维导图、饼图等

语法：使用代码块，语言标记为 mermaid

示例：

```mermaid
graph TD
  A[开始] --> B{判断}
  B -- 是 --> C[执行]
  B -- 否 --> D[结束]
```

提示：Typora 本地可直接预览，推送到网页自动渲染


插入文件 ​

1


文本红蓝字 ​

本地和博客网，已将高亮<mark>&==?==和下标<sub>&~?~改为红字体和蓝字体

快捷键：红字(Ctrl R) + 蓝字(Ctrl E)

修改内容方法 ​

场景：

  1. 目录重构后：Markdown 文章里残留着指向旧中文路径的链接（例如 [链接](../某某文件夹/img.png)），导致 404。
  2. 写作过程中：文章里留下了大量临时的数字占位符（例如 [待补充](1)）或未填写的空链接（例如 [待办]()），发布前需要统一清理。

解决方案： 利用 VS Code 强大的 正则表达式 (Regex) 搜索功能，根据不同需求，精准定位问题链接

操作步骤：

  1. 打开全局搜索：

    Windows: Ctrl + Shift + F

  2. 开启正则模式：

    点击搜索框右侧的 .\* 图标（Use Regular Expression）

  3. 输入正则表达式（根据需求三选一）：

    🎯 需求 A：猎杀残留的中文路径

    正则代码：

    \]\(.*[\u4e00-\u9fa5].*\)

    原理：

    • \]\(：定位 Markdown 链接中间的 ]( 部分。
    • .*：中间任意字符。
    • [\u4e00-\u9fa5]：关键点，这是匹配所有常用汉字的 Unicode 范围。
    • 含义：“只要圆括号（链接地址）里出现了汉字，就给我抓出来！”

    🎯 需求 B：猎杀纯数字占位符 (如 [xx](1))

    正则代码：

    \]\(\d+\)

    原理：

    • \d+：匹配一个或多个纯数字。
    • 含义：“只要圆括号里只有数字，没有别的内容，就抓出来！”

    🎯 需求 C：猎杀空链接或空格链接 (如 [xx]() 或 [xx]( ))

    正则代码：

    代码段

    \]\(\s*\)

    原理：

    • \s*：匹配 0 个或多个空白字符（包括空格、Tab）。
    • 含义：“只要圆括号里是空的，或者只有空格，就抓出来！”

  4. 批量修复： 在搜索结果中点击，直接定位到文件对应行，手动修改为正确的英文路径或完整链接即可

原理：

  • \]\(：定位 Markdown 链接中间的 ]( 部分。
  • .*：中间任意字符。
  • [\u4e00-\u9fa5]：关键点，这是匹配所有常用汉字的 Unicode 范围。
  • 即：“只要圆括号（链接地址）里出现了汉字，就给我抓出来！”

特殊页面配置指南 ​

对于 docs/game/ 和 docs/blender/ 下的页面，为了获得沉浸式体验（全宽显示、无侧边栏），必须在 Markdown 头部添加 layout 属性。

Frontmatter 模板：

yaml
---
title: 我的3D模型展示
date: 2026-01-11       # 必须加日期，否则热力图不统计！
layout: page           # 关键！使用 page 布局可隐藏侧边栏
# layout: home         # 或者使用 home 布局（通常用于类似首页的宽屏展示）
---

<script setup>
// 在这里引入你的 Vue 组件
import ModelViewer from '../../components/ModelViewer.vue'
</script>

# 模型展示

<ModelViewer src="..." />

修改网站配置 ​

首页配置&内容 ​

首页Hero区按钮 ​

首页“四大按钮”HomeDock ​

首页“推荐项目”HomeContent ​

修改首页的推荐项目

首页“技术列表”HomeNews ​

逻辑配置 ​

基于 VitePress 搭建 | 记录生活与代码

Copyright © 2025-present PandaC

PandaC