VuePress v0.xでStatic Site(静的サイト)の作り方

記事投稿当時のVuePressのv0.14です。

#VuePressとは
Vueを使った最小限の静的サイトジェネレーターです。
静的サイトジェネレーターなので、HexoやGatsby同様にMarkdownの知識のみで更新ができるだめ、ドキュメントを作るのに適しています。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/110405/21aa6d23-f781-882b-ffec-745d7c147862.png)

##特徴
* QiitaのようにMarkdownでページの作成ができます。
* Markdownファイル内でVueが使用できます。
* Vueで作られたテーマをカスタマイズできます。
* 簡単にGoogleAnalyticsと連携できます。
* デフォルトテーマ
    * レスポンシブレイアウト
    * 検索機能付きのヘッダー
    * Algoliaとの連携
    * カスタマイズできるナビゲーションとサイドバー

#VuePress
##はじめに
この記事では以下のことをします。

* VuePressのインストール
* ローカルホストでのサイト立ち上げ
* ページの追加
* サイドバーのカスタマイズ
* トップページのカスタマイズ
* スタイルのカスタマイズ
* Vueコンポーネントの追加

##導入
グローバルにインストールする方法もありますが、プロジェクト作って進める方を解説していきます。
###ディレクトリ構成
構成は環境によって変わる場合があります。

```sh
root/
 ├ docs/
 │   ├ .vuepress/
 │   │    ├ components/
 │   │    │     └ Button.vue
 │   │    ├ public/
 │   │    │   └ hero.png
 │   │    ├ theme/
 │   │    ├ config.js
 │   │    └ override.styl
 │   ├ foo/
 │   │  ├ README.md
 │   │  └ one.md
 │   ├ README.md
 ├ node_mobules/
 ├ package.json
 └ yarn.lock
```

###プロジェクトの作成
コマンド(MacはTerminal、Windowsはコマンドプロンプト等)を使用して以下を実行。
[VuePress Getting started 公式](https://vuepress.vuejs.org/guide/getting-started.html)

```sh
# ディレクトリの作成
mkdir vuepress-example

# 作成したディレクトリに移動
cd vuepress-example

# プロジェクトの作成。プロジェクトの設定は特に行わないので -y をつけています。設定したい場合は外してください。
yarn init -y # OR npm init -y
```
###VuePressのインストール
公式では既存のプロジェクトでwebpack 3.xを使用している場合に、インストールが失敗する場合があるのでnpmの代わりに[Yarn](https://yarnpkg.com/ja/)を使用することを勧めています。

```sh
# VuePressのインストール
yarn add -D vuepress # OR npm install -D vuepress
```

###ページの作成
```sh
# ディレクトリの作成
mkdir docs

# ページの作成
echo '# Hello VuePress' > docs/README.md
```

###確認
以下を`package.json`に追記してください。

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

それでは以下を実行して、`http://localhost:8080/`にアクセスしてページを確認してみましょう。  
ポートである`8080`の部分は環境に変わる場合があるので、ページが開かない場合はターミナルのログを確認してください。

```sh
yarn docs:dev # OR npm run docs:dev
```
以下のようなページが確認できたと思います。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/110405/462998d9-cf03-186a-46b3-8d3c40872a67.png)

## 運用
### サイドナビの追加
サイドナビを利用するために、更に１ページ追加します。

```sh
# ディレクトリ作成
mkdir docs/articles

# ページ作成
echo '# Hello foo.' > docs/foo/README.md
```

サイドナビを利用するために設定ファイルを追加します。
[VuePress Configuration 公式](https://vuepress.vuejs.org/guide/basic-config.html)

```sh
# ディレクトリの作成
mkdir docs/.vuepress

# ファイルの作成
touch docs/.vuepress/config.js
```

追加した`config.js`に以下を記述して、`yarn docs:dev`を実行してください。
そうすると画像のようにサイドナビが追加されています。

```js:docs/.vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      '/README.md', // 項目名を設定しない場合はh1が項目名になります。
      ['/foo/README.md', 'foo']
    ]
  }
}
```
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/110405/ee9f4d7c-3704-aefd-ae98-67b983424af9.png)

### 静的ファイル
画像などの静的ファイルは`docs/.vupress/public`配下に配置して使用します。
以下の画像を`docs/.vupress/public`に配置して、`docs/README.md`内で使用してみます。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/110405/14073f2d-72f3-5eee-743c-0366377f7436.png" height="200">

```md:docs/README.md
# Hellow VuePress
![aaa](/hero.png)
```
そうすると以下のように表示されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/110405/fd8919ce-c4b5-6e66-3adb-7e6fe1090826.png)

## カスタマイズ

### サイドナビ
サイドナビには階層構造になったディレクトリ構造を表現したり、アコーディオンを使ってグループ分けしたりできます。
[VuePress Sidebar 公式](https://vuepress.vuejs.org/default-theme-config/#sidebar)

`foo`ディレクトリの配下に`one.md`ファイルを追加し、内容を記述します。

```sh
# ファイル作成
touch docs/foo/one.md
```

```md:docs/foo/one.md
# Introduction
VuePress is composed of two parts.

## How It Works
A VuePress site is in fact a SPA powered by Vue, Vue Router and webpack.
```

今回はアコーディオンを使用し、グループを表現します。
`docs/.vuepress/config.js`を以下のように変更してください。
変更後、画像のようになっていることを確認してください。

```js:docs/.vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      '/',
      {
        title: 'Group 1',
        children: [
          '/foo/', // ファイル名がREADME.mdやindex.mdの場合省略できます。
          '/foo/one' // .mdを省略できます。
        ]
      }
    ]
  }
}
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/110405/2771e9d0-649f-0ed2-4caf-1f5c978c423b.png)

### ホームページ
[VuePress](https://vuepress.vuejs.org/)のトップのように、ホームページを作成します。
先程作成した`docs/README.md`をホームページとするので、以下のように変更するとVuePressのトップページのようになります。
[VuePress Homepage 公式](https://vuepress.vuejs.org/default-theme-config/#homepage)

```md:docs/README.md
---
home: true # 必須
heroImage: /hero.png # 任意
actionText: Get Started → # 任意
actionLink: /foo/ # 任意
features: # 任意
- title: Simplicity First
  details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
  details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
  details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2018-present Evan You
---
```

### テーマの変更
VuePressでは[Stylus](http://stylus-lang.com/)でデフォルトスタイルの一部は`override.styl`で変更ができます。
`docs/.vuepress`配下に`override.styl`ファイルを追加して、以下のように変更してください。
変更できるスタイルは[VuePressのGithub](https://github.com/vuejs/vuepress/blob/76d12e7be2bfbb5c645fc838591e27d95e99db62/lib/default-theme/styles/config.styl)の変数を参考にしてください。
[VuePress Simple style override](https://vuepress.vuejs.org/default-theme-config/#simple-css-override)

```sh
# ファイルの作成
touch override.styl
```

```stylus:docs/.vuepress/override.styl
$accentColor = #bf0000
```
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/110405/a0c48ef4-affe-250e-7ed1-01e8656a13ab.png)


さらに変更したい場合は、デフォルトテーマをEjectすることで変更ができます。
以下を実行することで、`docs/.vuepress`配下に`theme`フォルダができ、その中にStylusやVueのデフォルトテーマファイルがコピーされます。これらのファイルを変更することでデフォルトテーマの変更をすることができます。

```sh
# vuepress eject [targetDir]
vuepress eject docs
```

### コンポーネント
VuePressではVueを使用することができるので、オリジナルのコンポーネントを作成して使用することができます。
`docs/.vuepress`配下に`components`フォルダを作成し、`Button.vue`ファイルを配置します。
今回は簡単なコンポーネントを作成しますが、コンポーネントの詳細は[Vue](https://jp.vuejs.org/v2/guide/components-registration.html)を参考にしてください。
[VuePress Using Components](https://vuepress.vuejs.org/guide/using-vue.html#using-components)

```vue:docs/.vuepress/Button.vue
<template>
  <a href="#" class="btn">Button</a>
</template>

<style>
.btn {
  display: inline-block;
  padding: 8px 24px;
  background-color: #bf0000;
  color: white;
  border-radius: 4px;
}
</style>

```

```md:docs/foo/README.md
<!-- 使用する側 -->
# Hello foo.
<Button />
```

```sh
# ディレクトリの作成
mkdir docs/.vuepress/components
```
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/110405/91552e74-501c-e5a1-e108-50a4e384a327.png)