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

- この記事は[MDCアドベントカレンダー](https://qiita.com/advent-calendar/2019/mdc)用に準備してましたが、全枠埋まったので普通に公開します。

## 概要

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

![demo.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/175213/ad6a5c52-85d3-bed8-0887-3ba739ede756.gif)

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

## 登場する技術やサービス

- VuePress
- GitHub
- Netlify

### VuePress
<img src="https://vuepress.vuejs.org/hero.png" alt="vuepress" height="160" width="160"/>

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

### GitHub
<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" alt="github" height="160" width="160" />

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

### Netlify
<img src="https://www.netlify.com/img/press/logos/logomark.png" height="160" width="160" alt="netlify" />

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

## 事前準備

- Node.jsとGitのセットアップが必要です
- [3日目の記事](https://qiita.com/aion0721/items/0e69eb97c6ac64ee9bf2)で@aion0721さんが書いてくれたのでそちらを参考にしてください
    - [Nodejsインストール](https://qiita.com/aion0721/items/0e69eb97c6ac64ee9bf2#nodejs%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB)
    - [Gitのインストール](https://qiita.com/aion0721/items/0e69eb97c6ac64ee9bf2#git%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB)


## VuePressでページを作る

### セットアップ

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

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

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

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

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

```zsh
npm i vuepress
```

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

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

### ローカルで動かしてみる

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

```md:README.md
# Hello Vuepress

- こんにちは
```

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

```zsh
npx vuepress dev
```

- 起動が完了したらhttp://localhost:8080 にアクセスしてみましょう
<img width="635" alt="スクリーンショット 2019-12-04 23.03.16.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/175213/3f62df5b-7934-6d79-53c6-0eebb71b3f62.png">

- markdownで書いたファイルがWebページ化されています！


### 複数ページ作成してみる

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

#### markdownファイルの作成

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

```md:docs/index.md
# MDCアドベントカレンダー

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

```md:docs/article_1.md
# 1日目の記事

- 1日目の記事です
```

```md:docs/article_2.md
# 2日目の記事

- 2日目の記事です
```

```md:docs/article_3.md
# 3日目の記事

- 3日目の記事です
```

#### 設定ファイルの作成

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

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

#### 起動スクリプトの設定

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

```zsh
{
  "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ディレクトリで以下のコマンドを実行し起動します

```zsh
npm start
```

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

![sample.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/175213/d58a9876-0dff-9052-596b-e0e515b3bcde.gif)

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

## GitHubにアップロードする

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

```zsh
git init
```

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

<img width="800" alt="スクリーンショット 2019-12-04 23.43.52.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/175213/d8e17f0e-274b-e8e8-a4cf-d936b14019b5.png">

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

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

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

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

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

<img width="862" alt="スクリーンショット 2019-12-04 23.47.45.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/175213/2fc03a9e-bb31-05dd-dd98-58e783e11bf9.png">

## Netlifyにデプロイ

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

<img width="840" alt="スクリーンショット 2019-12-04 23.57.10.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/175213/5496c5f5-4fd7-401c-036d-69cda8c18d80.png">
<img width="534" alt="スクリーンショット 2019-12-04 23.59.10.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/175213/7742c88c-c905-8b40-af9a-2a2e43c97f03.png">

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

<img width="752" alt="スクリーンショット 2019-12-05 0.01.13.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/175213/522c931f-cf2a-6adf-76a7-9eb061a2a31f.png">

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

<img width="856" alt="スクリーンショット 2019-12-05 0.02.01.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/175213/face92dc-075e-0dba-743d-5bea62ab14d8.png">

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

## ページの更新

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

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

### ページを更新してみる

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

#### テーマカラーの変更

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

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

#### 画像の埋め込み

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

```md:docs/index.md
# MDCアドベントカレンダー

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

![mdc](/image.png)
```

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

<img width="789" alt="スクリーンショット 2019-12-05 0.25.43.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/175213/aa097e70-3cef-c4b6-cb52-93575cd8ac55.png">

#### ファビコンの設定

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

<img width="162" alt="スクリーンショット 2019-12-05 0.30.35.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/175213/8116a517-1942-e3ae-88e4-65f4cc74e61b.png">

- ファビコンは通常の画像ではなく専用のフォーマットが必要です
- [favicon 作成 などとググれば](https://www.google.com/search?q=favicon+%E4%BD%9C%E6%88%90)画像からfaviconを生成してくれるサイトがあるのでそれを使って`favicon.ico`を作成してください
- 作成した`favicon.ico`は`docs/.vuepress/public`内に配置するだけでOKです

#### ページの最新化

- GitHubにアップロードします

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

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

<img width="788" alt="スクリーンショット 2019-12-05 0.35.35.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/175213/3a0fdb5b-08a9-0086-5ff6-c5cd11e3a479.png">

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

<img width="398" alt="スクリーンショット 2019-12-05 0.37.10.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/175213/096b8dc8-6f07-05db-a7ed-14ed771833ab.png">

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

<img width="789" alt="スクリーンショット 2019-12-05 0.39.36.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/175213/4de9b092-c1fb-bd77-6a17-1268c8187532.png">

## 最後に

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