开启掘金成长之旅!这是我参与「掘金日新计划 · 12 月更文挑战」的第1天,点击查看活动详情
一.网站概述
个人站点页面:
支持PC和wap自适应
lighthouse报告:
本文将详细介绍个人网站的搭建的完整流程,主要分为两部分,
- vitepress配置,
- github actions设置。
相信看完一定有所收获。
二. vitepress
vitepress
是由vite
的核心开发成员,Evan You 创建,基于vite
提供极速的hmr
能力和快速的服务器启动。配置也十分简单,几乎只用书写markdown
,就能搭建一个高性能的网站。
注意:截止目前,
vitepress
依然没有发布正式版本,当前最新版本是1.0.0-alpha.29
。不建议使用在特别正式的环境。
当然个人用用问题不大。
1.vitepress最佳实践
一般去学习一个新东西,往往会先去看它的官网:
但由于它的中文文档已经长达一年多不更新。英文文档虽然更新的很快,但有些部分仍然在编写中。所以最佳实践是,找一个比较 有名气 且是用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.ts
进行配置
目录结构如下
配置config.ts
的内容
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
安排的链接,就可以看到页面啦
已经添加MIT
协议,可以随便使用,欢迎star
,issue
,pr
,互相学习,一起进步~