Loading...
墨滴

望北川

2021/08/06  阅读:101  主题:全栈蓝

利用 Vuepress 搭建一个精美好看的静态博客

大家好,我是小维。

我们在程序开发的过程中,常要给自己的程序写一套配套的技术文档。记录接口,函数名,参数等等,方便后期开发及第三方开发。

网上有很多文档编写网站及工具,比如看云、语雀、石墨等等。但这些绝大部分都是需要付费,不能自己DIY。

为了提高开发效率,我推荐使用VuePressVue驱动的静态网站生成器,生成的网页内容放到自己服务器上管理,可用于遍写技术文档个人博客

介绍

官网:https://vuepress.vuejs.org/zh/

VuePress 由两部分组成:第一部分是一个极简静态网站生成器 (opens new window),它包含由 Vue 驱动的主题系统插件 API,另一个部分是为书写技术文档而优化的默认主题,它的诞生初衷是为了支持 Vue 及其子项目的文档需求。

每一个由 VuePress 生成的页面都带有预渲染好的 HTML,也因此具有非常好的加载性能和搜索引擎优化(SEO)。同时,一旦页面被加载,Vue 将接管这些静态内容,并将其转换成一个完整的单页应用(SPA),其他的页面则会只在用户浏览到的时候才按需加载。

它是如何工作的?

事实上,一个 VuePress 网站是一个由 Vue (opens new window)Vue Router (opens new window)webpack (opens new window)驱动的单页应用。如果你以前使用过 Vue 的话,当你在开发一个自定义主题的时候,你会感受到非常熟悉的开发体验,你甚至可以使用 Vue DevTools 去调试你的自定义主题。

在构建时,我们会为应用创建一个服务端渲染(SSR)的版本,然后通过虚拟访问每一条路径来渲染对应的HTML。这种做法的灵感来源于 Nuxt (opens new window)nuxt generate 命令,以及其他的一些项目,比如 Gatsby (opens new window)

准备环节:

工具1:安装nmp环境

下载地址:https://nodejs.org/en/(这里就不详细讲了,网上也有很多教程)

工具2:这边建议安装Git命令窗口。

官方下载很慢,之前有篇文章记录到咱们用淘宝的镜像站下载Git软件:https://blog.isww.cn/index.php/archives/462/

当然,如果你嫌麻烦,也可以使用电脑自带的cmd(电脑Win+R 输入cmd即可唤起命令窗口)

验证是否安装成功:

命令窗口输入:node -vnpm -v 安装成功了的话会显示软件版本。

一、快速开始

1、安装

npm install -g vuepress  // 或者 yarn global add vuepress

2、新建一个项目文件夹,并且初始化

// 创建一个目录 叫 myblog
mkdir myblog
// 进入这个目录
cd myblog
// 初始化项目
npm init -y

3、创建博客相关目录

在myblog目录下新建docs目录,在docs目录里新建.vuepress文件夹,然后在里面创建config.js文件 用于存放配置信息

module.exports = {
  title: '小维博客',
  description: '欢迎来到我的博客'
}

4、在docs目录里面创建一个README.md的文件,输入内容

---
home: true
heroImage: /hero.png
actionText: 快速上手 →
actionLink: /zh/guide/
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构,以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验,在 Markdown 中使用 Vue 组件,同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML,同时在页面被加载的时候,将作为 SPA 运行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---

5、运行博客

package.json里面添加脚本

"scripts": {
    "test""echo \"Error: no test specified\" && exit 1",
    "dev""vuepress dev docs",
    "build""vuepress build docs"
}

然后在终端(命令行工具)输入启动命令

npm run dev

二、设置导航栏

基础设置

module.exports = {
  themeConfig: {
    nav: [
      {
        text: 'Languages',
        items: [
          { text: 'Chinese', link: '/language/chinese' },
          { text: 'Japanese', link: '/language/japanese' }
        ]
      }
    ]
  }
}

我的nav配置

nav: [
    { text: "首页", link: "/" },
    { text: "基础教程", link: "/basics/" },
    { text: "项目实战", link: "/project/" },
    { text: "零散文章", link: "/article/" },
    { text: "一起学习", link: "/association/" },
    { text: "前端架构师", link: "/architect/" },
    { text: "小维博客", link: "https://blog.isww.cn/" }
]

对应上面的导航栏,我们需要在docs文件夹下去新建basics、project、article、association、architect等文件夹

三、侧边栏设置

.
├─ README.md
├─ contact.md
├─ about.md
├─ foo/
│  ├─ README.md
│  ├─ one.md
│  └─ two.md
└─ bar/
   ├─ README.md
   ├─ three.md
   └─ four.md

配置:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: {
      '/foo/': [
        '',     /* /foo/ */
        'one',  /* /foo/one.html */
        'two'   /* /foo/two.html */
      ],

      '/bar/': [
        '',      /* /bar/ */
        'three', /* /bar/three.html */
        'four'   /* /bar/four.html */
      ],

      // fallback
      '/': [
        '',        /* / */
        'contact', /* /contact.html */
        'about'    /* /about.html */
      ]
    }
  }
}

四、head配置和自定义样式

静态文件要放到.vuepress/public目录下

// 添加浏览器图标
head: [
    ["link", { rel: "icon", href: "/logo.png" }],
]

自定义样式可以放到.vuepress/styles/index.style

.theme-default-content 
  h1
    border-bottom  3px solid rgb(0, 172, 193)
    padding 20px 0px 20px 0px
    font-size 24px

 
.theme-default-content 
  h2
    border-bottom  2px solid rgb(0, 172, 193)
    padding 15px 0px 15px 0px;
    font-size 20px
 
.theme-default-content 
  p 
    margin: 15px 0px 15px 0px;


/* PrismJS 1.17.1
https://prismjs.com/download.html#themes=prism-okaidia&languages=markup+css+clike+javascript */
/**
 * okaidia theme for JavaScript, CSS and HTML
 * Loosely based on Monokai textmate theme by http://www.monokai.nl/
 * @author ocodia
 */

code[class*="language-"],
pre[class*="language-"] {
 color: #f8f8f2;
 background: none;
 text-shadow: 0 1px rgba(0, 0, 0, 0.3);
 font-family: Consolas, Monaco, 'Andale Mono''Ubuntu Mono', monospace;
 font-size: 1em;
 text-align: left;
 white-space: pre;
 word-spacing: normal;
 word-break: normal;
 word-wrap: normal;
 line-height: 1.5;

 -moz-tab-size: 4;
 -o-tab-size: 4;
 tab-size: 4;

 -webkit-hyphens: none;
 -moz-hyphens: none;
 -ms-hyphens: none;
 hyphens: none;
}

/* Code blocks */
pre[class*="language-"] {
 padding: 1em;
 margin: .5em 0;
 overflow: auto;
 border-radius: 0.3em;
}

:not(pre) > code[class*="language-"],
pre[class*="language-"] {
 background: #272822;
}

/* Inline code */
:not(pre) > code[class*="language-"] {
 padding: .1em;
 border-radius: .3em;
 white-space: normal;
}

.token.comment,
.token.prolog,
.token.doctype,
.token.cdata {
 color: slategray;
}

.token.punctuation {
 color: #f8f8f2;
}

.namespace {
 opacity: .7;
}

.token.property,
.token.tag,
.token.constant,
.token.symbol,
.token.deleted {
 color: #f92672;
}

.token.boolean,
.token.number {
 color: #ae81ff;
}

.token.selector,
.token.attr-name,
.token.string,
.token.char,
.token.builtin,
.token.inserted {
 color: #a6e22e;
}

.token.operator,
.token.entity,
.token.url,
.language-css .token.string,
.style .token.string,
.token.variable {
 color: #f8f8f2;
}

.token.atrule,
.token.attr-value,
.token.function,
.token.class-name {
 color: #e6db74;
}

.token.keyword {
 color: #66d9ef;
}

.token.regex,
.token.important {
 color: #fd971f;
}

.token.important,
.token.bold {
 font-weight: bold;
}
.token.italic {
 font-style: italic;
}

.token.entity {
 cursor: help;
}

五、部署上线

我们将代码部署到Coding上,需要完成的步骤有:

1、注册一个coding账号 官网coding.net

2、为coding生成一个ssh公钥

3、编写脚本将代码自动上传到coding

4、开启coding静态page服务,绑定私有域名

生成ssh的过程:

1、进入到自己home目录下的.ssh目录,如果没有就自己新建一个

windows一般在这个位置: C:\Users\用户名\.ssh  
Mac: ~\.ssh

2.生成ssh key,在终端执行命令

# "-t rsa"表示使用密钥的加密类型,还可以为dsa;-C设置注释文字,
比如你的邮箱“YourEmail”,不一定要是github注册邮箱

$ssh-keygen -t rsa -C "${YourEmail}"                                    

# 直接回车
Enter file in which to save the key (/Users/faner/.ssh/id_rsa): 
# 输入密钥文件授权密码
Enter passphrase (empty for no passphrase):  
# 确认密钥文件授权密码                        
Enter same passphrase again:                                           
Your identification has been saved in /Users/faner/.ssh/id_rsa.
Your public key has been saved in /Users/faner/.ssh/id_rsa.pub.

生成好以后,你需要将你.ssh目录下的.pub文件打开,里面有公钥,你需要把这个公钥配置到coding上面。

接下来,需要在.ssh里面新增一个config文件,文件配置格式如下:

# Host自己填一个名称 不要带中文就行
Host isww
# 这里是网站地址
HostName e.coding.com
# github对应的email或者用户名
User git
# coding对应的私钥
IdentityFile ~/.ssh/id_rsa_isww_github_io

3.编写一个deploy.sh的脚本

实现脚本一键更新渲染博客内容。

#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run build

# 进入生成的文件夹
cd docs/.vuepress/dist

# 如果是发布到自定义域名
echo '这里填你需要绑定的域名' > CNAME


git init
git config user.name "这里填你coding的名字"
git config user.email "这里填你coding的邮箱"
git add -A
git commit -m 'deploy-coding'

# 如果发布到 https://<USERNAME>.github.io
# git push -f git@dadifeihong:dadifeihong/dadifeihong.github.io.git master

# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages
git push -f git@dadifeihong-coding:dadifeihong/nodeingfe.git master
cd -

平时需要用到的命令:

启用本地测试:vuepress dev docs

生成本地静态网页网页:vuepress build docs

运行脚本上传网页静态文件:bash deploy.sh

六、成品展示

文章采用markdown语法,部分展示样式需要安装官方文档编写。

以下是我之前给自己网站写的一些教程文档,就那么几页,数都数得过来,哈哈。。。

官方还提供了主题开发,插件开发文档介绍,非常贴心。

教程到此结束!

我是小维,原创不易,如果觉得文章还不错的话,希望 点赞 + 在看 支持下,给俺点创作动力。

望北川

2021/08/06  阅读:101  主题:全栈蓝

作者介绍

望北川