我的文档

简体中文

English

简体中文

English

主题

添加新内容 ​

学习如何在 VitePress 网站中添加新的文章和页面。

📚 基础概念 ​

文件即页面 ​

VitePress 遵循一个简单的规则：

  • ✅ 每个 .md 文件 = 一个网页
  • ✅ 文件路径 = 网页 URL
  • ✅ 文件名建议用英文（避免中文）

URL 映射示例 ​

文件路径访问 URL
docs/about.md/about
docs/guide/intro.md/guide/intro
docs/blog/post.md/blog/post

快速添加文章 ​

方法一：根目录添加（最简单） ​

适合单独页面，如"关于"、"联系"等。

步骤：

  1. 在 docs/ 目录创建 my-page.md
  2. 编写内容：
markdown
# 我的新页面

这是页面内容...
  1. 在 config.js 添加导航：
js
nav: [
  { text: '首页', link: '/' },
  { text: '我的新页面', link: '/my-page' }  // 新增
]

完成！导航栏会显示新页面链接。

方法二：在分类目录添加 ​

适合添加到现有分类，如在"指南"下添加教程。

步骤：

  1. 在 docs/guide/ 创建 new-tutorial.md
  2. 编写内容
  3. 在 config.js 的侧边栏添加：
js
sidebar: {
  '/guide/': [
    {
      text: '入门教程',
      items: [
        { text: '快速开始', link: '/guide/getting-started' },
        { text: '新教程', link: '/guide/new-tutorial' }  // 新增
      ]
    }
  ]
}

访问 /guide/ 下任何页面，侧边栏会显示"新教程"。

创建新分类 ​

假设创建"博客"分类：

1. 创建目录 ​

bash
# Windows
mkdir docs\blog

# Mac/Linux
mkdir docs/blog

2. 创建文章 ​

创建 docs/blog/my-post.md：

markdown
---
title: 我的第一篇博客
date: 2024-01-15
---

# 我的第一篇博客

这是博客内容...

3. 创建索引页 ​

创建 docs/blog/index.md：

markdown
# 博客文章

## 最新文章

- [我的第一篇博客](/blog/my-post) - 2024-01-15

4. 添加导航 ​

在 config.js 添加：

js
nav: [
  { text: '首页', link: '/' },
  { text: '博客', link: '/blog/' }  // 新增博客导航
]

5. 添加侧边栏（可选） ​

js
sidebar: {
  '/blog/': [
    {
      text: '博客',
      items: [
        { text: '最新', link: '/blog/' },
        { text: '我的第一篇', link: '/blog/my-post' }
      ]
    }
  ]
}

导航配置详解 ​

简单导航 ​

js
nav: [
  { text: '首页', link: '/' },
  { text: '关于', link: '/about' }
]

下拉菜单 ​

js
nav: [
  {
    text: '博客',
    items: [
      { text: '最新文章', link: '/blog/' },
      { text: '技术', link: '/blog/tech' },
      { text: '生活', link: '/blog/life' }
    ]
  }
]

分组菜单 ​

js
nav: [
  {
    text: '资源',
    items: [
      {
        text: '文档',
        items: [
          { text: '指南', link: '/guide/' },
          { text: 'API', link: '/api/' }
        ]
      },
      {
        text: '工具',
        items: [
          { text: '插件', link: '/plugins/' }
        ]
      }
    ]
  }
]

侧边栏配置详解 ​

单一侧边栏 ​

所有页面使用相同侧边栏：

js
sidebar: [
  {
    text: '指南',
    items: [
      { text: '介绍', link: '/guide/' }
    ]
  }
]

多侧边栏 ​

不同路径使用不同侧边栏：

js
sidebar: {
  // /guide/ 路径的侧边栏
  '/guide/': [
    {
      text: '指南',
      items: [
        { text: '介绍', link: '/guide/' }
      ]
    }
  ],
  
  // /blog/ 路径的侧边栏
  '/blog/': [
    {
      text: '博客',
      items: [
        { text: '最新', link: '/blog/' }
      ]
    }
  ]
}

可折叠侧边栏 ​

js
sidebar: [
  {
    text: '基础教程',
    collapsed: false,  // false=默认展开
    items: [
      { text: '第一课', link: '/lesson1' }
    ]
  },
  {
    text: '进阶教程',
    collapsed: true,   // true=默认折叠
    items: [
      { text: '高级技巧', link: '/advanced' }
    ]
  }
]

完整示例 ​

创建"项目展示"分类的完整流程。

1. 创建文件结构 ​

docs/projects/
├── index.md       # 项目列表
├── project-a.md   # 项目 A
└── project-b.md   # 项目 B

2. 创建索引页 ​

docs/projects/index.md：

markdown
# 项目展示

## 所有项目

- [项目 A](/projects/project-a) - 一个很酷的项目
- [项目 B](/projects/project-b) - 另一个项目

3. 创建项目页面 ​

docs/projects/project-a.md：

markdown
# 项目 A

## 简介

这是项目 A...

## 技术栈

- Vue.js
- VitePress

## 链接

- [在线演示](https://example.com)
- [GitHub](https://github.com/user/project-a)

4. 更新配置 ​

编辑 docs/.vitepress/config.js：

js
export default {
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { 
        text: '项目',
        items: [
          { text: '所有项目', link: '/projects/' },
          { text: '项目 A', link: '/projects/project-a' },
          { text: '项目 B', link: '/projects/project-b' }
        ]
      }
    ],
    
    sidebar: {
      '/projects/': [
        {
          text: '项目展示',
          items: [
            { text: '项目列表', link: '/projects/' },
            { text: '项目 A', link: '/projects/project-a' },
            { text: '项目 B', link: '/projects/project-b' }
          ]
        }
      ]
    }
  }
}

Front Matter ​

在文章开头添加元数据：

markdown
---
title: 文章标题
description: 文章描述
date: 2024-01-15
author: 张三
tags:
  - Vue
  - VitePress
---

# 文章内容...

常用字段 ​

字段说明
title页面标题（覆盖 # 标题）
description页面描述（用于 SEO）
layout布局类型（home、doc、page）
navbar是否显示导航栏（true/false）
sidebar是否显示侧边栏（true/false）

最佳实践 ​

文件命名规范 ​

✅ 推荐：

  • getting-started.md
  • api-reference.md
  • 2024-01-15-my-post.md

❌ 不推荐：

  • 开始使用.md（避免中文）
  • api_reference.md（用 - 替代 _）
  • MyArticle.md（用小写）

目录结构建议 ​

docs/
├── guide/          # 教程指南
├── api/            # API 文档
├── blog/           # 博客文章
│   ├── tech/       # 技术分类
│   └── life/       # 生活分类
├── projects/       # 项目展示
├── faq.md          # 常见问题
└── about.md        # 关于

图片管理 ​

  1. 把图片放在 docs/public/images/
  2. 在 Markdown 中引用：
markdown
![图片描述](/images/screenshot.png)

链接写法 ​

内部链接：

markdown
[快速开始](/guide/getting-started)
[相对路径](./other-page)

外部链接：

markdown
[VitePress](https://vitepress.dev)

常见问题 ​

添加了文章但导航不显示？ ​

原因：没在 config.js 的 nav 中添加链接。

解决：

js
nav: [
  { text: '新文章', link: '/new-article' }
]

点击链接显示 404？ ​

检查：

  • 文件是否存在：docs/new-article.md
  • 链接是否正确：/new-article（注意开头的 /）

侧边栏不显示？ ​

原因：页面路径不匹配侧边栏配置。

解决：

如果配置是 /guide/：

js
sidebar: {
  '/guide/': [...]  // 只在 /guide/ 下显示
}

则只有 /guide/xxx 页面才会显示侧边栏。

修改 config.js 没生效？ ​

解决：重启开发服务器

bash
# 按 Ctrl+C 停止
npm run docs:dev  # 重新启动

检查清单 ​

添加新文章后检查：

  • [ ] 文件已创建在正确位置
  • [ ] 文件名使用英文和 -
  • [ ] 文章内容已完成
  • [ ] 在 config.js 添加了导航/侧边栏
  • [ ] 保存了配置文件
  • [ ] 页面能正常访问
  • [ ] 链接都能正常跳转

总结 ​

三步添加文章 ​

  1. 创建文件 - 在 docs/ 下创建 .md 文件
  2. 编写内容 - 使用 Markdown 写作
  3. 更新配置 - 在 config.js 添加导航

关键点 ​

  • 📁 文件路径 = URL 路径
  • 📝 Markdown = 网页
  • ⚙️ config.js 控制导航和侧边栏
  • 💡 修改后自动刷新（配置文件除外）

更多详细信息

查看根目录的 如何添加新文章.md 了解更多场景和示例。

基于 MIT 许可发布 | 使用 VitePress 构建

Copyright © 2026-present