Duan's Site

Appearance

VitePress 新手指南 ​

本站使用 VitePress 搭建，以下是日常维护所需的知识。

核心工作流 ​

编辑 /root/articles/posts/xxx.md   ← 新增或修改文章
              ↓
      ~/articles/deploy.sh          ← 一键构建 + 部署
              ↓
      线上自动生效（Nginx 无需重启）

注意

永远修改 /root/articles/posts/ 下的源文件，不要直接改 /var/www/ 下的产出文件。

文件命名 ​

文件名直接决定 URL 路径：

文件名访问 URL
hello-world.md/articles/posts/hello-world
2026-04-13-hello-world.md/articles/posts/2026-04-13-hello-world

命名建议：

  • 使用小写英文 + 短横线，如 my-first-post.md
  • 避免空格和中文（中文能用但 URL 不美观）
  • 日期前缀可加可不加，排序和日期展示靠的是 frontmatter 而非文件名

Frontmatter ​

每篇文章顶部用 --- 包裹的区域叫 frontmatter，是文章的元数据：

md
---
title: 文章标题          # 博文列表页展示的标题
date: 2026-04-13         # 日期，用于列表页排序
excerpt: 一句话简介       # 博文列表页展示的摘要（可选）
---
  • title 和 date 建议必填，否则列表页显示"无标题"且排序混乱
  • excerpt 可选，不写则列表页不显示摘要

Markdown 扩展语法 ​

VitePress 在标准 Markdown 基础上支持以下扩展。

提示容器 ​

md
::: tip 提示标题
提示内容
:::

::: warning 警告标题
警告内容
:::

::: danger 危险标题
危险内容
:::

::: details 点击展开
折叠的内容
:::

渲染效果：

提示

这是一条提示信息。

警告

这是一条警告信息。

危险

这是一条危险警告。

点击展开

这是被折叠的内容，点击标题可以展开。

代码块高亮指定行 ​

在语言标识后用 {行号} 指定高亮行：

md
```js{2,4}
const a = 1
const b = 2  // 高亮
const c = 3
const d = 4  // 高亮
```
js
const a = 1
const b = 2  // 高亮
const c = 3
const d = 4  // 高亮

自动生成目录 ​

在文章任意位置插入 [[toc]]，会自动根据标题层级生成目录（本文顶部就用了这个）。

图片 ​

在 posts/ 下创建子目录存放图片，使用相对路径引用：

md
![示意图](./images/demo.png)

构建时图片会自动复制到产出目录，无需额外配置。

首页配置 ​

首页文件是 /root/articles/index.md，使用 VitePress 的 home 布局。当前内容如下：

yaml
---
layout: home
hero:
  name: "Duan's Blog"       # 大标题
  text: '个人博客'            # 副标题
  tagline: 记录技术与思考     # 标语
  actions:                    # 按钮列表
    - theme: brand            #   主按钮（实心）
      text: 阅读博文
      link: /posts/
---

可修改项 ​

添加更多按钮——在 actions 下追加条目：

yaml
actions:
  - theme: brand           # 主按钮（实心高亮）
    text: 阅读博文
    link: /posts/
  - theme: alt             # 次按钮（边框样式）
    text: GitHub
    link: https://github.com/yourname

添加首页特性卡片——在 frontmatter 中添加 features：

yaml
---
layout: home
hero:
  name: "Duan's Blog"
  text: '个人博客'
  tagline: 记录技术与思考
  actions:
    - theme: brand
      text: 阅读博文
      link: /posts/
features:
  - title: 技术笔记
    details: 记录开发中的经验与踩坑
  - title: 随笔思考
    details: 一些零散的想法和感悟
  - title: 工具推荐
    details: 好用的开发工具和效率技巧
---

侧边栏与导航栏 ​

配置文件位于 /root/articles/.vitepress/config.mjs。

  • 侧边栏：构建时自动扫描 posts/ 目录生成，新增文章后跑 deploy.sh 即可更新，无需手动改配置
  • 顶部导航栏：在 config.mjs 的 themeConfig.nav 中配置，格式为 { text: '显示文字', link: '路径' }

本地预览 ​

部署前想看效果，可以运行：

bash
cd ~/articles && npm run dev

浏览器访问 http://localhost:5173/articles/，修改 .md 文件后页面会自动热更新。

常用命令速查 ​

命令用途
npm run dev本地开发预览（热更新）
npm run build构建静态文件
~/articles/deploy.sh一键构建 + 部署到线上