デザイナーでもわかるVuepress(Vue.js)

デザイナースタートのプログラミング初心者です。
初歩的なVuepressの解説になります。
内容の多くが既出ですが、「現役エンジニアにとっては簡単なことかもしれないけど私にはわからないっ:older_woman:」という部分を補強する意図があります。「理屈はわからないけど、書いてる通りに進めたら出来た！！」を目指します。
Version 1.7.1


## 流れ

* (必要なものを準備)
* Vuepressインストール
* Vuepressの設定をいじる
* Vuepressの中身をつくる
* サイトを公開する

## 必要なものを準備

### テキストエディタ
なんでもいいのですが「VScode」がおすすめ

### ターミナル
最初から入ってることが多いのでPC内で「terminal」とかで検索してみて下さい。
ターミナルにもいろいろあるらしいのですが、私は「Windows Terminal」をインストールしました。

### Node.js
この辺はデザイナーに縁がありません。
しかしこれがないといけないみたいなので何も考えず手を動かします。

既に入ってるかどうかの確認法
ターミナルを起動、以下を入力してEnter

```
node --version
```

入っていればこんな感じでバージョンが表示されます。

```
v14.6.0
```

errorが表示されたら下記を参考にNode.jsを入手してください。
参考:[Node.jsをインストールする](https://qiita.com/sefoo0104/items/0653c935ea4a4db9dc2b)


### Vuepressインストール
まず作業フォルダを作成します。
vuepress_qという名前でフォルダを作りました。
(ネーミングに関して、日本語や記号とかは避けるのがベターですね)

ターミナルでそのフォルダまで移動します。
やり方ですが、例えばProductsフォルダの中のvuepress_qに移動したければ

```
cd Products/vuepress_q/
```
と入力してEnter。
例えば私の場合は以下のようになりました。

```
PS C:\Users\ユーザー名\Desktop\tests\vuepress_q>
```

ここで、

```
npm init
```
と入力してEnter。
ターミナルにいくつかの質問が表示されますが、全てEnterで進めます。

Is this OK? (yes)が最後です。
この段階ではフォルダ内に`package.json`が作られていることが確認できます。

そしてようやくvuepressのインストール。

```
npm install --save-dev vuepress
```
数十秒待たされます。

```
.
├── node_modules
├── package-lock.json
└── package.json
```

インストールが完了するとフォルダの中身はこんな感じになっていると思います。

### Vuepressの設定をいじる

package.jsonを開いて、

```package.json
"scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
```
↑ここを↓このように書き換えてください。

```package.json
  "scripts": {
    "dev":"vuepress dev src",
    "build":"vuepress build src"
  },
```


次に、作業フォルダ(vuepress_q)の直下に`src`という名前でフォルダを作ります。
(自信のない方はフォルダ名変えずに)

さらに`src`直下に`README.md`というファイルを作ります。
`.md`はマークダウン記法という形式で文書を作成できるファイルです。
マークダウン自体はとても簡単なので気軽にご活用ください。
[Markdown記法 チートシート](https://qiita.com/Qiita/items/c686397e4a0f4f11683d)

README.mdを開き、例えば

```
# ああああ
```

とでも入力し、保存して下さい。

**一応これで超最小構成は完成となります。**

ページの確認方法ですが、`.html`のようにローカルで開くだけでは正常に確認できません。

ターミナルで作業フォルダ(vuepress_q)にいる状態で、

```
npm run dev
```
と入力してEnterをおすと何やら処理が始まって
http://localhost:8080/
こんなURLが表示されます。このURLをブラウザで表示すると

![スクリーンショット 2020-10-19 123621.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/694012/2b446956-5346-9ed9-3bf2-f7b734c3027b.png)

元気なVuepressが確認できます。

## Vuepressの中身をつくる

`src`の直下に`.vuepress`というフォルダを作り、
さらにその中で`config.js`というファイルを作成します。(命名順守)
`config.js`の中身はひとまずこのように。

```config.js
module.exports = {
    title: 'ページタイトル', 
    description: 'ここにディスクリプションのテキスト' ,
    locales: {
      '/': {
        lang: 'ja'
      }
    },
    dest: 'docs',
    }
```
### aboutページを作る
`src`の直下に`about`フォルダ作成しその中に`index.md`作成。

### 上部ナビを作る
上部ナビメニューの設定を`config.js`の続きに追記します。

```config.js
module.exports = {
    
    //(省略)

    themeConfig: {
      nav: [
        { text: 'ほーむ', link: '/' },
        { text: 'あばうと', link: '/about/' }
      ],
    },
}
```
保存してもブラウザに変化がない場合は、
ターミナルで`Ctrl + C`押してから先ほどの`npm run dev`を再度実行。
![スクリーンショット 2020-10-19 130855.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/694012/6ceecb19-ead3-5eeb-33aa-463f86c567b7.png)

上部メニューが追加されているかと思います。

### サイドメニューの追加

ページ内を移動できるサイドメニューを作成します。
下記追記してください。

```js:config.js
themeConfig: {
      nav: [
        { text: 'ほーむ', link: '/' },
        { text: 'あばうと', link: '/about/' }
      ],
        sidebar: 'auto', //ここ追記
    },
```

(適宜、見出し・本文を追記して…)
<details><summary>本文サンプル</summary><div>

```README.md
# ああああ

## 画像

## 1 見出し

本文

## 2 見出し

本文

## 3 見出し

本文
```
</div></details>

![スクリーンショット 2020-10-19 140545.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/694012/84fb97f3-1dc7-d386-f40c-8502112c0f8c.png)

こうなります。(変化が無ければターミナルで`Ctrl + C`からの`npm run dev`)

本文で使用している ## 見出し などが自動でサイドメニューとして表示されます。

### 画像を表示

`.vuepress`フォルダの下に`public`フォルダを作成し、その中に画像を格納していきましょう。
記述は

```README.md
![](/sample.jpg)
```

もしくは

```README.md
<img src="./.vuepress/public/sample.jpg">
```

で表示できます。
もちろん、`public`の下にさらにフォルダを追加しても大丈夫です。

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

`.vuepress`の直下に`styles`フォルダを作成。
`palette.styl`ファイルを作成(命名順守)
下記の中から変更したい部分だけ記述します。

以下公式より引用
>
```palette.style
// colors
$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
$arrowBgColor = #ccc
$badgeTipColor = #42b983
$badgeWarningColor = darken(#ffe564, 35%)
$badgeErrorColor = #DA5961
// layout
$navbarHeight = 3.6rem
$sidebarWidth = 20rem
$contentWidth = 740px
$homePageWidth = 960px
// responsive breakpoints
$MQNarrow = 959px
$MQMobile = 719px
$MQMobileNarrow = 419px
```

分かりやすく`accentColor`を変更します。

```palette.styl
$accentColor = #f66
```
![スクリーンショット 2020-10-19 142541.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/694012/1a6df98f-2572-5b3c-1a83-c4b398a97154.png)
グリーン→レッドに変更できました。

### 独自のCSSを適用する
前項はあらかじめ指定された箇所をいじるだけでしたが、
スタイルを独自にカスタマイズすることもできます。
`styles`フォルダの中に`index.styl`を作成します。

例えば以下のシチュエーションで画像を横並びにしたいときは、

```html:README.md
<div class="flex">
    <img src="https://placehold.jp/f66/fff/300x300.png">
    <img src="https://placehold.jp/66f/fff/300x300.png">
    <img src="https://placehold.jp/ff6/666/300x300.png">
</div>
```

```index.styl
.flex{
    display:flex;
}
```

![スクリーンショット 2020-10-19 144005.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/694012/3616d2bb-45b3-8b5c-6dfd-2fe3bc698cbd.png)

このように通常の`.html` `.css`と同様の記述ができます。
スタイルを上書きする場合は`!important`が必要な場合があります。


## ページを公開する

サーバーの条件によってはVuepressは動きません。
契約プランにもよりますがレンタルサーバーだと動かないことのほうが多いです。

無料かつ手軽に利用できるサービスだとGithubPagesとNetlifyが有名です。
どちらも出来ることは同じですが、手順が少しだけ異なるのでご注意ください。

### Netlifyの場合

ターミナルでvuepress_qにいる状態で`npm run build`と入力しEnterでビルドします。
(画像編集でいうところの書き出しのような作業です。)

ビルドが完了するとdocsという名前のフォルダが作成され、中にはhtmlやcssが生成されているはずです。

(※ここからはVuepressとか関係なく通常のサイト公開と変わりがないため、ざっくりと説明します。)
Netliftyのアカウントを作り、
![スクリーンショット 2020-11-10 125218.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/694012/f29e8078-13e8-685b-bc32-c7fc6aca772b.png)
こんな感じのところにdocsフォルダをドラッグアンドドロップします。

URLが生成されるのでそちらにアクセスしてページが表示されれば完了です。

### GithubPagesの場合

Githubでバージョン管理する場合はこちらのほうが便利でしょう。

(※こちらも一般的なGithubの利用方法と被る部分はざっくりいきます。)

Githubでリポジトリを作成して作業データをコミット・プッシュするのですが、
node_moduleフォルダは基本いじらないのでバージョン管理からは外したほうがいいです。

また、`src/.vuepress/public/`の画像たちも(バージョン管理しないのであれば)含めなくて大丈夫です。
実際にページに反映されるのはこの後ビルドで生成する`docs/assets/img`の画像だからです。

`.gitignore`に追記しましょう。

```.gitignore
node_module
```

次に`config.js`に下記を追記してください。

```config.js
module.exports = {

    //省略

    base:'/Githubのリポジトリ名/',
}
```
あとはNetlifyの場合と同様、`npm run build`でビルド、
作業フォルダの中身をデプロイします。

githubのSettingsページ内 Github Pagesセクションで下記のように設定してSaveを押下。
(Branch → Master , folder → /docs)
![スクリーンショット 2020-11-10 140603.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/694012/ceec166b-3afd-0b7e-1b28-d013beb549f9.png)

URLが生成されてページにアクセスできるようになりますが、確認ができるまでに数秒～数分かかります。
私の場合、10分以上かかったこともありました。
それまでは404ページが表示されるはずです。

以上です。適宜記事の更新、リポジトリの公開をしようと思っています。