跳转到主要内容

基于VitePress的静态博客搭建

• 1771 字 • 4 分钟
vitepress

Quick Start

基础环境搭建

此项目基于VitePress搭建，node.js版本要求大于18

官方网站：node.js vitepress

使用pnpm进行包管理

npm install -g pnpm

编写文档

拉取代码

git clone ssh://[USER_NAME]@192.168.10.51:29418/DocWiki.git

初始化环境

仓库中已经配置好依赖项，但是node_modules没有上传，需要本地安装

请直接执行以下命令，将会根据当前目录的pnpm-lock.yaml自动安装依赖（需要联网）

pnpm install

将会输出以下类似内容：

devDependencies:
+ vitepress 1.0.2
+ vitepress-sidebar 1.22.0


   ╭──────────────────────────────────────────────────────────────────╮
   │                                                                  │
   │                Update available! 8.6.5 → 8.15.6.                 │
   │   Changelog: https://github.com/pnpm/pnpm/releases/tag/v8.15.6   │
   │                Run "pnpm add -g pnpm" to update.                 │
   │                                                                  │
   │      Follow @pnpmjs for updates: https://twitter.com/pnpmjs      │
   │                                                                  │
   ╰──────────────────────────────────────────────────────────────────╯

Done in 814ms

安装完成之后，可以在本地开启服务，观看效果

pnpm run docs:dev

然后可以浏览器打开http://localhost:5173/本地项目

添加文档

文档采用MarkDown标记语言编写，详见MarkdDown

本项目目前分为平台维护(platfrom)，应用(soft)，驱动(driver)，分别对应首页下方的三个feature部分，请按照文件内容分类，特定的模块请在soft/modules新建模块文件夹，然后再新建文档

编写文档的时候，浏览器中网页应该会同步更新，可以随意检查效果

上传代码

请按照git正常流程上传代码，不需要走Code Review 流程，请直接上传到服务器即可

git add .
git commit -m ''
git push origin master

发布网站

此项目为编译型项目，需要将Markdown编译为静态的html文件，然后再发布

pnpm run docs:build

编译结果目录为：./docs/build/

同步到服务器

rsync -a --delete  ./docs/build/ root@192.168.10.51:/home/raid10/docwiki_product/

目前使用root账户同步,密码为agold

开发工具

  1. vite & vue开发可以通过VSCode及官方Vue扩展开发
  2. markdown源文件可以通过VSCode中Markdown插件实现，也可以采用其他工具，例如Typora，MarkText等
备注

以下内容为项目搭建基本流程，详细信息可以参见官方指导

初始化项目

添加vitepress

pnpm add -D vitepress

项目初始化

pnpm vitepress init

根据提示初始化项目基本配置：

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  Doc Wiki
│
◇  Site description:
│  A simple document platform
│
◇  Theme:
│  Default Theme + Customization
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
└  Done! Now run pnpm run docs:dev and start writing

然后本地运行项目：

pnpm run docs:dev

然后就可以在浏览器中访问网站http://localhost:5173/

基础配置

配置源文件目录

在config.mts中添加

srcDir: 'src',

插件安装

VitePress官方没有支持sidebar自动生成，需要我们在config.mst中配置sidebar相关属性，不方便使用，因此安装第三方插件来实现自动生成sidebar，插件的官方网址为：VitePress Sidebar

pnpm i -D vitepress-sidebar

目录说明

src目录

此目录是源目录，也就是存放 MarkDown 源文件的目录，因为config.mts中配置了srcDir，因此所有的页面路径都是相对于此目录的。

public目录

此目录要放在源目录中，存放所有没有被 Markdown 引用或者主题等直接引用的文件，编译之后将会保持源文件名字拷贝到编译输出目录的根目录中

此目录的资源要使用根绝对路径来引用，例如public/icon.png需要使用/icon.png来引用

静态资源目录

VitePress项目中所有 MarkDown 源文件都会被编译成Vue组件，交由Vite处理，所有的静态资源应该使用相对路径来引用，所有引用的资源，都会在编译期间复制到输出目录，并使用哈希文件名。

  1. 未使用的资源不会被复制
  2. 小于4kb的资源会使用base64内联在 MarkDown 源文件中。
  3. 所有的静态路径引用，包括绝对路径，要基于源目录(即相对于src目录)

部署

同步到服务器

目前此服务部署到 代码服务器中

ssh 192.168.10.51

创建项目部署位置

mkdir -p /home/raid10/docwiki_product/

然后将本地编译好的项目同步到服务器

pnpm run docs:build
rsync -a --delete  ./docs/build/ root@192.168.10.51:/home/raid10/docwiki_product/

配置apache

进入目录/etc/apache2/sites-available,

创建配置文件：

cp ./000-default.conf ./docwiki.conf

修改配置文件：vi ./docwiki.conf

<VirtualHost 192.168.10.51:8110>
	ServerName 192.168.10.51

	ServerAdmin webmaster@localhost
	DocumentRoot /home/raid10/docwiki_product

	<Directory /home/raid10/docwiki_product>
            AllowOverride none
            Require all granted		
	</Directory>

	ErrorLog ${APACHE_LOG_DIR}/error.log
	CustomLog ${APACHE_LOG_DIR}/access.log combined

</VirtualHost>

修改DocumentRoot Directory配置，指向我们的项目部署位置

ServerName必须填写，Directory中要填写Require部分，否则可能会没有权限

启动服务

cd /etc/apache2/sites-enable
ln -s ../sites-available/docwiki.conf
# 然后重启apache
/etc/init.d/apache2 restart