PandaC's Blog

Appearance

博客使用指南 ​

紧跟：个人博客网 来上手此博客

内容使用方法 ​

文件命名规范与路径重构 (2026-01-02 更新) ​

博客文件名英文！写上title中文标签即可

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

核心原则：英核中皮 ​

我们采用 “英文文件名 + 中文标题” 的策略：

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

为什么这样做？ ​

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

操作流程 (SOP) ​

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)

常用目录命名对照表 (Naming Convention) ​

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

📂 01.Coding (代码技术)

  • 个人开发技术栈 → TechStack
    • Web三件套 → WebBasics.md
    • Vue框架 → VueFramework.md
  • 开发环境配置 → EnvSetup
  • AI编程 → AIProgramming
    • 个人开发 → IndieProjects

📷 02.Visuals (视觉工坊)

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

🔤 03.English (英语学习)

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

💎 04.Share (资源分享)

  • 工具软件分享 → SoftwareTools
    • 工作利器 → WorkTools
    • Mermaid教程 → MermaidTutorial.md
  • 网络服务配置 → NetworkConfig
  • 网站建设指南 → WebBuilding
    • 博客使用指南 → BlogGuide.md
  • 自动化Work → Automation

🚀 05.Growth (个人成长)

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

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

🕹️ game (游戏厅)

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

🏛️ blender (3D博物馆)

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

🔧 System & Private (系统与后台) 存放 Vue 组件源码或不公开的私人内容，通常不直接出现在导航栏中

⚙️ util (实用工具页)

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

🔒 private (私密树洞)

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

常用内容插入指南 ​

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

在文章中引用站内的另一篇文章，点击可直接跳转

语法：[链接显示的文字](/目录/英文文件名.md)

示例：

推荐阅读我的 [Mermaid 绘图教程](/docs/04.Share/SoftwareTools/MermaidTutorial.md)

注意：

  1. 推荐使用 根路径 (以 / 开头)，路径更稳定
  2. 必须使用 英文文件名
  3. 后缀推荐写 .md，这样在本地 Typora 也能跳转，网页端会自动转为 HTML

插入图片 ​

通常配合 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