{"id":19151903,"url":"https://github.com/azcodingaccount/my-docs-website","last_synced_at":"2025-05-07T05:42:25.344Z","repository":{"id":216051919,"uuid":"740348517","full_name":"AZCodingAccount/my-docs-website","owner":"AZCodingAccount","description":"AlbertZhang的文档网站","archived":false,"fork":false,"pushed_at":"2024-03-03T14:13:32.000Z","size":155,"stargazers_count":16,"open_issues_count":0,"forks_count":7,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-19T19:05:09.480Z","etag":null,"topics":["github-pages","vitepress"],"latest_commit_sha":null,"homepage":"https://docs.bugdesigner.cn","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AZCodingAccount.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-01-08T06:53:42.000Z","updated_at":"2025-04-16T12:24:48.000Z","dependencies_parsed_at":"2024-03-03T15:27:45.446Z","dependency_job_id":"e484a909-ed98-4407-92cf-793e30c48163","html_url":"https://github.com/AZCodingAccount/my-docs-website","commit_stats":null,"previous_names":["azcodingaccount/my-docs-website"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AZCodingAccount%2Fmy-docs-website","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AZCodingAccount%2Fmy-docs-website/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AZCodingAccount%2Fmy-docs-website/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AZCodingAccount%2Fmy-docs-website/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AZCodingAccount","download_url":"https://codeload.github.com/AZCodingAccount/my-docs-website/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252823669,"owners_count":21809707,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-pages","vitepress"],"created_at":"2024-11-09T08:16:00.515Z","updated_at":"2025-05-07T05:42:25.308Z","avatar_url":"https://github.com/AZCodingAccount.png","language":"JavaScript","readme":"# vitepress搭建并部署网站\n\n## 前言\n\n首先，明确一点，**不要轻易用最新的版本**！！！很多开源项目文档写的真的太简练了，个人觉得不太适合小白，给个QA区也好啊。最后我们在遇到问题的时候解决方案一般有三条：\n\n1. 去网上搜索，看别人写的博客\n2. 问gpt\n3. 问别人（效率最低，特别是对于不会提问的同学）\n\n对开源项目来说，还有两条\n\n1. 去github的issues区看别人是否遇到过这种问题\n2. 提issue\n\n为什么说不要用最新版本，首先版本发布的最新，很多问题网上根本没有解决方案，特别是对于比较小众的开源项目。问GPT的话它的知识库都没更新到最新，也没法解决。至于github的issue区也只能碰运气。\n\n到最后遇到问题你只能提issue，这个时候就得看负责维护这个项目团队的积极性了，vitepress团队还是很奈斯的，我今天两点提了个issue8分钟就回复了，也得益于美国跟咱这边有时差。\n\n![image-20240108185018057](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108185018057.png)\n\n## 创建项目\n\n话不多说，接下来开始我们的搭建步骤。对于开源项目，肯定是直接看官网和一些最佳实践了。\n\nvitepress官网地址：https://vitepress.dev/\n\n模仿的最佳实践（B站一个UP主的）：https://docs.zhengxinonly.com/\n\n**安装vitepress**\n\n首先新建文件夹，打开cmd窗口\n\n```sh\npnpm add -D vitepress\n```\n\n**初始化Vitepress**\n\n```sh\npnpm vitepress init\n```\n\n这是我的配置，简单介绍一下\n\n- 第一个是在当前根目录下创建vitepress项目\n\n- 站点标题和描述。后续可以在配置中改\n- 主题，建议选择第二个，个人觉得比较好看\n- 是否使用ts，我们个人学习就没必要ts了，主要还是我懒\n- 是否添加脚本到package.json，这个还是需要的，启动命令，打包命令这些都得用\n\n\u003cimg src=\"https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108190215775.png\" alt=\"image-20240108190215775\" style=\"zoom:50%;\" /\u003e\n\n初始化成功后，使用vscode或webstorm打开文件夹，会看到这样一个目录。接下来简单介绍一下每个文件的含义\n\n- .vitepress，最核心的目录，\n- theme目录。自定义主题配置，css样式等\n- config.mjs。最核心的文件，各种配置导航栏、侧边栏、标题什么的都是在这里\n- node_modules。安装的依赖\n- api-examples.md和markdown-examples.md。官方给的两个示例\n- index.md。主页相关\n- package.json和pnpm-lock.yml。包管理工具需要用的\n\n![image-20240108190658316](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108190658316.png)\n\n**启动项目**\n\n```sh\npnpm run docs:dev\n```\n\n打开，看到这个，说明初始化成功\n\n![image-20240108191252240](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108191252240.png)\n\n## 自定义配置\n\n### 美化主页\n\n对于主页，我们自定义的内容有哪些？如下图，8个地方可以自定义。接下来就一一叙述者8个地方怎么自定义的。\n\n![image-20240108191730006](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108191730006.png)\n\n2-6是在index.md文件中自定义的。简单介绍一下对应关系\n\n`name\u003c==\u003e2`\t\t`text\u003c==\u003e3`\t\t`tagline\u003c==\u003e4`\t\t`actions\u003c==\u003e5`\t\t`features\u003c==\u003e6`\n\n需要说明的是，对于5这两个按钮，是可以跳转的，**link指定路径**，比如/api-example就是在项目根目录下找api-example.md这个文件\t\n\n\u003cimg src=\"https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108192410028.png\" alt=\"image-20240108192410028\" style=\"zoom:50%;\" /\u003e\n\n修改后的页面如下：\n\n![image-20240108192848790](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108192848790.png)\n\n1、7、8这三个配置是在config.mjs中配置的\n\n其中，title对应1，nav对应7，socialLinks对应8。description是SEO要用的，我们不用关注。\n\n\u003cimg src=\"https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108194059919.png\" alt=\"image-20240108194059919\" style=\"zoom:50%;\" /\u003e\n\n最后的结果是这样。\n\n![image-20240108194335668](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108194335668.png)\n\n### 主页扩展\n\n我们可能还想要对页面进行进一步美化，添加一些图标。可以去这个网站找图片https://www.iconfont.cn/\n\n将找到的图片放在根目录下的public目录下。\n\n\u003cimg src=\"https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108195132751.png\" alt=\"image-20240108195132751\" style=\"zoom:50%;\" /\u003e\n\n最后美化的效果如图：\n\n![image-20240108195220278](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108195220278.png)\n\n**TODO：**\n\n- logo的配置是在config.mjs添加。（注意是themeConfig不是config）\n\n```\nlogo: \"logo.svg\", // 配置logo位置，public目录\n```\n\n- vitepress原生支持国外的sociallink，如果是国内需要自行复制svg代码。如图：\n\n![image-20240108195501321](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108195501321.png)\n\n- 添加搜索栏，config.mjs中的themeConfig（支持国际化需要进一步配置 ）\n\n![image-20240108215134634](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108215134634.png)\n\n### 美化文章页\n\n默认进来官方给的示例是三边栏的\n\n左边是sidebar的配置，右边是显示的文章目录（默认显示一二级）。\n\n![image-20240108195711534](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108195711534.png)\n\n\n\n下面叙述这个是怎么配置的。sidebar可以是数组，也可以是对象。还是修改config.mjs\n\n![image-20240108200043005](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108200043005.png)\n\n最后的结果是这样\n\n![image-20240108200249558](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108200249558.png)\n\n右侧导航栏默认索引的是md文件的一二级标题，可能需要定义索引的标题级别和`On this page`这个说明。这个时候需要在config.mjs中配置下面这两个选项，`outlineTitle`用于替代On this page。`outline`定义展示的标题级别，这里定义2-6级\n\n![image-20240108200555674](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108200555674.png)\n\n最后美化后的文章目录是这样\n\n![image-20240108201005185](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108201005185.png)\n\n**自动生成侧边栏**\n\n我们使用这种配置时常常是一个目录有很多md文件，这些md文件所在的目录对应导航栏的一个选项。侧边栏的配置需要自己手写一个个路由映射到相应的文件上，那么有没有一个自动生成侧边栏的工具呢？根据一个目录下面的所有md文件自动生成路由，可以使用下面这个脚本\n\n```js\nimport path from \"node:path\";\nimport fs from \"node:fs\";\n\n// 文件根目录\nconst DIR_PATH = path.resolve();\n// 白名单,过滤不是文章的文件和文件夹\nconst WHITE_LIST = [\n  \"index.md\",\n  \".vitepress\",\n  \"node_modules\",\n  \".idea\",\n  \"assets\",\n];\n\n// 判断是否是文件夹\nconst isDirectory = (path) =\u003e fs.lstatSync(path).isDirectory();\n\n// 取差值\nconst intersections = (arr1, arr2) =\u003e\n  Array.from(new Set(arr1.filter((item) =\u003e !new Set(arr2).has(item))));\n\n// 把方法导出直接使用\nfunction getList(params, path1, pathname) {\n  // 存放结果\n  const res = [];\n  // 开始遍历params\n  for (let file in params) {\n    // 拼接目录\n    const dir = path.join(path1, params[file]);\n    // 判断是否是文件夹\n    const isDir = isDirectory(dir);\n    if (isDir) {\n      // 如果是文件夹,读取之后作为下一次递归参数\n      const files = fs.readdirSync(dir);\n      res.push({\n        text: params[file],\n        collapsible: true,\n        items: getList(files, dir, `${pathname}/${params[file]}`),\n      });\n    } else {\n      // 获取名字\n      const name = path.basename(params[file]);\n      // 排除非 md 文件\n      const suffix = path.extname(params[file]);\n      if (suffix !== \".md\") {\n        continue;\n      }\n      res.push({\n        text: name,\n        link: `${pathname}/${name}`,\n      });\n    }\n  }\n  // 对name做一下处理，把后缀删除\n  res.map((item) =\u003e {\n    item.text = item.text.replace(/\\.md$/, \"\");\n  });\n  return res;\n}\n\nexport const set_sidebar = (pathname) =\u003e {\n  // 获取pathname的路径\n  const dirPath = path.join(DIR_PATH, pathname);\n  // 读取pathname下的所有文件或者文件夹\n  const files = fs.readdirSync(dirPath);\n  // 过滤掉\n  const items = intersections(files, WHITE_LIST);\n  // getList 函数后面会讲到\n  return getList(items, dirPath, pathname);\n};\n```\n\n使用时，需要导入函数名，\n\n```js\nimport { set_sidebar } from \"../utils/auto-gen-sidebar.mjs\";\t// 改成自己的路径\n```\n\n直接使用。第一个/front-end/react常常是**nav的link**，这个set_sidebar传递的参数是相对于根路径的文件夹路径，返回的是每个文件夹中文件的名称和链接\n\n```js\nsidebar: { \"/front-end/react\": set_sidebar(\"front-end/react\") },\n```\n\n\n\n### 文章页扩展\n\n当然，这样对一些项目的文档是非常合适的。但是如果我们需要记笔记的话有些繁琐，并且三边栏总感觉可以查阅的东西变少了。因此可以使用刚才说的自定义样式。将三边栏改成两边栏\n\n在config.mjs中的themeConfig配置对象中配置 \n\n```js\nsidebar: false, // 关闭侧边栏\naside: \"left\", // 设置右侧侧边栏在左侧显示\n```\n\n在.vitepress theme style.css中配置下面的css\n\n```css\n/* 自定义侧边栏在最左边，右边撑满宽度 */\n.VPDoc .container {\n  margin: 0 !important;\n}\n@media (min-width: 960px) {\n  .VPDoc:not(.has-sidebar) .content {\n    max-width: 1552px !important;\n  }\n}\n.VPDoc.has-aside .content-container {\n  max-width: 1488px !important;\n}\n@media (min-width: 960px) {\n  .VPDoc:not(.has-sidebar) .container {\n    display: flex;\n    justify-content: center;\n    max-width: 1562px !important;\n  }\n}\n.aside-container {\n  position: fixed;\n  top: 0;\n  padding-top: calc(\n    var(--vp-nav-height) + var(--vp-layout-top-height, 0px) +\n      var(--vp-doc-top-height, 0px) + 10px\n  ) !important;\n  width: 224px;\n  height: 100vh;\n  overflow-x: hidden;\n  overflow-y: auto;\n  scrollbar-width: none;\n}\n\n/* 自定义h2的间距 */\n.vp-doc h2 {\n  margin: 0px 0 16px;\n  padding-top: 24px;\n  border: none;\n}\n```\n\n就可以将三栏样式改成双栏了（当然，上面的自定义css是我的偏好，根据实际情况可以修改），效果图如下\n\n\n\n![image-20240108204620601](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108204620601.png)\n\n## 使用Github Pages部署\n\n### 部署步骤\n\nGithub Pages专门用来托管静态内容，由于不需要服务器且基于git，支持CI/CD，成为很多静态网站比如博客、文档网站的很好的选择。下面介绍流程\n\n1. 在github上创建仓库，如果没有Github账号，需要先注册一个。\n\n![](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108205813594.png)\n\n2. 初始化git仓库\n\n```bash\ngit init\n```\n\n3. 添加gitignore文件\n\n```\nnode_modules\n.DS_Store\ndist\ndist-ssr\ncache\n.cache\n.temp\n*.local\n```\n\n4. 添加本地所有文件到git仓库\n\n```bash\ngit add .\n```\n\n5. 创建第一次提交\n\n```bash\ngit commit -m \"first commit\"\n```\n\n6. 添加远程仓库地址到本地\n\n```bash\ngit remote add origin https://github.com/AZCodingAccount/Demo.git\n```\n\n7. 推送项目到github\n\n```bash\ngit push -u origin master\n```\n\n8. 选择github actions\n\n![image-20240108210624305](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108210624305.png)\n\n9. 设置工作流\n\n![image-20240108210710694](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108210710694.png)\n\n10. 重命名并设置deploy脚本\n\n脚本文件：参考的vitepress官方文档：https://vitepress.dev/guide/deploy#github-pages\n\n❗node版本和pnpm版本需要一致\n\n❗对于npm的部署可以参考这个博客[GitHub Action一键部署个人博客 | Ahao (helloahao096.github.io)](https://helloahao096.github.io/helloahao/posts/GitHub Action一键部署个人博客.html)\n\n❗需要注意项目的根目录（.vitepress所在的目录）\n\n```yml\nname: Deploy VitePress site to Pages\n\non:\n  push:\n    branches: [master]\n\n# 设置tokenn访问权限\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\n# 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列\n# 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成\nconcurrency:\n  group: pages\n  cancel-in-progress: false\n\njobs:\n  # 构建工作\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v3\n        with:\n          fetch-depth: 0 # 如果未启用 lastUpdated，则不需要\n      - name: Setup pnpm\n        uses: pnpm/action-setup@v2 # 安装pnpm并添加到环境变量\n        with:\n          version: 8.6.12 # 指定需要的 pnpm 版本\n      - name: Setup Node\n        uses: actions/setup-node@v3\n        with:\n          node-version: 18\n          cache: pnpm # 设置缓存\n      - name: Setup Pages\n        uses: actions/configure-pages@v3  # 在工作流程自动配置GithubPages\n      - name: Install dependencies\n        run: pnpm install # 安装依赖\n      - name: Build with VitePress\n        run: |\n          pnpm run docs:build # 启动项目\n          touch .nojekyll  # 通知githubpages不要使用Jekyll处理这个站点，不知道为啥不生效，就手动搞了\n      - name: Upload artifact\n        uses: actions/upload-pages-artifact@v2  # 上传构建产物\n        with:\n          path: .vitepress/dist # 指定上传的路径，当前是根目录，如果是docs需要加docs/的前缀\n\n  # 部署工作\n  deploy:\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }} # 从后续的输出中获取部署后的页面URL\n    needs: build    # 在build后面完成\n    runs-on: ubuntu-latest  # 运行在最新版本的ubuntu系统上\n    name: Deploy\n    steps:\n      - name: Deploy to GitHub Pages\n        id: deployment  # 指定id\n        uses: actions/deploy-pages@v2 # 将之前的构建产物部署到github pages中\n\n```\n\n\n\n![image-20240108210850443](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108210850443.png)\n\n11. 点击确定，耐心等待15秒左右，就可以了，接下来查看我们的域名：\n\n![image-20240108211049140](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108211049140.png)\n\n\n\n踩坑点：为啥下面的没有CSS样式呢？原因是因为没有.nojekyll这个文件，不然一些css会被忽略。添加一下再push就好了\n\n![image-20240108211022770](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108211022770.png)\n\n最后，就部署完毕了\n\n![image-20240108214941003](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108214941003.png)\n\n### 配置自定义域名\n\n来自我的最佳实践，直接配置子域名，别配置4条A记录，没必要，并且域名服务商只允许添加5条，多了就得加钱了。\n\n在自己的域名服务商那里添加一条CNAME记录，直接指向自己的github分配的域名就好了，另外需要把这个base给注释掉（不然css文件和页面都找不到），等待分配完成。\n\n![image-20240108232734898](https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240108232734898.png)\n\n\n\n## 补充\n\n如果你想要配置mermaid支持(这是一个可以使用md语法绘制流程图，饼状图的md扩展),需要按照下面的步骤操作。\n安装\n\n```bash\nnpm i vitepress-plugin-mermaid mermaid -D\n```\n\n如果使用pnpm，还需要下面的配置改变pnpm的默认行为兼容插件\n\n```bash\npnpm install --shamefully-hoist\n# 或者在根目录新建.npmrc文件，配置\nshamefully-hoist=true\n```\n\n更改`.vitepress/config.mjs`配置项\n\n1: 导入\n\n```js\nimport { withMermaid } from \"vitepress-plugin-mermaid\";\n```\n\n\n\n2: defineConfig—\u003ewithMermaid\n\n\u003cimg src=\"https://my-picture-bed1-1321100201.cos.ap-beijing.myqcloud.com/mypictures/image-20240209000231506.png\" alt=\"image-20240209000231506\" style=\"zoom:33%;\" /\u003e\n\n3:根配置项下添加\n\n```js\n mermaid: {\n    // refer https://mermaid.js.org/config/setup/modules/mermaidAPI.html#mermaidapi-configuration-defaults for options\n  },\n mermaidPlugin: {\n    class: \"mermaid my-class\", // set additional css classes for parent container\n  },\n```\n\n可以访问[插件官网](https://emersonbottero.github.io/vitepress-plugin-mermaid/guide/getting-started.html)和[mermaid官网](https://mermaid.js.org/config/setup/modules/mermaidAPI.html#mermaidapi-configuration-defaults for options)获取更多配置信息\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazcodingaccount%2Fmy-docs-website","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazcodingaccount%2Fmy-docs-website","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazcodingaccount%2Fmy-docs-website/lists"}