vitepress系列-01-搭建笔记骨架

搭建笔记骨架

环境依赖：Node.js 18 及以上版本。

项目创建-以macOS为例

# 1.创建空项目
mkdir vitepress-learn-notes

# 2.进入 vitepress-learn-notes
cd vitepress-learn-notes

# 3. 初始化项目
pnpm init

# 4.安装vitepress 根据自己电脑的安装插件 比如 npm yarn pnpm bun
pnpm add -D vitepress

# 5. 安装向导
pnpm vitepress init

注意：

VitePress 是仅 ESM 的软件包。不要使用 require() 导入它，并确保最新的 package.json 包含 "type": "module"，或者更改相关文件的文件扩展名，例如 .vitepress/config.js 到 .mjs/.mts。更多详情请参考 Vite 故障排除指南。此外，在异步 CJS 上下文中，可以使用 await import('vitepress') 代替。

将需要回答几个简单的问题：

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◆  Theme:
│  ● Default Theme (Out of the box, good-looking docs)
│  ○ Default Theme + Customization
│  ○ Custom Theme
└

注意： Vue 作为 peer dependency 这边主要是修复，在vitepress中引用vue相关的API报错的问题。

Vue 作为 peer dependency
如果打算使用 Vue 组件或 API 进行自定义，还应该明确地将 vue 安装为 peer dependency。

文件结构

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

目录说明：

docs 目录作为 VitePress 站点的项目根目录。.vitepress 目录是 VitePress 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的位置。

配置文件

配置文件 (.vitepress/config.js)

// .vitepress/config.js
export default {
  // 站点级选项
  title: 'VitePress',
  description: 'Just playing around.',

  themeConfig: {
    // 主题级选项
  }
}

还可以通过 themeConfig 选项配置主题的行为。有关所有配置选项的完整详细信息，请参见配置参考。

源文件

.vitepress 目录之外的 Markdown 文件被视为源文件。

VitePress 使用 基于文件的路由：每个 .md 文件将在相同的路径被编译成为 .html 文件。例如，index.md 将会被编译成 index.html，可以在生成的 VitePress 站点的根路径 / 进行访问。

VitePress 还提供了生成简洁 URL、重写路径和动态生成页面的能力。这些将在路由指南中进行介绍。

启动并运行

该工具还应该将以下 npm 脚本注入到 package.json 中：

{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}

docs:dev 脚本将启动具有即时热更新的本地开发服务器。使用以下命令运行它：

pnpm run docs:dev

除了 npm 脚本，还可以直接调用 VitePress：

pnpm exec vitepress dev docs

更多的命令行用法请参见 CLI 参考。

下一步

• 想要进一步了解 Markdown 文件是怎么映射到对应的 HTML，请继续阅读路由指南。
• 要了解有关可以在页面上执行的操作的更多信息，例如编写 Markdown 内容或使用 Vue 组件，请参见指南的“编写”部分。一个很好的起点是了解 Markdown 扩展。
• 要探索默认文档主题提供的功能，请查看默认主题配置参考。
• 如果想进一步自定义站点的外观，参见扩展默认主题或者构建自定义主题。
• 文档成形以后，务必阅读部署指南。