VuePress 快速上手及基础配置

开始之前

  1. 安装Node.js

    下载地址(版本需 >= 8.6)

  2. 初始化项目

    yarn init
  3. 安装VuePress

    yarn add -D vuepress

项目配置

目录结构

├─── docs
│   ├── README.md(首页)
│   ├── A(自定义文章目录)
│   ├── B(自定义文章目录)
│   ├── C(自定义文章目录)
│   └── .vuepress
│       ├── dist(生成静态文件的目录)
│       ├── public(存放静态资源)
│       └── config.js(配置文件)
└── package.json

首页

---
home: true
heroImage: /hero.png
heroText: LBVIIC's Notes
tagline: Less is more.
actionText: Blog
actionLink: https://hf.mk
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构,以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验,在 Markdown 中使用 Vue 组件,同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML,同时在页面被加载的时候,将作为 SPA 运行。
footer:  Copyright © 2017-2021 LBVIIC
---

你可以将相应的内容设置为 null 来禁用标题和副标题。

任何 YAML front matter 之后额外的内容将会以普通的 markdown 被渲染,并插入到 features 的后面。

config.js

module.exports = {
    title: 'LBVIIC\'s Notes', 
    description: null,
    base: '/notes/', // 项目部署位置,若为根目录删除本行
    head: [
        ['link', { rel: 'icon', href: 'https://hf.mk/favicon.ico' }]
      ],
    themeConfig: {
        // nav顶栏配置
        nav: [
            { text: 'page', link: '/page' },    // 单页面(文件名结尾)
            { text: 'folder', link: '/folder/' },    // 多页面(斜杠结尾,访问的是folder文件夹内的README.md)
            {    //分组
                text: 'Group Name',
                items: [    
                    { text: 'page', link: '/page' },    // item内配置同上
                    { text: 'folder', link: '/folder/' }    // item内配置同上
                ]
            }
        ],
        sidebar: {
            // 侧边栏配置
            '/example/': [
                {    // 分组名
                    title: 'Group1',   // 必要的
                    collapsable: false, // 可选的, 默认值是 true,
                    sidebarDepth: 1,    // 可选的, 默认值是 1
                    //分组下文件['文件名','显示名称']
                    children: [
                      ['','目录'],    //文件名为空代表README.md
                      ['file1','文件1']    //当前路径可以省略./,md文件可以省略.md
                    ]
                  }
            ],
        sidebarDepth: 0, // 侧边栏深度 默认为1 最大为2
        search: false, // 关闭搜索
        smoothScroll: true, // 开启页面滚动
    },
    markdown: {
        lineNumbers: true // 开启代码行号
      }
}

package.json

package.json中添加以下代码

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

发布

自行发布

  1. 本地运行本地服务

    访问http://localhost:8080即可预览网站

    yarn docs:dev
  2. 生成静态文件

    放置在docs/.vuepress/dist目录中

    yarn docs:build

持续集成

持续集成指的是项目代码上传至master,自动生成静态文件到gh-pages分支中

Github - Actions - 新建一个如下yml文件保存即可(每次push后,Github Actions会自动执行以下脚本)

name: VuePress

on:
  push:
    branches:
      - master

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2 # If you're using actions/checkout@v2 you must set persist-credentials to false in most cases for the deployment to work correctly.
        with:
          persist-credentials: false

      - name: Install and Build # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
        run: |
          yarn install
          yarn run docs:build
      - name: Deploy
        uses: JamesIves/github-pages-deploy-action@releases/v3
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages # The branch the action should deploy to.
          FOLDER: docs/.vuepress/dist # The folder the action should deploy.