对vuepress的认识

前言

还是和昨天写vuepress-theme-vdoing使用体验一样。在边尝试VuePress +Gitee 快速搭建个人博客边写博客的过程中,引出了我对vuepress的认识,而且越写越多,所以干脆也单独拎出来写一章。我复制了其中的vuepress认识,让这篇博客写得更加连贯。

记录的主体内容有三部分:我接触vuepress的过程、vuepress官网摘要、vuepress-theme-vdoing官网摘要。

重新认识vuepress

其实我对vuepress项目感兴趣是因为我用过WordPress。看到这个vuepress的名字的时候我就下意识的认为这是一个使用vue框架的CMS。碰巧我不怎么喜欢WordPress,对vue十分有好感。所以昨天就看了看GitHub上的vuepress-theme-vdoing。还写了vuepress-theme-vdoing使用体验我对博客网站的认识——wsdchong

今天早上看到VuePress +Gitee 快速搭建个人博客,于是打算尝试一下vuepress,在尝试的过程中查找资料,我在CSDN的链接中还找到了vuepress-theme-antdocs和vuepress-creator的作者。我还以为他是vue-theme-vdoing的作者,但是他们的GitHub不同。最后我在vuepress-theme-vdoing的文档库中发现原来还有个vuepress。兜兜转转最后找到了组织。

vuepress:vue驱动的静态网站生成器。以markdown为中心的项目结构,以最少的配置帮助你专注写作。

使用vuepress的过程

既然可以运行又可以部署,那么就可以尝试修改内容了。

我准备尝试的部分是修改。

首先是预期效果。首先参考三个人的博客:Evan’s bloglingze’s blogrestlessMan

Evan’s blog:是vuepress-theme-vdoing的作者。

lingze’s blog:是vuepress-theme-vdoing的使用者。内容精简。

restlessMan:是我参考的那篇文章的vuepress博客。

然后是参考文档。一个是vuepress的官方文档,一个是vuepress-theme-vdoing的文档

vuepress:源头。官方文档更系统准确。

vuepress-theme-vdoing:一个好的使用者。个人文档更便于理解思考。

等我理解文档的意思后,归纳总结关注点。

vuepress理论基础摘要

基础

vuepress的介绍

  • 简洁。以 Markdown 为中心的项目结构,以最少的配置帮助你专注于写作。
  • vue驱动。享受 Vue + webpack 的开发体验,可以在 Markdown 中使用 Vue 组件,又可以使用 Vue 来开发自定义主题。
  • 高性能。VuePress 会为每个页面预渲染生成静态的 HTML,同时,每个页面被加载的时候,将作为 SPA 运行。

vuepress的基本使用

npm install -g vuepress
echo '# hello!' > README.md
vuepress dev
vuepress build
//注意node.js版本>=8.6

vuepress的介绍

VuePress 由两部分组成:第一部分是一个极简静态网站生成器 ,它包含由 Vue 驱动的主题系统插件 API,另一个部分是为书写技术文档而优化的默认主题

每一个由 VuePress 生成的页面都带有预渲染好的 HTML,也因此具有非常好的加载性能和搜索引擎优化(SEO)。这也是每个网站最重要的两点,首先不要卡,然后便于被搜索到。

一旦页面被加载,Vue 将接管这些静态内容,并将其转换成一个完整的单页应用(SPA),其他的页面则会只在用户浏览到的时候才按需加载。这样既节约资源,又响应快。用户体验棒。

vue的工作原理

事实上,一个 VuePress 网站是一个由 Vue Vue Router webpack 驱动的单页应用。

在构建时,vuepress会为应用创建一个服务端渲染(SSR)的版本,然后通过虚拟访问每一条路径来渲染对应的HTML。

vuepress的优势

对比Nuxt:VuePress 能做的事情,Nuxt 理论上确实能够胜任,但 Nuxt 是为构建应用程序而生的,而 VuePress 则专注在以内容为中心的静态网站上,同时提供了一些为技术文档定制的开箱即用的特性。

对比Hexo:Hexo 最大的问题在于他的主题系统太过于静态以及过度地依赖纯字符串。Markdown 渲染的配置也不是最灵活的。

vuepress的目录结构(docs/.vuepress)

  • docs/.vuepress: 用于存放全局的配置、组件、静态资源等。
  • docs/.vuepress/components: 该目录中的 Vue 组件将会被自动注册为全局组件。
  • docs/.vuepress/theme: 用于存放本地主题。
  • docs/.vuepress/styles: 用于存放样式相关的文件。
  • docs/.vuepress/styles/index.styl: 将会被自动应用的全局样式文件,会生成在最终的 CSS 文件结尾,具有比默认样式更高的优先级。
  • docs/.vuepress/styles/palette.styl: 用于重写默认颜色常量,或者设置新的 stylus 颜色常量。
  • docs/.vuepress/public: 静态资源目录。
  • docs/.vuepress/templates: 存储 HTML 模板文件。
  • docs/.vuepress/templates/dev.html: 用于开发环境的 HTML 模板文件。
  • docs/.vuepress/templates/ssr.html: 构建时基于 Vue SSR 的 HTML 模板文件。
  • docs/.vuepress/config.js: 配置文件的入口文件,也可以是 YMLtoml
  • docs/.vuepress/enhanceApp.js: 客户端应用的增强。

vuepress的基本配置

  • 配置文件:所有vuepress相关的文件都将放在.vuepress文件夹。一个 VuePress 网站必要的配置文件是 .vuepress/config.js
  • 主题配置:一个 VuePress 主题应该负责整个网站的布局和交互细节。在 VuePress 中,目前自带了一个默认的主题,它是为技术文档而设计的。同时,默认主题提供了一些选项,让你可以去自定义导航栏(navbar)、 侧边栏(sidebar)和 首页(homepage) 等,详情请参见 默认主题
  • 应用级别配置:由于 VuePress 是一个标准的 Vue 应用,你可以通过创建一个 .vuepress/enhanceApp.js 文件来做一些应用级别的配置,当该文件存在的时候,会被导入到应用内部。

vuepress的markdown拓展

  • header anchors:所有的标题将会自动地应用 anchor 链接,anchor 的渲染可以通过 markdown.anchor 来配置。
  • 链接:网站内部的链接,将会被转换成 `` 用于 SPA 导航。VuePress 支持重定向到干净链接。外部的链接将会被自动地设置。
  • Front Matter:在markdown开头的三条虚线之间,可以设置预定义变量。如title、lang、description、layout、meta等。

在Markdown中使用vue

浏览器的API访问显示

模块语法

使用组件

使用预处理器

脚本和样式提取

内置组件

vuepress的多语言支持

.vuepress/config.js 中提供 locales 选项中设置

vuepress的部署

有许多部署方式。

  1. 文档放置在项目的 docs 目录中;
  2. 使用的是默认的构建输出位置;
  3. VuePress 以本地依赖的形式被安装到你的项目中
  • docs/.vuepress/config.js 中设置正确的 base
  • 创建一个如下的 deploy.sh 文件

vuepress的进阶内容

我暂时省略。

Front Matter:front matter 必须是 markdown 文件中的第一部分,并且必须采用在三点划线之间书写的有效的 YAML。

永久链接:一个永久链接是一个旨在未来很多年里维持不变的 URL,由此产生一个发生链接失效(link rot1 )的可能性较小的超链接。

markdown插槽:VuePress 实现了一套针对 Markdown 的内容分发 API。通过这个特性,你可以将你的文档分割成多个片段,以便于在布局组件中灵活组合。

全局计算属性:在 VuePress 中,内置了一些核心的计算属性 ,以供默认主题 或自定义主题使用。如 s i t e 、 site、 sitepage、 f r o n t m a t t e r 、 frontmatter、 frontmatterlang、 l o c a l e P a t h 、 localePath、 localePathtitle、 d e s c r i p t i o n 、 description、 descriptionthemeConfig

vuepress的配置

基本配置:base、title、description、head、host、port、temp、dest、locales、shouldPrefetch、cache;

styling:palette.styl对默认预设 的样式进行简单的替换;index.styl中可以添加额外样式。

主题:theme用于指定主题、themeConfig用于配置主题;

Pluggable:plugins插件

Markdown:anchor、toc、plugins;

构建流程:postcss、stylus、scss、sass、less、configureWebpack、chainWebpack。

浏览器兼容性:evergreen

设计理念

VuePress 1.x 的设计理念主要体现在:插件化、约定大于配置、合理的优先级管理。

插件化:可以解耦。在过去,当我们遇到一些不太常见的需求时,我们会有一些疑虑:如果我们打算不支持,VuePress 的使用场景也就受到了限制;但如果想要支持它,我们就必须将其写到核心代码库中,并为其单独开设配置的 API。对于维护者来说,除了不利于长久的维护,这有时也会让我们心力交瘁。而解决办法就是插件。

约定大于配置:VuePress 1.0 开始引入一些约定,以减少用户过多的配置压力。对于这一点,最直观的体现是对文档目录结构主题目录结构的约定。

合理的优先级管理:主题开发者和普通的文档用户都具有定义全局的 palettestyletemplatesplugins 的能力。通过设计合理的优先级管理使得它们可以协同工作。

插件

使用插件的目的:使项目尽可能简洁。

使用插件、开发插件、插件的生命周期、option API和Context API我就不赘述了。主要介绍几个常用的官方插件

@vuepress/plugin-active-header-links:页面滚动时自动激活侧边栏链接的插件

back-to-top:顾名思义。回到顶部。

plugin-blog:分类系统让vuepress快速贴文分类、分页功能、客户端API。

plugin-search:用于headers的搜索插件。

除了这些还可以根据Plugins API自己开发插件。

主题

使用主题

使用一个主题和使用一个插件的方式几乎一致。

开发主题

首先在根目录创建一个.vuepress/theme目录,然后创建Layout.vue文件。

获取渲染内容: .md 文件渲染的内容,可以作为一个独特的全局组件 `` 来使用

内容摘抄: markdown 文件中有一个 注释,该注释之前的内容会被抓取并暴露在 $page.excerpt 属性中。

目录结构:随着需求的变化,只有一个布局组件 Layout.vue 可能还不够,你可能想要定义更多的布局组件用于不同的页面

  • theme/global-components: 该目录下的组件都会被自动注册为全局组件。想了解更多,请参考 @vuepress/plugin-register-components
  • theme/components: Vue 组件。
  • theme/layouts: 布局组件,其中 Layout.vue 是必需的。
  • theme/styles: 全局的样式和调色板。
  • theme/templates: 修改默认的模板文件。
  • theme/index.js: 主题文件的入口文件。
  • theme/enhanceApp.js: 主题水平的客户端增强文件。

布局组件

使用插件

网站和页面的元数据:Layout 组件将会对每一个文档目录下的 .md 执行一次,同时,整个网站以及特定页面的元数据将分别暴露为 this.$sitethis.$page 属性,它们将会被注入到每一个当前应用的组件中。

应用配置

主题的配置

plugins

DevTemplate:dev 模式下使用的 HTML 模板路径,默认模板见 这里

SSRTemplate:build 模式下使用的 HTML 模板路径,默认模板见 这里

extend:VuePress 支持一个主题继承于另一个主题。

globalLayout:全局布局组件是负责管理全局布局方案的一个组件

默认主题配置

首页:认的主题提供了一个首页(Homepage)的布局

导航栏:导航栏可能包含你的页面标题、搜索框导航栏链接多语言切换仓库链接,它们均取决于你的配置。

侧边栏:想要使 侧边栏(Sidebar)生效,需要配置 themeConfig.sidebar

搜索栏:通过 themeConfig.searchMaxSuggestions 来调整默认搜索框显示的搜索结果数量

最后更新时间:可以通过 themeConfig.lastUpdated 选项来获取每个文件最后一次 git 提交的 UNIX 时间戳(ms),同时它将以合适的日期格式显示在每一页的底部

上/下一篇链接:自动地根据当前页面的侧边栏的顺序来获取。

git仓库和编辑链接

页面滚动:通过 themeConfig.smoothScroll 选项来启用页面滚动效果。

博客主题

安装:npm install @vuepress/theme-blog -D

使用:

// .vuepress/config.js
module.exports = {
  theme: '@vuepress/blog',
  themeConfig: {
    // 请参考文档来查看所有可用的选项。
  }
}

vuepress基础内容的总结

明白vuepress的定位:一个静态网站生成器。优势是简洁、vue驱动、高性能。

明白vuepress的结构:第一部分是静态网站生成器,另一部分是默认主题docs。

明白vuepress的设计理念:插件化

明白vuepress的目录结构docs/.vuepress和基本配置

明白vuepress的插件和主题

明白vuepress的使用、vuepress主题的使用、vuepress的部署。

//vuepress的使用
npm install -g vuepress
echo '# hello!' > README.md
vuepress dev
vuepress build
//vuepress主题的使用
npm install @vuepress/theme-blog -D
// .vuepress/config.js
module.exports = {
  theme: '@vuepress/blog',
  themeConfig: {
    // 请参考文档来查看所有可用的选项。
  }
}

vuepress的部署

  1. 文档放置在项目的 docs 目录中;
  2. 使用的是默认的构建输出位置;
  3. VuePress 以本地依赖的形式被安装到你的项目中
  • docs/.vuepress/config.js 中设置正确的 base
  • 创建一个如下的 deploy.sh 文件

学习使用vuepress,可以提高我直接用vue开发网站的效率。

学习vuepress-theme-vdoing,可以提高我配置vuepress主题的效率。

毕竟自己从头开始做一个vue框架的静态网站生成器要花费很大精力,而且不一定做得好;从头设计一个vuepress主题也要花很大精力,并且也不一定做得美观。新手期的时候借用别人的轮子可能开发出更好的产品。

认识vuepress-theme-vdoing的摘要

vuepress-theme-vdoing

基础

vdoing介绍和特性:

Vdoing是VuePress 的一个主题,是在默认主题 基础上做的修改和扩展,很多配置仍然沿用官方配置

特性:结构化(自动生成侧边栏、目录页、索引页、面包屑等,构建一个结构化知识库)、碎片化和个性化(博客功能)

vdoing相比于默认主题,添加的功能内容有:

管理学习笔记和技术文档:自动生成结构化侧边栏自动生成front matter目录页扩展的搜索框插件面包屑快捷翻页按钮

博客相关: 文章信息栏(作者与创建时间)最近更新栏博主信息栏页脚版权栏分类功能+分类页标签功能+标签页归档页评论插件

多种颜色模式供用户选择:跟随系统浅色模式深色模式阅读模式

提高搬砖效率的辅助工具: 批量操作front matter工具

方便好用的 Markdown 容器

vdoing快速上手

//安装和启动;
//可以直接看到成品,但是作者的使用痕迹很高,修改不容易。最后使用vdoing主题。然后自己写自己的vuepress。
# clone the project
git clone https://github.com/xugaoyi/vuepress-theme-vdoing.git

# enter the project directory
cd vuepress-theme-vdoing

# install dependency
npm install # or yarn install

# develop
npm run dev # or yarn dev

//使用vdoing主题
npm install vuepress-theme-vdoing -D

//在.vuepress/config.js中配置使用主题:
/*
// config.js
module.exports = {
  theme: 'vdoing'
}
*/
//修改config.js配置后需要重新启动项目才能生效

//版本更新:
npm update vuepress-theme-vdoing

vdoing目录结构

.
├── .github   (可选,GitHub Actions所需文件)
│   ├── workflows
│   │   ├── baiduPush.yml (可选,百度定时自动推送)
│   │   └── ci.yml (可选,自动部署)
├── docs (必须,不要修改文件夹名称)
│   ├── .vuepress (同官方,查看:https://vuepress.vuejs.org/zh/guide/directory-structure.html#目录结构)
│   ├── @pages (可选,自动生成的文件夹,存放分类页、标签页、归档页)
│   ├── _posts (可选,专门存放碎片化博客文章的文件夹)
│   ├── <结构化目录> 
│   └── index.md (首页)
├── theme-vdoing (可选,本地的vdoing主题)
├── utils  (可选,vdoing主题使用的node工具)
│   ├── modules
│   ├── config.yml (可选,批量操作front matter配置)
│   ├── editFrontmatter.js (可选,批量操作front matter工具)
├── baiduPush.sh (可选,百度推送命令脚本)
├── deploy.sh (可选,部署命令脚本)
│
└── package.json
  • docs 文件夹名称请不要修改
  • docs/.vuepress 用于存放全局的配置、样式、静态资源等,同官方,查看 详情目录结构
  • docs/@pages 此文件夹是自动生成的,存放分类页、标签页、归档页对应的.md文件,一般不需要改动
  • docs/_posts 专门用于存放碎片化博客文章,里面的.md文件不需要遵循命名约定,不会生成结构化侧边栏和目录页。
  • docs/<结构化目录> 请查看《构建结构化站点的核心配置和约定》
  • docs/index.md 首页
  • theme-vdoing 存放在本地的vdoing主题文件,如果你想深度的修改主题,首先要在docs/.vuepress/config.js中配置使用的主题指向这个文件。

vdoing遵循“约定优于配置”.

构建一个结构化的站点,需要遵循下面这些约定,约定可以为你省去很多配置,轻松拥有一个结构清晰的站点。

config.js中有如下配置

// config.js
module.exports = {
  themeConfig: {
     sidebar: 'structuring' //  'structuring' | { mode: 'structuring', collapsable: Boolean} | 'auto' | 自定义 
  }
}

在运行开发服务npm run dev或打包npm run build时主题内部将会按照目录约定自动生成一个结构化的侧边栏、目录页、面包屑等数据。

在源目录(一般是docs)文件夹中,除了.vuepress@pages_postsindex.md 或 README.md之外的文件夹将会为其生成对应的侧边栏。生成的顺序取自序号,名称取自文件夹(文件)名。

vdoing自动生成front matter

当你没有给.md文件的front matter 指定标题(title)、时间(date)、永久链接(permalink)、分类(categories)、标签(tags)时,在运行开发服务npm run dev或打包npm run build时将自动为你生成这些数据,你也可以自己手动设置这些数据,当你手动设置之后,相应的数据就不会再自动生成

vdoing的markdown容器

提示框容器

布局容器

普通卡片列表

图文卡片列表

vuepress-theme-vdoing的高级操作

批量操作front matter工具:使得博客在build后自动生成front matter;

自动部署:可以一键部署到GitHub pages和Coding Pages上;用npm run deploy即可一键部署。

评论模块的搭建:使用Gitalk实现静态博客无后台评论系统。弥补了静态网页不能交互的缺点。

图床:GitHub + jsDelivr + TinyPNG+ PicGo 打造稳定快速、高效免费图床。GItHub上存图片、jsDelivr免费CDN加速、PicGo做图床、TinyPNG压缩上传的图片。简直是一条龙服务。

百度收录:GitHub Actions 定时运行代码:每天定时百度链接推送。让自己的博客被推广。

在线编辑:前提是把博客源码上传到github仓库,并配置好 GitHub Actions 自动部署。配置好之后,每个文章页面底下都会有一个编辑按钮,点击即可跳到github在线编辑,编辑完成后提交就会自动触发GitHub Actions自动部署。

幸运的是这些功能都集成到vdoing中(我猜的,之前不是说这个vdoing主题和默认主题新增了内容)。

vdoing配置

主题配置:category、tag、archive、sidebar等

首页配置:bannerBg、features、postList

front matter配置:sidebar、article、comment等

目录页配置

添加摘要:文章摘要会显示于首页的详细版文章列表中,在编写文章时(.md文件中)在合适的位置添加一个``注释。注释前面的内容将会暴露在摘要中。

修改主题颜色和样式

评论栏:vuepress-plugin-commentvuepress-plugin-vssue

总结

看到这差不多了解了vuepress和vuepress-theme-vdoing。接下来我也准备尝试使用vuepress-theme-vdoing。

最后分析一下使用过程。

我原本是写《VuePress+Gitee快速搭建个人博客的尝试》。现在准备把这个收个尾,然后另起炉灶,实现vuepress+coding/GitHub;因为vdoing的官方文档上说用cdoing方便被百度收录。另外自动部署、在线编辑等功能依赖于GitHub Action,所以有必要另外写一篇《vuepress-theme-vdoing使用过程记录》

在《vuepress-theme-vdoing使用过程记录》中,第一步是安装下载vuepress;第二步是部署GitHub Pages和Coding Pages;第三步是使用使用vdoing主题并部署;第四步是实现博客+技术文章;

前三步大概没问题,第四步可能再做修改。

第四步想实现lingze’s blog的效果。

第一个是博客效果(还有分类、标签的模块)

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-6vzvfJGQ-1599979951957)(%E5%AF%B9vuepress%E7%9A%84%E8%AE%A4%E8%AF%86.assets/image-20200913144430537.png)]

image-20200913144516035

第二个是技术文档效果(知识库)

image-20200913144251596

第三个是关于界面(介绍自己、评论gittalk)

image-20200913145019501

第四部分是归档和友链

暂时写到这。

更新地址:GitHub

更多内容请关注:CSDNGitHub掘金

Logo

前往低代码交流专区

更多推荐