VuePress の使い方: 基本的な設定方法とデプロイまでの流れ

16 min to read

Vue.jsプログラミング

どうも、こうすけ（@kosuke_upd）です。

今回は、静的サイトジェネレータ VuePress の使い方について、プロジェクトを作成してから各種設定し、簡単なページを作成し、デプロイするまでの方法を解説します。

VuePress は、簡単な WEB サイトや技術文書などを作る際におすすめのものなのですが、昨日実際に使ってみたところ、簡単に導入でき、ページも Markdown で簡単に書くことができたり、あったら嬉しい設定項目がもろもろ揃っていったりとなかなか良いなと感じました。

では早速順番に解説していくので、一緒に見ていきましょう。

VuePress とは

VuePress 公式サイト

VuePress とは、Vue.js の開発者である Evan You さんが作成した静的サイトジェネレータです。

VuePress の特徴としては下記のようなものがあります。

  • シンプルでわかりやすい
  • Markdown で書ける
  • Markdown 内で Vue.js が使える
  • ページの編集状態をリアルタイムで確認できる

まとめると、簡単でシンプルで使いやすいといった感じです。Vue.js らしさが感じられますね。

では、VuePress の使い方を順番に解説していくので、順番に見ていきましょう。

VuePress の使い方

準備: Node.js (Ver 8 以上) をインストール

まず前提として、VuePress を使うには、Node.js の Ver 8 以上が必要になります。

もしまだ Node.js をインストールしていない場合はインストールを、Node.js をインストールしているけどバージョンが古い場合はアップデートをしましょう。Node.js のバージョン確認は node -v で行えます。

Node.js のインストール方法に関してはこちらを参考にしてください。

【Mac】Node.js / npm のインストール方法

手順1. プロジェクトディレクトリの作成

ではまずはじめに、任意の場所で下記コマンドを実行し、プロジェクトディレクトリを作成し、作成したディレクトリに移動しましょう。

mkdir sample-site
cd sample-site

手順2. package.json の作成と VuePress のインストール

次は下記コマンドを実行し、プロジェクトディレクトリ内に package.json を作成し、VuePress をインストールしましょう。

yarn init -y
yarn add -D vuepress

この時点で、ディレクトリ構成は下記のようになります。

ディレクトリ構成

sample-site
├── node_modules
├── package.json
└── yarn.lock

手順3. docs ディレクトリを作成しページを作成する

ここまでできたら、実際にページを作成していきましょう。

下記コマンドを実行し、プロジェクトディレクトリ直下に docs フォルダを作成し、その中に index.md ファイルを作成しましょう。

mkdir docs
cd docs
touch index.md

すると、下記のようなディレクトリ構成になります。

ディレクトリ構成

sample-site
├── docs
│   └── index.md
├── node_modules
├── package.json
└── yarn.lock

その後、作成した index.md ファイル内に下記のように記述し、保存しておきましょう。

# Hello VuePress

手順4. package.json 内にコマンドを記述

次は、開発時とビルド時に使用するコマンドを使いやすくするために、package.json 内に下記のように記述しましょう。

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

これにより、開発時に yarn dev コマンドを実行することで、開発中のサイトの状態を確認できたり、yarn build コマンドを実行することでビルドすることができます。

また、この時点で package.json は下記のような内容になります。

{
  "name": "sample-site",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "devDependencies": {
    "vuepress": "^0.14.11"
  },
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  }
}

手順5. 表示確認をする

この時点で一度どのように表示されるかを確認してみましょう。下記コマンドを実行してみてください。

yarn dev

そして http://localhost:8080/ にアクセスしてみましょう。すると、下画像のように表示されると思います。

ちなみに、上記ページを開いたままエディタで中身を編集して保存すると、変更がリアルタイムで反映されます。一度試しに index.md ファイルを適当に編集して保存してみると良いですね。

また、確認状態を終了するには、ターミナル上で「Ctrl + C」キーを押すことで終了させることができます。

手順6. ページを追加する

ページを追加する場合は、index.md と同じディレクトリに .md ファイルを作成しましょう。例えば about.md ファイルを追加します。

docs ディレクトリ配下は下記のような構成になります。

docs
├── about.md
└── index.md

そして、yarn dev を実行し、http://localhost:8080/about.html にアクセスすると、追加したページを表示できます。

ページを追加する際に、docs ディレクトリ直下に about ディレクトリを作成し、その中に index.md ファイルを追加すると、追加したページを http:localhost:8080/about/ という URL で表示させることができます。

この際の docs 配下のディレクトリ構成は下記のようになります。

docs
├── index.md
└── about
     └── index.md

手順7. ナビゲーションに項目を追加

デフォルトのナビゲーションは下画像のように検索ボックスしかありませんので、項目を追加してみましょう。

vuepress 1

まず、docs ディレクトリ直下に .vuepress ディレクトリを作成し、その直下に config.js ファイルを作成します。

作成した config.js 内に下記のように記述してみましょう。

リンクを絶対パスにすると、自動的に target="_blank" が追加されます。

module.exports = {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'About', link: '/about.html' },
      { text: 'Blog', link: 'https://example.com/' }
    ]
  }
}

画面を確認すると、このようにナビゲーションに項目が追加されています。

また、下記のように階層構造を作ることで、ドロップダウンメニューにすることも可能です。

module.exports = {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'About', link: '/about.html' },
      { text: 'Blog', link: 'https://example.com/' },
      {
        text: 'SNS',
        items: [
          { text: 'Twitter', link: 'https://twitter.com/' },
          { text: 'Instagram', link: 'https://www.instagram.com/' },
          { text: 'GitHub', link: 'https://github.com/' }
        ]
      }
    ]
  }
}

手順8. サイドバーを追加

次はサイドバーを追加してみましょう。サイドバーを追加するには、config.js 内に下記のように記述しましょう。

module.exports = {
  themeConfig: {
    sidebar: [
      ['/', 'Home'],
      ['/about/', 'About']
    ]
  }
}

すると、下画像のようにサイドバーが追加されます。また、画像を見るとわかるように、自動的に開いているページの目次も表示されます。

また、このままだと目次に表示されるのは見出し2 (h2 タグ) のみですが、それより下の階層を表示させたければ、config.js 内に下記のように記述することで変更可能す。

module.exports = {
  themeConfig: {
    sidebar: [
      ['/', 'Home'],
      ['/about/', 'About']
    ],
    sidebarDepth: 2
  }
}

sidebarDepth: 2 というのを追記しましたが、この状態で画面を確認してみると、下画像のように h3 タグまでが目次に表示されていることがわかります。

手順9. 各種設定

次はサイトの各種設定をしていきましょう。設定と言ってもたくさんあるので、基本的な設定を見ていきます。

サイトの言語を日本語に設定

デフォルトでは、サイトの言語が英語になっているので日本語に設定しておきましょう。

config.js 内に下記を記述しましょう。これだけで日本語への設定変更は完了です。

module.exports = {
  locales: {
    '/': {
      lang: 'ja'
    }
  }
}

サイトのタイトル (title) の設定

config.js 内に下記のように記述することで、サイトのタイトルを設定できます。

module.exports = {
  title: 'Sample Site'
}

サイトの説明文 (description) の設定

config.js 内に下記のように記述することで、サイトの説明文を設定できます。

module.exports = {
  description: 'VuePress で作成したサンプルサイト'
}

head 内へのタグの埋め込み

head 内にタグを埋め込む場合、config.js 内に下記のように記述しましょう。

下記は一例ですが、ファビコンと OGP タグを埋め込んでいます。

module.exports = {
  head: [
    ['link', { rel: 'icon', type: 'image/png', href: '/favicon.png' }],
    ['meta', { name: 'og:url', content: 'https://example.com/' }],
    ['meta', { name: 'og:type', content: 'website' }],
    ['meta', { name: 'og:title', content: 'Sample Site' }],
    ['meta', { name: 'og:description', content: 'VuePress で作成したサンプルサイト' }],
    ['meta', { name: 'og:image', content: '/og.png' }]
  ]
}

手順10. ページごとの設定

手順9ではサイト全体の設定を行いましたが、ページごとに設定を行う場合は、設定したいページファイルの冒頭に下記のように記述します。例えば About ページに設定したい場合は、about.md ファイル内に記述します。

---
description: About ページです
meta:
  - name: og:url
    content: https://example.com/about.html
  - name: og:type
    content: website
  - name: og:title
    content: About Page
  - name: og:description
    content: About ページです
  - name: og:image
    content: /og.png
---

# About Page

手順11. デプロイする

ここまでできたら、最後にビルドしてデプロイしてみましょう。

下記コマンドを実行し、まずはビルドします。

yarn build

すると、.vuepress ディレクトリ直下に dist ディレクトリが作成されます。この時点でのディレクトリ構成は下記のようになっています。

sample-site
├── docs
│   └── index.md
│   └── about.md
│   └── .vuepress
│       └── config.js
│       └── dist
├── node_modules
├── package.json
└── yarn.lock

あとは、作成された dist フォルダを任意のサーバーにデプロイしましょう。

デプロイ方法はデプロイ先によって異なるので、公式サイトを参考にしてみてください。

参考 DeployingVuePress

最後に

今回は、VuePress の使い方について、プロジェクトを作成して基本的な設定をし、最後にデプロイするまでの流れを説明しました。

VuePress は、簡単な WEB サイトや技術文書などを作成するにはとても便利な静的サイトジェネレータなので、ぜひ一度使ってみてください。

\ 記事が良かったらシェア！ /

むらかこうすけ

むらかこうすけ

フリーのソフトウェアエンジニア.

Web アプリ, スマホアプリの開発が得意で, 今はゲームに関するプロダクトを仲間とともに開発しています.

ゲーム, 旅行がめちゃくちゃ好きです.

当ブログは Gatsby を用いて構築した完全自作ブログです.

UPDATE