使用VuePress创建Github Pages

本文介绍从零开始使用VuePress搭建个人博客并且发布到GithubPages的过程。

快速上手

初始化项目

新建目录

mkdir vuepress-starter && cd vuepress-starter

生成package.json文件

yarn init -y

安装依赖

yarn add -D vuepress 

创建第一篇文档

mkdir docs && echo '# Hello VuePress' > docs/README.md
运行项目

添加scripts

package.json

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

本地启动服务

yarn docs:dev 

目录结构

推荐目录结构如下

.
├── docs
│   ├── .vuepress (可选的)
│   │   ├── components (可选的)
│   │   ├── theme (可选的)
│   │   │   └── Layout.vue
│   │   ├── public (可选的)
│   │   ├── styles (可选的)
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates (可选的, 谨慎配置)
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js (可选的)
│   │   └── enhanceApp.js (可选的)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json

详细的目录说明参看官方文档,这里列出主要修改的几个目和文件

  • docs/.vuepress: 存放全局的配置、组件、静态资源等。

  • docs/.vuepress/public: 静态资源目录。

  • docs/.vuepress/config.js: 配置文件的入口文件,也可以是 YMLtoml

  • docs/README.md: 站点首页,默认路由是/

基本配置

网站banner

docs/README.md

---
home: true
heroImage: /home.jpg
actionText: 开始了解 →
actionLink: /repository/

footer: CC0 Licensed | Copyright © 2020-alfalfaw
---

默认的静态资源目录为docs/.vuepress/public/home.jpg表示的是docs/.vuepress/public目录下的home.jpg文件

网站标题和描述

docs/.vuepress/config.js

module.exports = {
  title: '全栈日志',
  description: '公众号:全栈日记'
}
静态路径

docs/.vuepress/config.js

通过配置别名来避免用绝对路径访问资源

module.exports = {
  configureWebpack: {
    resolve: {
      alias: {
        '@public': './public'
      }
    }
  }
}
站点根目录

docs/.vuepress/config.js

module.exports = {
  base: '/journals/'
}

比如,要将网站部署到 https://.github.io/journals/,那么 base 的值就应该被设置为 "/journals/"

网站图标

docs/.vuepress/config.js

module.exports = {
  head: [
    [
      'link',
      {
        rel: 'icon',
        href: '/favicon.ico'
      }
    ]
  ]
}
网站目录
const utils = require('./utils')
module.exports = {
  themeConfig: {
    editLinks: true,
    docsDir: 'docs',
    smoothScroll: true,
    nav: [
      {
        text: '博客',
        link: '/blog/'
      },
      {
        text: '分享',
        link: '/share/'
      },
      {
        text: '面试',
        link: '/interview/'
      }
    ],
    sidebar: utils.inferSiderbars(),
    lastUpdated: '上次更新',
    editLinkText: '在 GitHub 上编辑此页'
  }
}
插件

@vuepress/plugin-active-header-links

页面滚动时自动激活侧边栏链接

yarn add -D @vuepress/plugin-active-header-links

使用

module.exports = {
  plugins: ['@vuepress/active-header-links', {
    sidebarLinkSelector: '.sidebar-link',
    headerAnchorSelector: '.header-anchor'
  }]
}

back-to-top

增加返回顶部按钮

yarn add -D @vuepress/plugin-back-to-top

使用

module.exports = {
  plugins: ['@vuepress/back-to-top']
}

last-updated

显示更新时间

使用默认主题只需配置themeConfig.lastUpdated = '最后更新时间'

@vuepress/plugin-medium-zoom

安装

yarn add -D @vuepress/plugin-medium-zoom

使用

module.exports = {
  plugins: ['@vuepress/medium-zoom']
}

yarn add -D @vuepress/plugin-search

搜索

安装

yarn add -D @vuepress/plugin-search

使用

// .vuepress/config.js or themePath/index.js
module.exports = {
  plugins: [
    ['@vuepress/search', {
      searchMaxSuggestions: 10
    }]
  ]
}

@vuepress/plugin-google-analytics

网站统计

安装

yarn add -D @vuepress/plugin-google-analytics

使用

plugins: [
  [
    '@vuepress/google-analytics',
    {
      ga: 'G-XXX'
    }
  ]
]

其中ga获取方式如下,

访问Google Analytics,点击左下角管理,然后创建媒体资源,点击刚才创建的媒体资源下的数据流,选择添加数据流,数据流类型选择网站

部署

以部署到Github Pages为例

deploy.sh

#!/usr/bin/env sh

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

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

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

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://.github.io
# git push -f [email protected]:/.github.io.git master

# 如果发布到 https://.github.io/
git push -f [email protected]:/.git main:gh-pages

cd -

赋予权限

sudo chmod u+x deploy.sh

每次部署时执行下面命令

./deploy.sh

你可能感兴趣的:(使用VuePress创建Github Pages)