开启掘金成长之旅！这是我参与「掘金日新计划 · 12 月更文挑战」的第1天，点击查看活动详情

一.网站概述

地址：https://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最佳实践

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

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

比如说vite官网：https://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中的内容
  },

完整的代码参考可以看：https://github.com/chaxus/ran/tree/main/packages/docs

三. 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安排的链接，就可以看到页面啦

完整代码：https://github.com/chaxus/ran/tree/main/packages/docs

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