前端文档【免费下载链接】vitepressVite Vue powered static site generator.项目地址https://gitcode.com/gh_mirrors/vi/vitepress点击查看免费下载本指南面向首次接触 VitePress 的开发者完整讲解基于 Vite Vue 的静态站点生成器 VitePress 的安装、项目初始化、目录结构与配置文件编写并带你跑通dev开发服务器。读完后你将能够独立搭建一个可运行的 VitePress 文档站点并理解其每个 Markdown 文件对应一个页面的文件路由机制为后续学习路由、Markdown 扩展与部署打下基础。在线尝试如果暂时不想在本地安装任何东西可以直接在浏览器中打开 StackBlitz官方提供的在线沙箱入口仓库 README 与文档均以此作为零安装体验入口进行在线尝试。它预置了完整的 VitePress 环境适合先感受站点效果、再回到本地动手实践。安装前置准备开始之前请确认你的环境满足以下条件Node.js 22 及以上版本VitePress 2.x 的 CLI、构建管线与开发服务器均依赖较新的 Node 运行时能力包括原生 ESM 支持。一个终端CLI需要通过命令行界面调用 VitePress 的dev、build、preview等命令。支持 Markdown 语法的编辑器推荐 VSCode并安装其官方 Vue 扩展Volar以便在.md中嵌入 Vue 组件时获得语法高亮与类型提示。VitePress 既可以作为独立站点使用也可以安装进现有项目。两种场景下的安装命令一致只需在项目根目录执行::: code-group$ npm add -D vitepressnext$ pnpm add -D vitepressnext$ yarn add -D vitepressnext vue$ bun add -D vitepressnext:::::: tip 注意VitePress 是仅 ESM 的软件包。请不要使用require()导入它并确保最近的package.json包含type: module或者将相关文件的扩展名改为.mjs/.mts例如.vitepress/config.js改为.mjs。更多细节可参考 Vite 官方的 ESM-only 故障排除指南。在异步 CJS 上下文中可以使用await import(vitepress)代替。:::从仓库根目录的 package.json 可以看到type: module 与 files 中打包的dist、bin、template等目录印证了该包以纯 ESM 形式发布bin字段将vitepress命令指向bin/vitepress.js这正是你安装后能在终端直接调用vitepress命令的原因。安装向导VitePress 自带一个命令行设置向导能够帮你脚手架出一个基础项目。安装完成后运行::: code-group$ npx vitepress init$ pnpm vitepress init$ yarn vitepress init$ bun vitepress init:::你将被问到几个简单的问题。仓库中的 docs/snippets/init.ansi 完整记录了向导的交互过程大致如下Where should VitePress initialize the config?配置文件放在哪里默认./可填./docs。Where should VitePress look for your markdown files?从哪里寻找 Markdown 源文件。Site title站点标题默认My Awesome Project。Site description站点描述默认A VitePress Site。Theme选择主题——Default Theme开箱即用的文档样式、Default Theme Customization额外生成自定义 CSS 与布局插槽、Custom Theme完全自定义或使用外部主题。Use TypeScript for config and theme files?是否使用 TypeScript 编写配置与主题文件。Add VitePress npm scripts to package.json?是否自动注入 npm 脚本。Add a prefix for VitePress npm scripts? / Prefix是否给脚本加前缀默认docs最终生成docs:dev等。从源码看向导的交互逻辑位于 src/node/init/init.tsinit()通过clack/prompts的group()依次收集上述选项随后调用scaffold()生成文件。ScaffoldThemeType定义了三种主题选项Default、DefaultCustom、Custom与向导中的选项一一对应。scaffold()内部使用 Eta 模板引擎渲染 template 目录下的模板文件并会根据useTs、userPkg.type ! module等条件自动把.vitepress/config.js改写为.mjs或.ts扩展名见useMjs与renderFile中的扩展名替换逻辑。向导结束时还会根据你的选择给出提示如果项目内存在.git会提醒你把.vitepress/dist和.vitepress/cache加入.gitignore如果选择了自定义主题但项目尚未安装vue则会提示显式安装vue作为 devDependency。仓库的tests/init/init.test.ts 对三种主题 × 是否使用 TypeScript 共 6 种组合做了端到端验证先scaffold出项目再启动开发服务器断言首页标题与示例页面可以正常访问。::: tip Vue 作为 peer dependency 如果打算使用 Vue 组件或 API 进行自定义还应该明确地将vue安装为 dependency。 :::文件结构如果你正在构建独立的 VitePress 站点可以直接在当前目录./搭建但如果是在已有项目中与其他源码共存建议将站点搭建在嵌套目录例如./docs中以便与项目其余部分分开。假设选择在./docs中搭建生成的文件结构如下. ├─ docs │ ├─ .vitepress │ │ └─ config.js │ ├─ api-examples.md │ ├─ markdown-examples.md │ └─ index.md └─ package.jsondocs目录被视为 VitePress 站点的项目根目录。.vitepress目录是 VitePress 的保留位置用于存放配置文件、开发服务器缓存、构建输出以及可选的主题自定义代码。这些模板文件在仓库中均有对应template/index.md、template/api-examples.md、template/markdown-examples.md是三个示例源文件template/.vitepress/config.js是配置模板若选择默认主题 自定义还会额外生成template/.vitepress/theme/index.js与template/.vitepress/theme/style.css若选择完全自定义主题则再追加template/.vitepress/theme/Layout.vue。::: tip 默认情况下VitePress 将开发服务器缓存存储在.vitepress/cache中生产构建输出存储在.vitepress/dist中。如果使用 Git应将它们加入.gitignore。这两个位置也可以通过outDir/cacheDir等选项手动配置。 :::配置文件配置文件.vitepress/config.js用于自定义 VitePress 站点的方方面面最基本的选项是站点的标题和描述import { defineConfig } from vitepress export default defineConfig({ // 站点级选项 title: VitePress, description: Just playing around., themeConfig: { // 主题级选项 nav: [ { text: Home, link: / }, { text: Examples, link: /markdown-examples } ], sidebar: [ { text: Examples, items: [ { text: Markdown Examples, link: /markdown-examples }, { text: Runtime API Examples, link: /api-examples } ] } ] } })还可以通过themeConfig选项配置主题行为。有关全部配置选项的详细信息参见配置参考。仓库中的 template/.vitepress/config.js 展示了向导生成的真实配置模板它会根据srcDir、title、description与是否使用默认主题defaultTheme动态填充内容并默认生成nav、sidebar与socialLinks三组主题配置——这正是文档提到的themeConfig最常用的几个入口。源文件.vitepress目录之外的 Markdown 文件都被视为源文件。VitePress 使用基于文件的路由每个.md文件会在相同路径下被编译为对应的.html文件。例如index.md会被编译成index.html可以在生成站点的根路径/访问。这一文件即路由的约定贯穿 VitePress 的整个工作流docs/zh/guide/下每个.md文档对应一个文档页面就是最好的例证。此外VitePress 还支持生成简洁 URL、路径重写rewrites以及动态生成页面等能力这些将在路由指南中介绍。启动并运行向导在安装向导阶段选择注入 npm 脚本时会自动向package.json写入以下脚本{ ... scripts: { docs:dev: vitepress dev docs, docs:build: vitepress build docs, docs:preview: vitepress preview docs }, ... }docs:dev脚本会启动一个带即时热更新的本地开发服务器。运行方式::: code-group$ npm run docs:dev$ pnpm run docs:dev$ yarn docs:dev$ bun run docs:dev:::除了 npm 脚本也可以直接调用 VitePress 命令::: code-group$ npx vitepress dev docs$ pnpm vitepress dev docs$ yarn vitepress dev docs$ bun vitepress dev docs:::其中docs是站点根目录参数更多的命令行用法参见 CLI 参考。开发服务器默认运行在http://localhost:5173在浏览器中访问该地址即可看到新站点。从 src/node/cli.ts 的源码可以还原这条命令的底层流程vitepress dev docs会先通过resolveConfig解析配置再调用createServer创建开发服务器随后server.listen()、打印版本与访问地址并通过bindShortcuts绑定终端快捷键。cli.ts同时支持init调用 src/node/init/init.ts 的init()、build调用build()与serve/preview调用serve()命令并会为未知命令报错。开发服务器运行时终端还支持一组交互快捷键定义在 src/node/shortcuts.ts按r重启服务器、u显示服务器地址、o在浏览器中打开、c清空控制台、q退出CtrlC/CtrlD亦可退出按h可查看全部快捷键帮助。当process.stdin非 TTY 或处于 CI 环境时这些快捷键会自动禁用。下一步想进一步了解 Markdown 文件如何映射为对应的 HTML 页面请阅读路由指南。要了解页面上能做的更多操作例如编写 Markdown 内容或使用 Vue 组件请参见指南的编写部分一个不错的起点是Markdown 扩展。要探索默认文档主题提供的功能请查看默认主题配置参考。想进一步自定义站点外观参见扩展默认主题或构建自定义主题。文档成形后务必阅读部署指南。至此你已经完成了 VitePress 从零到一的全流程搭建了解了前置环境要求与 ESM-only 的注意事项掌握了vitepress init向导的每一个交互选项及其底层实现理解了.vitepress目录的职责与文件即路由的页面映射机制并成功启动了自己的第一个本地开发站点。接下来就可以在这个骨架上开始撰写内容逐步探索 VitePress 的 Markdown 扩展、主题定制与部署发布能力。赞分享前端文档【免费下载链接】vitepressVite Vue powered static site generator.项目地址https://gitcode.com/gh_mirrors/vi/vitepress点击查看免费下载相关推荐syncpack 与主流包管理器集成npm、pnpm、yarn 的终极对比指南 syncpack 与主流包管理器集成npm、pnpm、yarn 的终极对比指南 在大型 JavaScript 单体仓库Monorepo中 sync开发工具如何快速开始ClusterFuzz10分钟搭建本地开发环境ClusterFuzz是Google开源的 大规模模糊测试基础设施 能够自动发现软件问题并管理整个测试生命周期。作为一款专业的 模糊测试平台 它支持分布式并应用安全后端开发工具Gogs 本地开发环境搭建指南依赖安装、数据库初始化与 moon run gogs:dev 开发循环Gogs 本地开发环境搭建指南依赖安装、数据库初始化与 moon run gogs:dev 开发循环 本文基于 Gogs 仓库官方的 本地开发文档 https后端代码托管上一篇终极指南3分钟掌握Filament主题色彩系统的强大定制能力下一篇突破语言壁垒Crawlee多语言爬取实战终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
