11-23 02:04 阅读 71

vitepress+github actions搭建SSG

一.网站概述

地址：chaxus.github.io/ran/

个人站点页面：

支持PC和wap自适应

lighthouse报告：

接下来就是分享搭建的过程，主要分为两部分，

vitepress配置，
github actions设置。

二. vitepress

vitepress是由vite的核心开发成员，Evan You 创建，基于vite提供极速的hmr能力和快速的服务器启动。配置也十分简单，几乎只用书写markdown，就能搭建一个高性能的网站。

注意：截止目前，vitepress依然没有发布正式版本，当前最新版本是1.0.0-alpha.29。不建议使用在特别正式的环境。

当然个人用用问题不大。

1.vitepress最佳实践

一般去学习一个新东西，往往会先去看它的官网：

中文官网
英文官方
github地址

但由于它的中文文档已经长达一年多不更新。英文文档虽然更新的很快，但有些部分仍然在编写中。所以最佳实践是，找一个比较 有名气 且是用vitepress搭建的网站，看它的源码，往往就是最佳实践。

比如说vite官网：vitejs.dev/

(1).创建项目

mkdir docs pnpm init 复制代码

查看vite官网的vitepress是哪个版本，使用跟它一样的版本。进入vite的官方仓库，查看项目下的package.json,找到vitepress的版本

pnpm i vitepress@1.0.0-alpha.29 复制代码

(2).查看vite的最佳实践

找到vite项目中的docs目录，查看目录结构

可以一个个点进去看看目录结构，先说下结论，.vitepress是配置文件(必需)。index.md是文档的入口。public是存放静态文件的地方，比如图片。_data里面是核心开发者的信息。其他目录里面都是markdown文件。

(3).配置首页

首先创建index.md，它的内容就是首页，具体配置我们可以参考vite首页，基本就能发现是怎么配置的

--- layout: home title: Vite titleTemplate: Next Generation Frontend Tooling hero:   name: Vite // 网站的左上角标题   text: Next Generation Frontend Tooling // 最中间的文字   tagline: Get ready for a development environment that can finally catch up with you. // 最中间的文字   image:     src: /logo-with-shadow.png // 页面中最大的那个图标，默认地址 /public，放在public中无需写完整路径     alt: Vite   actions: // 对应页面上，vite英文介绍下面的三个按钮     - theme: brand       text: Get Started       link: /guide/           ... // 省略一部分  features: // 页面中下位置的文字介绍   - icon: ????     title: Instant Server Start     details: On demand file serving over native ESM, no bundling required!   - icon: ⚡️     title: Lightning Fast HMR     details: Hot Module Replacement (HMR) that stays fast regardless of app size.   ... // 省略一部分 --- 复制代码

(4).配置导航栏nav和config

那么问题来了，最上方的导航栏是怎么配置的呢。导航栏在.vitepress里面的config.md进行配置目录结构如下

配置config.md的内容

import { defineConfig } from "vitepress"; export default defineConfig({   title: "chaxus",   description: "描述信息",   base: "/ran/", // 部署到github上时访问的根目录   lastUpdated: true, // 页面上展示最后更新的时间   head: [     ['link', { rel: 'icon',  href: '/favicon.ico' }], // 也是放在/public目录中   ],   themeConfig: {     logo: '/home.svg', // 也是放在/public目录中     nav: [ // 页面最上面一行的导航栏       { text: "首页", link: "/" }, // 导航栏名字和目录地址，如果文件名叫index.md可以省略不写，路径只写到目录     ],     // 配置github地址     socialLinks: [{ icon: "github", link: "https://github.com/chaxus/ran" }],     footer: {       message: "Released under the MIT License.",       copyright: "Copyright © 2022-11-11",     },     // 配置从导航栏进去后的侧边栏     sidebar: {       "/ranuts/": [         {           text:'通用函数',           items: [             { text: "过滤对象", link: "/ranuts/functions/" },             { text: "统计执行时间", link: "/ranuts/functions/task/" },           ],         },       ],     },   }, });  复制代码

(5).设置主题

在.vitepress目录下新建theme

我们只需要关心styles目录和index.ts。将styles里的样式全部复制过来

index.ts配置

import DefaultTheme from 'vitepress/theme' import './styles/index.less' import './styles/vars.less' export default {   ...DefaultTheme,   enhanceApp({ app }) {      // 用于过滤一些组件，不重要     app.config.compilerOptions.isCustomElement = (tag) => tag.includes('r-')   } } 复制代码

配置package.json的命令

"scripts": {     "dev": "vitepress dev",     "build": "vitepress build", // 执行后会在.vitepress目录下生成dist目录     "serve": "vitepress serve" // 执行.vitepress目录下dist中的内容   }, 复制代码

完整的代码参考可以看：github.com/chaxus/ran/…

三. github actions配置

1.github的配置

找到项目setting,配置secrets中的actions

其中secrets是在个人设置setting进行设置

2.项目增加actions

新建目录

name: pages-build-site on:    push:  // 有代码push或者merge到main分支时，才进行下面的操作     branches:        - main jobs:   deploy:     runs-on: ubuntu-latest      steps:       - name: Checkout         uses: actions/checkout@v3       - name: Install Node.js         uses: actions/setup-node@v3         with:           node-version: 16       - uses: pnpm/action-setup@v2 // 配置使用pnpm         name: Install pnpm         id: pnpm-install         with:           version: 7           run_install: false              - name: Get pnpm store directory         id: pnpm-cache         shell: bash         run: |           echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT        - uses: actions/cache@v3         name: Setup pnpm cache         with:           path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}           key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}           restore-keys: |             ${{ runner.os }}-pnpm-store-        - name: Install dependencies         run: pnpm install       - name: Build docs         run: pnpm -F docs build       - name: Deploy         uses: peaceiris/actions-gh-pages@v3         with:           github_token: ${{ secrets.RAN_ACTIONS_TOKEN }} // 配置在项目里的secrets           exclude_assets: ''           publish_dir: packages/docs/.vitepress/dist // 需要发布内容的路径 复制代码

上述命令简单来说就是：监听是否push或者merge到main分支，执行我们写好的打包命令pnpm -F docs build, 将指定路径的文件packages/docs/.vitepress/dist发布到一个指定的分支，默认是gh-pages。

如果这时候提交代码到main分支，点开actions能看到

如果有报错，我们还可以点进去看具体的报错情况，进行修改

需要注意下，设置部署网站的分支，因为静态网站的资源都在gh-pages分支上

至此访问github安排的链接，就可以看到页面啦

完整代码：github.com/chaxus/ran/…

已经添加MIT协议，可以随便使用，欢迎star，issue，pr，互相学习，一起进步～

作者：然燃
链接：https://juejin.cn/post/7168799961939722277