本文主要是介绍【教程】使用vitepress搭配githubPages构建自己的在线笔记,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!
1. 创建VitePress项目
确保自己已经安装好了node,我这个笔记用的是node 18.16.0,
怎么安装nvm这个可以csdn或者掘金,再或者等我有空了我就更新一下
- 使用nvm安装node
# 查看可用版本
nvm list avaliable
# 安装node
nvm install 18.16.0
# 切换node
nvm use 18.16.0
- 创建vitepress项目
# 首先全局安装vitepress
npm install -D vitepress
# 创建一个项目文件夹
mkdir notes
cd notes
# 使用vitepress自带的npx初始化
npx vitepress init
- 配置vitepress
┌ Welcome to VitePress!
│
◇ Where should VitePress initialize the config?
│ ./docs
│
◇ Site title:
│ notes(你的项目名称)
│
◇ Site description:
│ 后端仔的笔记(你的项目介绍)
│
◇ Theme:
│ Default Theme
│
◇ Use TypeScript for config and theme files?
│ Yes
│
◇ Add VitePress npm scripts to package.json?
│ Yes
│
└ Done! Now run npm run docs:dev and start writing.
- 运行
npm run docs:dev
2. 推送项目到github
- 在GitHub创建一个项目
- 给当前文件夹配置远程仓库
# 在项目的根目录初始化git
git init
# 添加远程仓库地址
git remote add origin git@github.com:youname/notes.git
- 在项目根目录创建
.gitignore
文件
/node_modules/
/.idea/
- 提交代码到远程仓库
# 检查文件状态
git status
# 添加文件被git管理
git add *
# 提交
git commit -m 初始化提交
# 推送远程
git push origin
3. 创建github部署脚本
最终要在GitHub的Pages展示的所以创建一个部署脚本,参考十分钟使用vitepress+github action+gitee pages 搭建你的专属文档
- 在项目根目录创建
.github/workflows
文件夹,然后在这个文件夹下创建deploy.yml
因为我不需要gitee的Pages所以下边的配置就被我删除了
name: Deploy VitePress site to Pageson:push:# 推送任意tags或者master分支推送的时候触发任务tags:- '*'branches:- masterworkflow_dispatch:jobs:deploy-and-sync:runs-on: ubuntu-lateststeps:- name: Checkout 🛎️uses: actions/checkout@v4with:ref: 'master'- name: Install yarnrun: corepack enable- uses: actions/setup-node@v3with:node-version: '18'cache: 'yarn'- name: Install dependenciesrun: yarn install- name: Build Siterun: npm run docs:build# 将文档产物提交到gh-pages分支- name: Deploy for Github 🚀uses: JamesIves/github-pages-deploy-action@v4.4.1with:branch: gh-pagesfolder: docs/.vitepress/dist# enable single-commit to reduce the repo sizesingle-commit: trueclean: true# - name: Sync to Gitee
# uses: wearerequired/git-mirror-action@v1.2.0
# env:
# SSH_PRIVATE_KEY: ${{ secrets.GITEE_RSA_PRIVATE_KEY }}
# with:
# # GitHub 仓库地址
# source-repo: git@github.com:chargeduck/notes.git
# # Gitee 仓库地址
# destination-repo: git@gitee.com:chargeduck/notes.git
#
# - name: Build Gitee Pages
# uses: yanglbme/gitee-pages-action@main
# with:
# # 替换为你的 Gitee 用户名
# gitee-username: chargeduck
# # 注意在 Settings->Secrets 配置 GITEE_PASSWORD
# gitee-password: ${{ secrets.GITEE_PASSWORD }}
# # 注意替换为你的 Gitee 仓库,仓库名严格区分大小写,请准确填写,否则会出错
# gitee-repo: chargeduck/notes
# # 要部署的分支,默认是 master,若是其他分支,则需要指定(指定的分支必须存在)
# branch: gh-pages
- 按照上边的步骤把这个文件提交到github上
4. Pages配置
- 打开github的仓库地址,找到
Settings
,选择Pages
- 在右侧的
Build and deployment
下边的Source
选择Deploy form a branch
- 在下边的
Branch
中选择gh-pages
分支/(root)
默认然后保存即可
5. 遇到的问题
1. 提交之后没有生成gh-pages
分支
第一次是因为
deploy.yml
没有放到.github/workflow
文件夹下
2. 工作流执行错误记录
修改了
deploy.yml
位置正确后还是没有创建gh-pages
分支
点击仓库的Actions
选项,在页面上的All Workflows中找到失败的job
1. Dependencies lock file is not found in /home/runner/work/notes/notes. Supported file patterns: yarn.lock
deploy.yml
中执行了yarn来打包和管理依赖,但是项目里边没有yarn.lock
文件
- 执行命令
yarn install
这个时候我的node版本还是16.0.0
,他报错vite@5.0.10: The engine "node" is incompatible with this module. Expected version "^18.0.0 || >=20.0.0". Got "16.20.0"
再执行
nvm list available
nvm install 18.16.0
nvm use 18.16.0
# 再次执行项目出现 yarn.lock
yarn install
# 把yarn.lock提交到github上
2. The deploy step encountered an error: The process ‘/usr/bin/git’ failed with exit code 128
提示我没有权限,按照上边csdn老哥的步骤。
在 GitHub 项目的
Settings -> Actions -> General
路径下配置Fork pull request workflows from outside collaborators
为Require approval for first-time contributors who are new to GitHub
,将
Workflow permissions
配置为Read and write permissions
。
3.本地正常上传到github上之后没有样式
config.mts
中忘记添加base
export default defineConfig({// 这个要和自己的仓库地址一致base: '/notes/',
})
这篇关于【教程】使用vitepress搭配githubPages构建自己的在线笔记的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!