[VuePress/Netlify]markdownだけでWebページを作成して公開するまで #GitHub

この記事はMDCアドベントカレンダー用に準備してましたが、全枠埋まったので普通に公開します。

概要

markdownでドキュメントを書いてそれをWebページ化して公開するまでの話です
markdown以外にも設定ファイルなどはいじりますが、プログラミングすることなくページを作成して公開できます
自分の場合は簡単なハンズオン資料など作る時によく活用しています
- こんなものが作れます
- https://react-handson.netlify.com/

少し長くなってしまいましたが、この手順通り進めれば公開までできるので試してもらえると嬉しいです

登場する技術やサービス

VuePress
GitHub
Netlify

VuePress

https://vuepress.vuejs.org/
今回のメインで、markdownをインプットにWebページ(HTML/CSS/JavaScript)を生成できるライブラリです
Vueのコンポーネントを作ってカスタマイズなどできますが、markdownを書くだけでも十分便利なライブラリです

GitHub

https://github.co.jp/
説明するまでもないですが、~~設計図共有サイト~~Gitでバージョン管理しているソースコードをWeb上で管理できるサービスです
今回はNetlifyとの連携のためにVuePresを使ったファイルをGitHubにアップロードします

Netlify

https://www.netlify.com/
静的ファイルのホスティングサービスです
GitHubとの連携が簡単で、指定したリポジトリのコンテンツを簡単に世の中に公開することができます

事前準備

Node.jsとGitのセットアップが必要です
3日目の記事で@aion0721さんが書いてくれたのでそちらを参考にしてください
- Nodejsインストール
- Gitのインストール

VuePressでページを作る

セットアップ

以下のコマンドを順番に実行してください

mkdir vuepress-sample
cd vuepress-sample
npm init -y
echo 'node_modules' > .gitignore
cd vuepress-sample

本筋から逸れるので説明は省きますがディレクトリ内が以下のような状態になっていればOKです

vuepress-sample
├── .gitignore
└── package.json

vuepress-sampleディレクトリ内で以下のコマンドを実行しVuePressをインストールします

npm i vuepress

node_modulesディレクトリの中にインストールしたライブラリが配置されます

vuepress-sample
├── .gitignore
├── node_modules
├── package-lock.json
└── package.json

ローカルで動かしてみる

vuepress-sampleディレクトリにREADME.mdを作成して以下の内容を記載します

README.md

# Hello Vuepress

- こんにちは

以下のコマンドで起動します
- 停止はctl + c

npx vuepress dev

起動が完了したらhttp://localhost:8080 にアクセスしてみましょう
markdownで書いたファイルがWebページ化されています！

複数ページ作成してみる

複数ページ作成して遷移させたり、サイドメニューを表示させたりしてみます

markdownファイルの作成

docsディレクトリを作成しそこにファイル作成します

docs/index.md

# MDCアドベントカレンダー

- MDCの2019年のアドベントカレンダーです

docs/article_1.md

# 1日目の記事

- 1日目の記事です

docs/article_2.md

# 2日目の記事

- 2日目の記事です

docs/article_3.md

# 3日目の記事

- 3日目の記事です

設定ファイルの作成

続いて設定ファイルを作成します

docs/.vuepress/config.js

module.exports = {
  title: 'MDCアドベントカレンダー',
  themeConfig: {
    sidebar: [
      '/',
      '/article_1',
      '/article_2',
      '/article_3',
    ],
  },
};

起動スクリプトの設定

最後に起動スクリプトの設定をします
package.jsonを修正して下さい
- scripts内のstartとbuildの行を追加しています

{
  "name": "vuepress-sample",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "vuepress dev docs",
    "build": "vuepress build docs",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "vuepress": "^1.2.0"
  }
}

動作確認

vuepress-sampleディレクトリで以下のコマンドを実行し起動します

npm start

起動したらhttp://localhost:8080 にアクセスしてみましょう

一気にそれっぽくなりました！

GitHubにアップロードする

NetlifyでWeb上に公開するために、まずはGitHubにソースコードをアップロードします
まずはgitのセットアップ
- vuepress-sampleディレクトリで以下のコマンドを実行して下さい

git init

次にGitHubでリポジトリを作成しそのURLを設定します
https://github.com にアクセスしてリポジトリを作成して下さい

作成できたらURLをコピーしてローカルのソースコードと紐付けます

git remote add origin https://さっきコピーしたURL

GitHubにファイルをアップロードします

git add .
git commit -m "vuepressのサンプルを作成した"
git push origin master

実行後GitHubのリポジトリのページにアクセスしてファイルがアップロードされてればOKです

Netlifyにデプロイ

最後はNetlifyにデプロイしてWeb上に公開してみます
まずはhttps://www.netlify.com/ にアクセスしてSignUpしてください
- GitHub連携で登録すれば一瞬です
ログインが完了したら先程作成したリポジトリを連携させます

連携が完了すると自動でビルドが走ります
少し待ってURLが黄色から緑色になったらデプロイ完了です！

さっそくURLにアクセスしてみましょう

ローカルで動かしたときと同じものが表示されてます！
あなたが作成したWebページが全世界に公開されました！

ページの更新

ページ更新の一連のながれ

ページを更新する場合は、ローカルで修正してGitHubにアップロードすると自動でNetlifyのビルドが走ります
なので基本の手順は
- ①ローカルで編集/動作確認
- ②GitHubにアップロード
- ③Netlifyに自動デプロイ
- といった流れです

ページを更新してみる

markdownを書き換えてもいいですが今回はVuePressのチップスを紹介しつつページの更新をしてみます

テーマカラーの変更

デフォルトはVueのテーマカラーである緑色が設定されています
docs/.vuepress/styles/palette.stylというファイルでカスタマイズできます

docs/.vuepress/styles/palette.styl

$accentColor = #28a6cf // 選択中部分の文字の色
$textColor = #2c3e50 // 文字の色
$borderColor = #eaecef // 区切り線の色
$codeBgColor = #282c34 // ソースコードエリアの背景色

画像の埋め込み

画像を埋め込みたい場合は画像ファイルをdocs/.vuepress/publicの中に配置します
お好きなファイルをimage.pngという名前でdocs/.vuepress/publicに配置して下さい
トップページに画像を埋め込んでみます

docs/index.md

# MDCアドベントカレンダー

- MDCの2019年のアドベントカレンダーです

![mdc](/image.png)

このように画像を埋め込むことができます

ファビコンの設定

ファビコンとはブラウザのタブに表示されるアイコンのことです

ファビコンは通常の画像ではなく専用のフォーマットが必要です
favicon 作成などとググれば画像からfaviconを生成してくれるサイトがあるのでそれを使ってfavicon.icoを作成してください
作成したfavicon.icoはdocs/.vuepress/public内に配置するだけでOKです

ページの最新化

GitHubにアップロードします

git add .
git commit -m "ページの変更"
git push origin master

アップロードが完了するとNetlifyのビルドが走ります
- ビルドが走り出すとNetlifyのWebページでProduction deploysに表示されます

Publishedになったらデプロイ完了です

URLにアクセスすると内容が更新されているはずです！

最後に

VuePressは最初にセットアップしてしまえば、あとはほとんどmarkdownの編集だけでページが作れます
さらにNetlifyを使うと簡単にWebページを公開することができてとても便利だと実感していただけたかと思います
この方法であればドキュメントの管理も自然とGitでバージョン管理されるのもいいところだと思います
GitHubでブランチ運用をしていけば複数人でコンテンツを作成しレビューしながら作成していくことも容易になります