作者:maomincoding 来源:前端历劫之路
说起文档,我们可能会第一时间会想起很多技术文档,比如Vue.js文档、React.js文档、TypeScript文档,它们都有相似的布局和样式。
那么,作为开发者的我们,怎么不也搞一个类似于技术文档的网站作为自己的博客呢?现在有很多开源的项目可以做博客,比如基于Vue.js开发的Vuepress以及同一家的Vitepress,还有基于React.js开发的Docusaurus。这么多方案,我们今天就拿Vuepress为例来搞一下线上可以访问的博客。
在开始实战之前呢!透露一下最近在搞得开源库Strve.js,它是一个可以将字符串转换为视图的JS库,换句话讲,也可以说是一款轻量的MVVM框架。目前Strve.js官方文档就是用的基于Vuepress来进行开发部署的,感兴趣的可以访问下方的官方文档源码地址,可以根据我的来进行自定义配置自己的博客网站。如果觉得不错的话,别忘了帮忙点个Star啊!
Strve.js官方文档源码地址
https://github.com/maomincoding/strvejs-doc
Strve.js官方文档
https://maomincoding.github.io/strvejs-doc/
自己亲身实战所攒下的经验,请认真往下看哦!
学习一个新技术,我们首先做得事就是打开官网文档,根据快速上手或者指南来进行大致的了解。
打开Vuepress官网:
https://vuepress.vuejs.org/zh/
官网上怎么安装Vuepress项目已经很详细了,这里就不再阐述,可以根据快速上手快速搭建一个Vuepress项目。
https://vuepress.vuejs.org/zh/guide/getting-started.html
一般搭建完成之后,会显示以下目录结构:
.
├── docs
│ ├── .vuepress (可选的)
│ │ ├── components (可选的)
│ │ ├── theme (可选的)
│ │ │ └── Layout.vue
│ │ ├── public (可选的)
│ │ ├── styles (可选的)
│ │ │ ├── index.styl
│ │ │ └── palette.styl
│ │ ├── templates (可选的, 谨慎配置)
│ │ │ ├── dev.html
│ │ │ └── ssr.html
│ │ ├── config.js (可选的)
│ │ └── enhanceApp.js (可选的)
│ │
│ ├── README.md
│ ├── guide
│ │ └── README.md
│ └── config.md
│
└── package.json
假设你已经在第一步中成功搭建起了项目,并且成功启动。下面,我们将会改改代码看下都是什么效果。
首先,我会看下这个文件doc > README.md,这个文件你可以把它理解成首页。
.
├─ docs
│ ├─ README.md
以Strve.js文档首页为例:
---
home: true
heroImage: /logo.png
heroText: Strve.js
tagline: 一个可以将字符串转换为视图的JS库
actionText: 快速上手 →
actionLink: /zh/started/
features:
- title: ⚡️ 快速地
details: 超快的虚拟 DOM。
- title: 空间小
details: 源代码文件大小仅仅4kb。
- title: 灵活地
details: 易于灵活地拆装不同的代码块。
footer: MIT Licensed | Copyright © 2021-present maomincoding
上面的格式是Front Matter,可以根据官方文档进行详细配置。
https://vuepress.vuejs.org/zh/theme/default-theme-config.html#首页
那么下面你需要关注的是Vuepress配置文件——config.js。
.
├─ docs
│ └─ .vuepress
│ └─ config.js
同样,拿Strve.js官网文档为例:
module.exports = {
base: '/strvejs-doc/', // /site/strvejs/
title: 'Strve.js',
description: 'A JS library that can convert strings into view',
head: [
['link', { rel: 'icon', href: '/logo.png' }],
],
markdown: {
lineNumbers: true
},
locales: {
'/': {
lang: 'en-US',
title: 'Strve.js',
description: 'A JS library that can convert strings into view'
},
'/zh/': {
lang: 'zh-CN',
title: 'Strve.js',
description: '一个可以将字符串转换为视图的JS库'
}
},
themeConfig: {
displayAllHeaders: true,
sidebar: 'auto',
sidebarDepth:4,
nav: [
{ text: 'GitHub', link: 'https://github.com/maomincoding/strve' }
],
locales: {
'/': {
selectText: 'Languages',
label: 'English',
ariaLabel: 'Languages',
sidebar: [
{
title: 'Introduce',
path: '/introduce/',
},
{
title: 'Install',
path: '/install/',
},
{
title: 'Started',
path: '/started/',
},
{
title: 'Usage',
path: '/usage/',
},
{
title: 'Tool',
path: '/tool/',
},
{
title: 'Other',
path: '/other/',
}
],
},
'/zh/': {
selectText: '选择语言',
label: '简体中文',
sidebar: [
{
title: '介绍',
path: '/zh/introduce/',
},
{
title: '安装',
path: '/zh/install/',
},
{
title: '快速上手',
path: '/zh/started/',
},
{
title: '使用',
path: '/zh/usage/',
},
{
title: '工具',
path: '/zh/tool/',
},
{
title: '其它',
path: '/zh/other/',
}
],
}
},
smoothScroll: true
}
}
看到这些配置不要慌,都可以从官方文档配置选项中可以找到。
https://vuepress.vuejs.org/zh/config/
其次,需要重点说明的是我这里/和/zh是提供了多语言支持配置路径,可以通过官方文档的多语言支持选项进行配置。
我之所以很简单地概括前面的步骤,是因为官网文档讲解的比我更明白更详细,我也不想浪费大家的时间。
下面,我们就要开始部署。在部署打包之前呢!我们首先要注意的是配置文件,我们回到之前的配置文件。
我们需要注意的是base选项,
module.exports = {
base: '/strvejs-doc/',
title: 'Strve.js',
description: 'A JS library that can convert strings into view',
head: [
['link', { rel: 'icon', href: '/logo.png' }],
]
}
打开package.json文件。
{
"name": "strvejsdoc",
"version": "1.0.0",
"description": "Strve.js document address",
"main": "index.js",
"license": "MIT",
"private": false,
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs"
},
"devDependencies": {
"vuepress": "^1.8.2"
}
}
我们看到"scripts"属性下有"build"指令。运行打包即可。
打包后,默认会打包到dist文件夹中,你可以把文件夹中的内容放到线上网站上去,如果没有网站,也没有关系。本篇文章就是让每个前端都拥有一个属于自己的博客线上网站。
.
├── docs
│ ├── .vuepress
│ │ ├── dist
我们会用到GitHub,所以需要创建一个仓库,名字可以起一个好记的。我这里因为是以Strve.js为例,所以名为strvejs-doc。然后你需要做的是使用SSH方式Clone下来。
如果没有配置SSH的可以根据我下面的步骤操作一下。
切换到 .ssh目录
cd ~/.ssh
浏览文件夹目录
ls
输入你的邮箱(邮箱不必与GitHub账号相同,个人邮箱即可),然后一直回车
ssh-keygen -t rsa -C "邮箱"
自动启动
eval "$(ssh-agent -s)"
添加文件
ssh-add ~/.ssh/id_rsa
查看 id_rsa.pub 文件的内容,复制一下,留存。
cat id_rsa.pub
下面,我们就要打开Github,点击右上角个人头像下拉菜单中的Settings选项,然后点击左边栏的SSH and GPG keys选项。
点击 New SSH key 按钮。
输入Title 下的内容,这里随便起一个好记的标题。
然后输入Key 下的内容,把刚才保存的id_rsa.pub 文件的内容复制到里面。
现在,大功告成!
以后,你只需要复制项目仓库中 Clone按钮下的 SSH 选项框中的链接。
然后,Clone 这个链接即可。
Clone 下仓库之后,然后可以把刚才Vuepress项目导入进去。
最后,Push一下。
首先,我们需要创建一个分支,比如命名pages。然后,打开GitHub远程仓库,点击项目仓库Tab栏上的Settings选项,然后点击Pages选项。
最后,在Source下选择刚才创建的pages分支,然后选择/(root),点击Save保存按钮。
不出意外,上方会给出一个网址,这里我们先保存一下,待会配置完成我们再点击浏览网址。
在项目根目录下创建一个deploy.sh文件,编辑如下内容:
#!/usr/bin/env sh
set -e
npm run build
cd docs/.vuepress/dist
git init
git add -A
git commit -m 'deploy'
# 如果发布到 https://<USERNAME>.github.io/<REPO>
git push -f git@github.com:<USERNAME>/<REPO>.git master:pages
cd -
这里你需要自定义的是:USERNAME、REPO、master:pages,分别对应用户名、仓库名、(一般是master:分支名或者main:分支名)。
我们在package.json文件中定义一个调试命令。
"scripts": {
"sh":"bash deploy.sh"
}
然后运行此命令。
最后,我们在浏览器上打开刚才的网址。
以后,每次更改文档,只需一条命令,即可更新线上网站。
自动化部署还有别的方案比如Github中的Actions,这里就不再详细介绍了。赶快来试试上面的方案吧!部署一个属于自己的博客。