手把手教你用vuepress搭建自己的网站(1)

(https://coder.itclan.cn/)

前言

如果说阅读是知识的输入,那么写作就是知识的输出,输出是一个内化知识理解的过程,有些知识,一问,知道,一动手,不会,看似简单,一看就会,一做就废,凡是不被自己吸收,为自己所用的,都只能称作为做信息,而不能视作为知识.

记录就像是复盘,迭代自己,不断试错,反馈. 无论是前端还是后端,甚至是其他,多动手,多实践才是真理

几大建站技术比较

每一个技术的涌现,受人追捧,必然有着它令人着迷之处,相比于jekyll,Hexo,GitBook,Nuxt,Docsify/Docute,以及现在的vuepress,而不久前尤大又多了个兄弟vitePress,它们都是一种静态网站生成器,各有特点,没有好坏,都有自己适宜的应用场景

技术永远都是在不断更新迭代,越来越进步

简单做一下对比

Jekyll

特点:Github 自带的,您不用部署静态页面,您只要往 GitHub 上推 md文件就能产生 blog

问题:

• 当 md 文件多了之后,排序是一个很头疼的问题,纯体力手工劳动,无法实现自动化,速度很是极具考验
• 后端基于 Ruby 语言
• 我早期的博客就是用 jekyll 搭建的,但是后来因为管理确实麻烦,就没打理了的Jekyll 官方文档 http://jekyllcn.com/

Hexo

特点:比Jekyll要先进一点,先生成文件,在部署

• 基于Node.js的静态网站生成器
• 主题很丰富,在vuepress之前很多博客,文档网站都是基于Hexo搭建的,是用jekyll还是Hexo搭建的,基本上做 IT 的小伙伴,也能辨别出来

问题:

每次都需要把生成的静态页面推上去,md 若出现错误,编译会出错,配置的不是特别灵活Hexo 官方文档 https://hexo.io/

GitBook

问题

默认主题有限制,随着文档的增加,每次加载的时间会很长,也不是 Vue 驱动的 官方团队专注于打造一个商业产品,而并非开源工具

• GitBook 官方文档 https://www.gitbook.com/

Docsify-Docute

• 两者都是基于Vue,在运行时驱动
• Docsify由于只用于解析Markdown文件并生成网站,不会生成静态 html 文件,所以它是不利于搜索引擎,百度,谷歌等是难以被收录的,即使做了网站统计,也很爬取到你的内容,但是简单,你只需专注 md 编写就可以
• Docute,是Docsify的升级,没有构建过程,将 md文件呈现为单页面应用程序,会生成静态HTML,对 SEO很友好,利于百度蜘蛛的抓取
• Docsify官方文档,
• Docute 官方文档https://docute.org/#what-is-docute

Nuxt

更偏向于构建应用程序,SSR 服务端渲染框架,适合构建复杂的系统应用程序,对于开发人员要求是有门槛的,如果自己只专注于内容创作,而耗费精力去搭建一个静态博客,个人觉得,有种大材小用

• Nuxt官方文档 https://zh.nuxtjs.org/

比较

• 阅读体验上:gitBook > Docsify/Docute = vuepress = HEXO > Jekyll
• 配置上:Jekyll == Docsify< Docute < Hexo < vuepress,其中Jekyll 和 Docsify配置是最简单的,如果只用于专注内容创作,挺合适的,但是功能很弱,拓展性差
• 性能/seo 上:VuePress是最好的,虽然 docsify,docute都是基于 vue,但是他们是在运行时解析,而 vuepress是预先解析 HTML,体验上会更好,而用Docsify搭建的网站,是很难被浏览器,搜索引擎录取的,百度,谷歌抓取不到,无人问津状况
• 灵活上: Vuepress更加灵活,可实现定制化,网站风格并非千篇一律,熟悉Vue组件化开发的,上手也不难
• 代码上: 文件结构非常清晰,可维护性,可拓展性好

为什么推荐选择-VuePress

VuePress

• Vue 驱动,强大的插件生态系统,官方文档详细
• 支持搜索引擎优化(SEO),单页面应用,按需加载,支持 PWA(无网络情况下照样能访问)
• 为技术文档而优化内置 markdown 拓展
• 在md(Markdown) 中可以写vue组件,甚至写原生JS,Ts,HTML,CSS`,无任何压力阻碍,更加的灵活,可定制化
• 可以自定义开发主题,任意修改,网站风格不在千篇一律
• 支持 PWA(自动生成 Service Worker),像 app 应用一样添加到手机桌面上
• 集成了 Google Analytics 集成,也支持百度统计
• 基于 git 的最后上传更新时间
• 支持国际化,多语言,只需配置一下就好
• 响应式布局,手机端,PC 端网站友好的用户体验

远不止于用来搭建博客,可以开发公司企业官网等网站应用,也可结合boostrap,Element UI等技术进行二次开发,构建更复杂的应用....

vuepress 官方文档-https://www.vuepress.cn/

注意

1. 目前VuePress版本并没有支持 typescript，并且没有提供类型定义,但如果想要用TS,可以安装vuepress-plugin-typescript插件,它提供了在 VuePress中使用 typescript 的部分能力。如果你想获取到正确的类型定义，你可以配合 vuepress-types一起使用
2. vuepress-types作为VuePress的类型定义包，还处于实验阶段
3. 具体使用,可参考文档vuepress-plugin-typescript 使用文档,可以去尝试一下,这个不仅仅可以写Ts,在md也可以写TypeScript

在自己用 VuePress搭建网站的过程中,从零开始,一行行代码的配置,编写,以及考虑代码模块化的拆分,维护性,可实现按需定制化,到最终部署上线,自定义域名等,在这个过程中,踩了很多坑

当然,也借鉴了不少网上的博客,但很多不是把配置写死,就是代码拓展性极其受限,而且每个人遇到的问题都是不一样的,而官方文档 VuePress的 API琳郎满目,对于新手小白,的确眼花缭乱,不知从何看起,配着配着就晕了的

而很多博客,大佬,基本上都是基于一个模板,有很多坑并没有提及

官方文档只适合查阅,也并不适合从头看到尾,不用每个 API 都熟记于心,你只需要知道怎么去查,在哪个地方找就可以了的

VuePress 的配置的确复杂,比较零散,但并非令人望而却步,一旦你掌握了套路后,就会欣赏它的独特,配置选项虽然多,但是它的结构非常清晰

本篇文章有些长,建议一步步的按阶段完成,有些配置你不必知道原因,你只需要知道按照官方文档那么配置,能出来,达到你想要的效果就可以了,至于内部原理,富有闲于时,可自行探索,不必深究

也不要一上来,就去折腾自定义主题,看到酷炫花销的博客,就立马想搞一个出来

一个能吸引到你的网站,让你停留片刻,收藏,点赞,转发,三连击的,起决定性作用,并非是你的 UI,而是你网站所提供的内容服务,如果一味的追求 UI 效果,却忽略建站的初衷,就有些本末倒置了

先把官方默认的主题,玩熟悉了,在去玩自定义主题,以及进行二次开发,都是可以的

口说无凭,话说多了,都是故事,下面一步步带你从零开始,到域名部署等,搭建属于自己的网站,开始自己的记录之旅.

你可前往https://coder.itclan.cn/(还在完善当中,如果有不足bug,谢路过的童鞋指正)

前提准备

安装NodeJs

• 下载NodeJs,并安装到本地,下一步,下一步,即可安装
• 检测 NodeJs 是否安装成功,可在命令行终端输入node -v,同时查看一下 npm 的版本npm -v(在安装 Node 完后,npm 是自动就安装上了的,集成在了Node运行坏境里)

C:\Users\itclancoder>node -v
v12.18.0
C:\Users\itclancoder>npm -v
6.14.4

警告

请确保你的 Node.js 版本 >= 8

NodeJs 下载地址:(NodeJS-长期支持版下载)

• 安装git bash:用于向 github 提交代码,虽然cmd或者power Shell都可以,但还是建议使用git bash
• git bash 下载地址:git bash
• 熟悉下markdwon语法,不熟悉也没有关系,后续都是用它来写文档,五分钟立马就可以上手,可前往在线练习 markdonw 语法
• vscode 插件商店里安装markdown,markdown Preview插件,也可下载安装Typora软件到本地编写md

项目搭建

全局安装-vuepress

• 命令行(cmd/git bash)终端下全局安装vuepress

yarn global add vuepress # 或者:npm install -g vuepress 或者cnpm install -g vuepress

警告

• 若是使用 yarn 安装,需要先全局安装 yarn(npm install -g yarn),yarn 使用官方文档
• 若是使用 npm 全局安装,请确保你的 Node.js 版本 >= 8
• 如果你的现有项目依赖了 webpack 3.x，推荐使用 Yarn而不是npm 来安装VuePress。因为在这种情形下，npm会生成错误的依赖树

初始化项目

在你的电脑某个磁盘下创建一个项目目录:mkdir itclan,这个是文件夹名字是任意的

mkdir itclan
cd itclan

进入itclan 文件夹后,在cmd或git bash终端下,使用npm init -y,或yarn init -y初始化,会自动生成一个package.json文件

yarn init -y 或 npm init -y

经过yarn init -y后,会生成一个package.json文件,内容如下所示

{
  "name": "itclan",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
}

紧接着，在 package.json里加一些脚本,配置启动命令

"scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }

警告

当 package.json 配置成这种格式时,在当前文件下,启动时使用npm run docs:dev,启动项目,而打包构建时,使用npm run docs:build

这个也可以简化成

"scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  }

警告

当package.json配置成这种格式时,在当前文件下,启动时可以使用npm run dev,启动项目,而打包构建时,使用npm run build如果是使用 yarn 方式启动和构建项目:可以使用yarn dev启动项目,而使用yarn build构建项目

• 启动项目: npm run docs:dev这条命令相当于vuepress dev docs
• 打包项目: npm run build这条命令相当于 vuepress build docs

在接着,创建docs目录, 这个docs文件夹主要用于放置我们写的.md类型的文章以及.vuepress相关的配置,这个文件夹的名字你可以任意,与你启动项目和构建项目时的配置保持一致就可以了的

mkdir docs

进入docs文件夹中使用mkdir命令创建.vuepress文件夹,注意这个文件夹的名字时固定的,不要随便改变

cd docs
mkdir .vuepress

这个.vuepress主要就是我们用于存放全局的配置、组件、静态资源等与VuePress相关的文件配置都将会放在这里

具体更详细配置说明可见官网:基本配置 具体更详细的目录树结构说明:目录结构 至此,项目大体已经搭建完成了,接下来,主要就是一些配置

限于篇幅所致,更多配配置见后文...