End

VuePress 博客 静态网站 部署

本文地址

目录

目录

VuePress

Vue-powered static site generator --- Vue 驱动的静态网站生成器

介绍

使用体验：

  • 上手简单，适合前端开发人员使用，但是基础功能太弱，bug 也很多
  • 构建后没法在本地使用，只能部署后使用
  • 侧边栏只能从 H2 开始，不包括 H1
  • 默认搜索只能搜索标题和 tag，不支持全文搜索
  • 没什么像样的主题或插件可用，生态不太活跃
  • 文档里的 bug 太多，很多功能根本没法用

特性：

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

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

同类产品比较

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

  • Docsify / Docute：这两个项目同样都是基于 Vue，然而它们都是完全的运行时驱动，因此对 SEO 不够友好。如果你并不关注 SEO，同时也不想安装大量依赖，它们仍然是非常好的选择！

  • Hexo：Hexo 最大的问题在于，他的主题系统太过于静态以及过度地依赖纯字符串，而我们十分希望能够好好地利用 Vue 来处理我们的布局和交互。同时，Hexo 的 Markdown 渲染的配置也不是很灵活。

  • GitBook：GitBook 最大的问题在于，每次编辑后的重新加载时间太长。它的默认主题导航结构也比较有限制性，并且，主题系统也不是 Vue 驱动的。另外，GitBook 背后的团队如今也更专注于，将其打造为一个商业产品而不是开源工具。

快速上手

  • 安装 VuePress：npm i -g vuepress 或 npm i -D vuepress 或 yarn add -D vuepress
  • 创建并进入一个新目录，创建一篇文档，例如 docs/README.md
  • 运行命令 vuepress dev docs(仅限全局安装) 或 npx vuepress dev docs 即可自动部署到 http://localhost:8080
  • 当在本地修改文档后，服务器会热重载文档内容
  • 运行命令 vuepress build docs 后即可自动构建到 docs\.vuepress\dist

推荐通过命令 npm init 创建配置文件 package.json，并在其中添加如下脚本，之后就可以通过命令 npm run dev 启动服务了。

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

部署

基础要求：

  • 文档放置在项目的 docs 目录中
  • 使用的是默认的构建输出位置
  • VuePress 以本地依赖的形式被安装到你的项目中
  • 确保至少配置了 "docs:build": "vuepress build docs"

支持部署的环境

  • CloudBase
  • GitHub Pages
  • Netlify
  • Google Firebase
  • Surge
  • Heroku
  • Vercel
  • 21 云盒子

部署到 GitHub Pages

  • 在 GitHub 上创建仓库
    • 如果部署到根目录，仓库名必须为：baiqiantao.github.io
    • 如果部署到子目录，仓库名可随意，比如：vuepressBlog
  • 在 docs/.vuepress/config.js 中设置正确的 base：
    • 如果部署到根目录：base: '/'
    • 如果部署到子目录：base: '/vuepressBlog/'
  • 在项目的根目录中创建一个 deploy.sh 脚本文件，注意 push 那一行的代码
    • 如果部署到根目录：git push -f git@github.com:baiqiantao/baiqiantao.github.io.git master
    • 如果部署到子目录：git push -f git@github.com:baiqiantao/vuepressBlog.git master:gh-pages
  • 运行此脚本即可自动完成 build、push 等操作
  • 然后就可以访问 baiqiantao.github.io 或 baiqiantao.github.io/vuepressBlog/
#!/usr/bin/env sh

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

# 生成静态文件
npm run docs:build

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

git init
git add -A
git commit -m 'deploy'
git push -f git@github.com:baiqiantao/vuepressBlog.git master:gh-pages
# git push -f git@github.com:baiqiantao/baiqiantao.github.io.git master

cd -

使用指南

目录结构

VuePress 遵循 约定优于配置 的原则，推荐的目录结构如下。

├── docs                        # 项目根目录，名字可以随意
│   ├── .vuepress               # 用于存放全局的配置、组件、静态资源等(下面的内容都是可选的)
│   │   ├── components          # 该目录中的 Vue 组件将会被自动注册为全局的异步组件
│   │   ├── theme               # 用于存放本地主题
│   │   │   └── Layout.vue
│   │   ├── public              # 静态资源目录，它们最终会被复制到生成的静态文件夹中
│   │   ├── styles              # 用于存放样式相关的文件
│   │   │   ├── index.styl      # 会生成在最终的 CSS 文件结尾的全局样式，优先级高于默认样式
│   │   │   └── palette.styl    # 用于重写默认颜色常量，或者设置新的 stylus 颜色常量
│   │   ├── templates           # 存储 HTML 模板文件，谨慎配置
│   │   │   ├── dev.html        # 用于开发环境的 HTML 模板文件
│   │   │   └── ssr.html        # 构建时基于 Vue SSR 的 HTML 模板文件
│   │   ├── config.js           # 【重要】网站的配置文件，格式也可以是 YAML 或 TOML
│   │   └── enhanceApp.js       # 客户端应用的增强
│   │
│   ├── README.md               # 【重要】网站首页，访问路径【/】
│   └── xxx.md                  # 一级内容，访问路径【/xxx.html】
│   ├── yyy                     # 子目录，如果下面没有【README.md】，子目录是没法直接访问的
│   │   └── README.md           # 二级首页，访问路径【/yyy/】
│   │   └── zzz.md              # 二级内容，访问路径【/yyy/zzz.html】
└── package.json                # 项目的配置文件

网站部署后，我们是把 docs 目录作为 targetDir(网站的根目录)，下面所有文件的访问路径都是相对于 docs 的相对路径。

文档中引用图片时，需要使用相对于当前文档的相对路径，例如 .vuepress/about.md 中引用.vuepress/public/logo.png 的引用路径为 ./public/logo.png

配置文件 config.js

网站的配置文件是 .vuepress/config.js，格式也可以是 YAML 或 TOML。

module.exports = {
  title: '标题',
  description: '描述'
}
  • base：默认值/，部署站点的基础路径
  • title：默认值undefined，网站的标题，它将会被用作所有页面标题的前缀，默认主题下，它将显示在导航栏上
  • description：默认值undefined，网站的描述，它将会以 <meta> 标签渲染到当前页面的 HTML 中
  • head: 默认值[]，额外的需要被注入到当前页面的 HTML <head> 中的标签
  • host：默认值'0.0.0.0'，指定用于 dev server 的主机名
  • port：默认值8080，指定 dev server 的端口
  • temp：默认值/path/to/@vuepress/core/.temp，指定客户端文件的临时目录
  • dest：默认值.vuepress/dist，指定 vuepress build 的输出目录
  • locales：默认值undefined，提供多语言支持的语言配置
  • shouldPrefetch：默认值() => true，一个函数，用来控制对于哪些文件需要生成 <link rel="prefetch"> 资源提示
  • cache：默认值true，是否使用缓存加快 webpack 的编译速度
  • extraWatchFiles: 默认值[]，指定额外的需要被监听的文件，监听的文件变动会触发重新构建，并实时更新
  • patterns：默认值['**/*.md', '**/*.vue']，指定要解析的文件 pattern

基础路径

  • 如果要将网站会部署到一个非根路径
  • 例如 https://baiqiantao.github.io/blog/，而非 https://baiqiantao.github.io/
  • 那么就需要在 .vuepress/config.js 中将 base 设置为 /blog/(以斜杠开始，以斜杠结束)

Markdown 拓展

  • 链接：所有的标题将会自动地应用 anchor 链接，anchor 的渲染可以通过 markdown.anchor 来配置
  • 索引：README.md 或者 index.md 文件会被自动编译为 index.html，对应的链接将为 /
  • 重定向：支持链接自动重定向，会自行在 /foo、/foo/、/foo.html 中寻找一个可用的
  • 目录：目录仅支持[[toc]]，而不支持[toc]
  • 容器样式：::: tip 提示、::: warning 注意、::: danger 警告、::: details 详情
  • 代码块：使用 Prism 实现语法高亮，支持代码块中的行高亮，支持显示行号，支持导入代码段
  • Emoji：例如 :100:，支持的表情列表详见 markdown-it-emoji
  • 前言：支持 Front Matter

VuePress 使用 markdown-it 来渲染 Markdown，可以通过 .vuepress/config.js 的 markdown 选项做一些自定义的配置。

默认主题

使用首页布局

想要使用特殊设计的首页布局，需要在根级 README.md 中指定 home: true。

---
home: true
heroImage: http://p1.qhmsg.com/dm/180_180_100/t0114c2c828368e8986.jpg
heroText: 标题
tagline: 副标题
actionText: 按钮的文字
actionLink: /about.html
footer: 这里是最底部的 footer，可以写版权信息
tags:
  - 白乾涛
  - 博客
  - Android
---

所有支持的设置

module.exports = {
    themeConfig: { //默认主题设置
        navbar: true, //启用或禁用所有页面的导航栏，【navbar: false】
        logo: 'http://p1.qhmsg.com/dm/180_180_100/t0114c2c828368e8986.jpg', //导航栏左上角的 Logo
        nav: [ //导航栏链接
            {text: '首页', link: '/'}, //链接标签默认包含 target="_blank" rel="noopener noreferrer"
            {text: '关于我', link: '/about.html', target: '_self', rel: ''},
            {text: '我的博客', link: 'https://www.cnblogs.com/baiqiantao/'},
            {
                text: '更多',
                items: [ //下拉列表
                    {text: '下拉列表', link: '/hello.html'},
                    {
                        text: '分组', items: [
                            {text: '下拉列表', link: '/hello.html'},
                        ]
                    }
                ]
            },
        ],

        sidebar: 'auto', //【sidebar: auto】
        sidebarDepth: 3, //标题深度，默认是 只提取h2标题，【sidebarDepth: 2】
        _displayAllHeaders: true, // 显示所有页面的标题链接，默认 false (只显示当前页面的标题)
        _activeHeaderLinks: true, // 活动的标题链接，默认 true
        _sidebar: [ //自定义侧边栏，会覆盖当前页面自动生成的侧边栏
            '/about.html', //会自动提取 about.html 的子标题
            ['/hello.html', 'hello 下的子标题'] //会自动提取 hello.html 的子标题
            //其他功能：将侧边栏划分成多个组、为不同的页面组来显示不同的侧边栏
        ],

        search: true, //启用、禁用默认搜索框，内置搜索只能搜索标题和【tags】，【search: false】
        searchMaxSuggestions: 10, //最大搜索结果数量
        _algolia: { //支持全文搜索
            apiKey: '<API_KEY>',
            indexName: '<INDEX_NAME>'
        },

        _lastUpdated: '最后更新时间 Last Updated', // 此文件最后一次 git commit 的时间
        _nextLinks: true, // 根据侧边栏的顺序来获取 下一篇 链接，【next: false】
        _prevLinks: true, // 【prev: ./some-other-page】
        smoothScroll: true, //启用页面滚动效果
    }
}

使用主题

module.exports = {
  theme: 'xxx'
}

可以使用缩写来省略主题名的前缀：

  • vuepress-theme-xxx等价于xxx
  • @org/vuepress-theme-xxx等价于@org/xxx
  • @vuepress/theme-xxx等价于@vuepress/xxx

使用插件

Awesome VuePress

module.exports = {
  plugins: ['xxx', '@vuepress/xxx']
}

可以使用缩写来省略插件名的前缀：

  • vuepress-plugin-xxx等价于xxx
  • @org/vuepress-plugin-xxx等价于@org/xxx
  • @vuepress/plugin-xxx等价于@vuepress/xxx

VuePress 自带的插件：

默认主题自带的插件：

支持的 Front Matter

VuePress 支持 YAML、JSON 或者 TOML 格式的 front matter。

---
key1: Value1
key2: Value2
---

---
{
  "key1": "Value1",
  "key2": "Value2"
}
---

---toml
key1 = "Value1"
key2 = "Value2"
---

2017-12-13

posted @ 2017-12-13 11:35  白乾涛  阅读(9323)  评论(1)  编辑  收藏  举报