VuePress を使って GitHub Pages でブログを公開する

はじめに

はじめまして、Qiita 初投稿の、どうもぼくです。投稿画面、プレビュー付き markdown で見やすい。
今回は VuePress を使って GitHub Pages にブログをデプロイするまでの手順を簡素にまとめます。

VuePress とは

VuePress 自体は Vue.js で作られた静的サイトジェネレータで、類似したものに React ベースの Gatsby 、 Ruby ベースの Jykell などがあります。

これらは総じて JAM Stack と呼ばれるフロントエンドアーキテクチャ（のような概念）で括られ、注目している人もいるようです。
が、そこらへんは既に解説されている方がいるのでおまかせします。

2018年のトレンドになるかもしれないJAM Stackの日本語情報がなかったので和訳してみる - Qiita

VuePress は自作しながらあれこれ機能を組み込むことができ、そこも楽しいのですが、
本記事では決まったテーマを入れてサクッとブログを公開することを目的とします。
詳細なカスタマイズについては後日記事を書くかもしれません。

前提

• Git - v2.24.0
• npm - v6.13.2
  • Mac なら yarn でも OK
• GitHub アカウント
  • 空の新規リポジトリを作っておく
  • リポジトリ名は [あなたのアカウント名].github.io の形式にしておく

手順

vuepress のインストール

基本的な VuePress ライブラリ。

npm i -g vuepress

gh-pages のインストール

GitHub Pages へのデプロイを簡単にするコマンド。

npm i -g gh-pages

テーマのリポジトリをクローンする

今回使うのは vuepress-theme-ououe というテーマで、
必要なものはほとんど揃っていて持ってくるだけでブログが作れます。
本記事では最小構成版を利用します。

git clone https://github.com/tolking/vuepress-theme-ououe-template.git
cd vuepress-theme-ououe-template

自分のリポジトリにコミットする

自分のリポジトリ用にディレクトリを初期化。

rm -rf .git/
git init
git add .;git commit -m "first commit"
git remote add origin https://github.com/[あなたのアカウント名]/[新規作成したあなたのリポジトリ名].git
git push -u origin master

dev ブランチを作成する

管理用ファイルを置くためのブランチを作成する。

git switch -c dev

ついでに master にある .git 以外のファイルを削除しておく。

git switch master
ls | grep -v -E '.git' | xargs rm -r
git add .;git commit -m "rm all";git push

master の中身は消してもいいの？

なぜ消すかというと、GitHub Pages で公開される master には公開用ファイルだけを置き、
dev ブランチにはコンパイル前の編集用ファイルだけを置いて区分するためです。
ブランチを用いて本番環境(master)とテスト環境(dev)を作る、とイメージすると捉えやすいかもしれません。

ページを出力する

開発用のページを表示

それでは実際にページを生成してみましょう。
まず dev ブランチに切り替え npm で package.json をローカルインストールします。

git switch dev
npm i

次にブラウザにサイトを表示してみます。

npm run dev
~ 中略 ~
success [18:12:15] Build 3f0668 finished in 5236 ms!
> VuePress dev server listening at http://localhost:8080/

ブラウザで http://localhost:8080/ にアクセスするとブログページが確認できます。
このとき、編集用ファイルが watch されある程度ライブリロードで変更が反映される状態になっています。
ブログのカスタマイズはこのモードで行うことになります。

本番用ファイルの出力

今度は本番環境に置くことになるファイル一式を出力してみます。

npm run build

実行すると同じ階層に dist/というディレクトリが生成され、中に各種ファイルがコンパイルされて格納されます。
本番にはこのディレクトリの中身を置くことになりますが、
実際にはこのコマンドを直接実行することはなくシェルスクリプトの一部として処理されることになります。
また、ローカルではCSSの相対パスの整合性が取れないためそのままではHTMLを開いても表示上の確認ができません。

GitHub Pages へデプロイ

それでは実際に本番用ブランチにデプロイしてみます。
その前に package.json の run-scripts を以下の記述に書き換えます。

package.json

  "scripts": {
    "dev": "vuepress dev blog",
    "build": "vuepress build blog",
    "push": "gh-pages -d dist -b master",
    "deploy": "npm run build && npm run push" 
  }

gh-pages コマンドは -d オプションでデプロイ元ディレクトリを指定し -b オプションでデプロイ先のブランチを指定します。
ディレクトリの中身をそのまま指定したブランチに同期し展開するので rsync っぽさがあります。

早速デプロイしましょう。

npm run deploy

タスクが完了すると GitHub のリポジトリの master に dist/ の内容が反映されているかと思います。
https://[あなたのアカウント名].github.io にアクセスしてみましょう。(反映に数分かかることがあります)

これでページを公開することができました。

設定など

ページのビジュアルをさっと変えたい場合、下記のファイルを編集することで見た目の変更を行うことができます。

• ./blog/.vuepress/config.js : ページの各種設定を記述している
• ./blog/.vuepress/styles/index.styl : stylus 形式で個別にスタイルを割り当てることができる

config.js

// 設定例
module.exports = {
  title: "ここにページタイトル",
  description: "ここにページのサブタイトル",
  base: "",
  dest: "dist/",
  theme: "ououe",
  head: [
    [
      "link",
      {
        rel: "stylesheet",
        href: "https://fonts.googleapis.com/css?family=M+PLUS+1p"
      }
    ]
  ],
  themeConfig: {
    defaultTheme: {
      dark: [10, 12]
    },
    showThemeButton: false,
    cover: "/images/cover.jpg",
    logo: '/logo.png',
    search: false,
    backgroundImage: false,
    pageGroup: 12,
    postTime: {
      createTime: "公開日",
      lastUpdated: "更新日"
    },
    nav: [
      {
        text: "Top",
        link: "/"
      },
      {
        text: "Posts",
        link: "/posts/"
      },
      {
        text: "Tags",
        link: "/tag/"
      },
      {
        text: "About",
        link: "/about/"
      }
    ],
    footer: [
      {
        text: "All rights reserved."
      }
    ]
  }
};

index.styl

body
  background blue
  div
    display inline-block
  .hogehoge
    margin 100px 20px

また、画像ファイルなどのバイナリデータは以下のディレクトリ配下に格納しページ内に配置することができます。

• ./blog/.vuepress/public/

記事は下記ディレクトリの中に markdown ファイルを作ることで追加できます。
記事の表示順序は date に指定した日付をもとに決定されます。

• ./blog/posts/

post-1.md

---
title: ブログエントリタイトルはここ
display: home
image: /images/posts/img_eyecatch.png
date: 2019-12-19
tags:
  - test
---

ここまで見出しに表示される。

<!-- more -->

ここからはトップから見えない。

## タイトル

本文

ドキュメント

詳しい仕様や設定項目はテーマのドキュメントや VuePress の公式を確認してみてください。

• テーマガイド : Introduction | vuepress-theme-ououe
• VuePress公式ガイド : Introduction | VuePress

デモ

最後に

静的ページのテンプレートエンジン多すぎ問題。
結局は好みでしかないのではないかと思えてきた。

しばらくは VuePress で遊んでみようと思います。
他にもいろいろな有志のテーマがあるのでみなさんもお試しください。