記事検索
購読 する ログイン

VuePressで作るドキュメントサイト 前編 VuePressの基本機能

Vue.jsの作者が開発した静的サイトジェネレーター「VuePress」の基本機能を紹介します。Markdownを書くだけでシンプルな静的サイトが作成でき、ドキュメント内でVueコンポーネントを使えるのが特徴です。

カテゴリー
Jamstack >
静的サイトジェネレーター

発行

著者 中島 直博 フロントエンド・エンジニア
VuePressで作るドキュメントサイト シリーズの記事一覧

VuePressとは

今回紹介するVuePressは、Vue.jsの作者Evan You氏が作成した静的サイトジェネレータで、特に技術ドキュメントの作成に向けて作られたものです。

次のサイトはVuePressの公式ドキュメントです。

上記のVuePressの公式サイト自体もVuePressで作られており、VuePressの機能や使い方をまとめたドキュメントになっています。

このシリーズでは2回に分けて、VuePressの主な機能を解説します。第1回目はインストールからページをビルドするまでの基本的な仕組みと機能を紹介します。

VuePressの特徴

VuePressはVue.jsを使って作られており、Markdownの中でVueコンポーネントが使えるように拡張されています。

また、公式ドキュメントのテーマが、そのままVuePressのデフォルトテーマとなっているので、見やすくレスポンシブなドキュメントがMarkdownを書くだけで作成できます。

テーマ自体もVueコンポーネントで作られているので、テーマを置き換えることも、拡張することもできます。

このように、Vue.jsの知識をそのままドキュメント作成に活かすことができます。

VuePressの動作環境

VuePressはNode.js上で動作します。必要なNode.jsのバージョンはv8.0.0以上となっています。

VuePressのインストールはnpmから行います。

nodeコマンドとnpmコマンドがインストールされていない場合はNode.jsのサイトからLTSバージョンをダウンロードしてインストールしてください。

VuePressのインストール

インストールには少し準備が必要です。VuePressの動作にpackage.jsonが必要になるので、ドキュメントを作成するディレクトリに次の内容でpackage.jsonを作成します。

package.json

{}

VuePressをnpmからインストールします。次のコマンドをターミナルで実行します。

npm install --save-dev vuepress

補足：既存プロジェクトにVuePressを追加する場合

もし既存プロジェクトでwebpackの3系が使われている場合、npmでのインストールでは依存関係のインストールがうまくいかないと公式ドキュメントに注意書きがあります。その場合はnpmの代わりにyarnを使ってインストールするようにしてください。

scriptsを追加する

package.jsonにVuePressを実行するためのコマンドを追加します。

scriptsを追加

{
  "devDependencies": {
    "vuepress": "^0.8.4"
  },
  "scripts": {
    "dev": "vuepress dev",
    "build": "vuepress build",
    "eject": "vuepress eject"
  }
}

VuePressのコマンド

VuePressには、次の3つのコマンドが用意されています。

  • dev
  • build
  • eject

それぞれのコマンドについて解説します。

dev

devコマンドはローカルサーバーを立てるためのコマンドです。コンテンツの差分更新も行ってくれるので、ドキュメント作成中はこのローカルサーバーにアクセスして、ブラウザで確認しながら作業を行えます。

devコマンドは実行するとコマンドを実行したディレクトリをルートディレクトリとして扱います。もしドキュメント用のディレクトリを/docsのような名前で使用する場合には、次のように引数としてディレクトリのパスを指定します。

vuepress dev docs

build

buildコマンドはドキュメントを静的ファイルとして生成するコマンドです。生成されたドキュメントをGitHub Pagesなどでホスティングします。

buildコマンドも、devコマンド同様にディレクトリ名を引数として与えることができます。

eject

ejectコマンドはデフォルトテーマに使われているファイルを、作業ディレクトリに展開するコマンドです。VuePressのデフォルトテーマは、ちょっとしたカスタマイズであれば、特定のファイルを用意することで変更できます。一方で、デフォルトテーマをもとに大幅にテーマを変更したい場合にはejectコマンドを利用してカスタマイズを行うことになります。

テーマのカスタマイズについては次回解説します。

インデックスページを作成する

それではまずドキュメントのインデックスページとなるファイルを作成しましょう。

VuePressではドキュメントを作成するディレクトリのルートディレクトリにあるREADME.mdがインデックスページとなります。

README.mdを作成して、次の内容で保存します。

README.md

---
title: すごいドキュメント
meta:
  - name: description
    content: すごい説明
---

## すごい見出し

すごい内容

作成したらnpm run devを実行して、ブラウザでhttp://localhost:8080/にアクセスして確認してみましょう。

ブラウザでは次のように表示されます。

README.mdというファイル名で作成したMarkdownファイルは、そのディレクトリのインデックスのページとなります。たとえば /about/README.mdというファイル名で作成した場合、/about/index.htmlが対応するURLになります。

README.md以外のファイル名の場合には、ファイル名.htmlがURLとなります。たとえば、/about/links.mdというファイル名で作成した場合には、/about/links.htmlが対応するURLになります。

YAML Front Matterによる拡張

---で囲まれたブロックはYAML Front Matterという、ファイルにメタ情報を埋め込むためのフォーマットです。VuePressのデフォルトテーマは、このYAMLからページのタイトルなどを設定するようになっています。

先ほど作成したREADME.mdではtitleとmetaを記述しました。titleは文字どおりページのタイトルとして使用されるとともに、ヘッダーエリアにも表示されています。metaはページの<head>に<meta name="description" content="すごい説明">として展開されます。

テーマのカスタマイズについては次回解説しますが、ここに書いたYAMLはテーマで使うコンポーネント内で$page.frontmatterという変数からアクセスできます。

YAML Front MatterのフォーマットはGitHubも対応

身近なところでは、GitHubはYAML Front Matterのフォーマットで書かれたメタ情報を、テーブルで表示するようになっています。

サイドバーを表示する

VuePressは、ページ内の見出しをリンクとしてサイドバーに表示する機能があります。

使い方は次のように、YAML Front Matterでsidebar: autoを指定します。これを保存すると、自動的にコンパイルされます。

---
sidebar: auto
---
# Title

## Heading 1

見出し1の内容

## Heading 2

見出し2の内容

## Heading 3

見出し3の内容

これだけでページ内の見出しがリンクとなって、サイドバーに表示されます。ブラウザで確認すると図のような結果が確認できるでしょう。

また、サイドバーは次回解説するconfig.jsでも指定できます。config.jsでサイドバーを設定した場合、ページにsidebarの指定がなくてもサイドバーが表示されます。サイドバーを表示したくないページでは、次のようにsidebar: falseを指定します。

---
sidebar: false
---

拡張されたMarkdown

VuePressはMarkdownのパースにmarkdown-itを使っています。markdown-itにはプラグインで拡張できる仕組みがあり、VuePressにはいくつかのプラグインがデフォルトで組み込まれています。

見出しリストの挿入

Markdown内で次のように[[toc]]という文字列を入れると、そのページ内の見出しへのリンクのリストが挿入されます。

[[toc]]

## Heading 1

### Heading 1-1

## Heading 2

### Heading 2-1

## Heading 3

絵文字の使用

Markdown内では、GitHubやSlackで使われているような:happy:といった形式の記述が、対応する絵文字へと変換されます。

## 絵文字変換
- :smile:
- :zipper_mouth_face:
- :thinking:
- :mask:

このMarkdownは次のように変換されて絵文字が表示されます。

変換される絵文字については、次のページを参照してください。

カスタムブロック

Markdownに特別なブロックが追加されています。これは補足や警告を手軽に表せるように用意されているものです。

## カスタムブロック

::: tip
すごい
:::

::: warning
あぶない
:::

::: danger
やばい
:::

このMarkdownは次のように変換されます。

この:::で囲まれたブロックは、次のようなHTMLに変換されるので、このクラスを指定することで見た目を変更できます。

<div class="tip custom-block">
  <p class="custom-block-title">TIP</p>
  <p>すごい</p>
</div>

このカスタムブロックはmarkdown-it-containerを使って構文を拡張したものです。config.jsで同じプラグインを使うことで、カスタムブロックを増やすこともできます。

コードブロックの行ハイライト

VuePressはPrism.jsを使っていて、コードブロックのシンタックスハイライトが可能です。VuePressはシンタックスハイライトに加えて、コードブロックの特定の行をハイライトできます。

次のように言語の指定のあとに{}でハイライトしたい行数を指定します。

```js{5}
export default {
  name: 'MyComponent',
  data() {
    return {
      message: 'ハイライトされてる！'
    }
  }
}
```

このコードブロックでは5行目をハイライトするように指定しています。これは次のように表示されます。

Vueコンポーネントを使う

VuePressはMarkdownの中でVueコンポーネントが使えるようになっています。コンポーネントは./.vuepress/componentsフォルダに入れることで、どこでも使えるようになります。

次のコンポーネントを./.vuepress/components/MyComponent.vueとして作成します。

<template>
  <div>
    <input type="text" v-model="message">
    <p>
      {{message}}
    </p>
  </div>
</template>

<script>
export default {
  name: 'MyComponent',
  data() {
    return {
      message: 'MyComponent!!'
    }
  },
}
</script>

このコンポーネントをMarkdown内で次のように使用します。

## コンポーネント

<MyComponent/>

このMarkdownは、次のように表示されます。

JavaScriptも通常どおり動作するので、ドキュメント内にデモを埋め込んだり、繰り返し使う記述をヘルパーのような使い方ができます。

コンポーネントの注意点

./.vuepress/componentsに追加したコンポーネントは、サーバーサイドレンダリングされることになります。そのため、コンポーネント内でブラウザのDOM APIなどにアクセスするライブラリなどを使う場合には注意が必要です。

サーバーサイドレンダリングはNode.jsのコンテキストで行われるため、DOM APIが存在しません。そのため、サーバーサイドレンダリング時に実行される箇所でDOM APIにアクセスするコードがあった場合にエラーが発生します。

これを回避するためには、次のようにmountedフックなどで動的にインポートして使う必要があります。

<script>
export default {
  mounted () {
    import('./lib-that-access-window-on-import').then(module => {
      console.log(module)
    })
  }
}
</script>

ビルドしてみる

それではbuildコマンドを実行してドキュメントを生成してみましょう。

ターミナルから次のコマンドを実行します。

npm run build

補足：npm run buildの実行

npm run devを実行すると、常にファイルの更新を監視している状態になり、そのままでは新たにコマンドを実行できません。別のターミナルやタブを開いてnpm run buildを実行してください。

実行すると次のようなログが表示され、./.vuepress/distディレクトリに出力されます。

> @ build /path/to/group-pxg/cg-demo/2018-vue-press
> vuepress build

Extracting site metadata...[21:36:30] Compiling Client
[21:36:30] Compiling Server
[21:36:33] Compiled Server in 3s
[21:36:36] Compiled Client in 6s
Rendering static HTML...
Rendering page:  /guide/ Rendering Rendering page: /404.html
Success! Generated static files in .vuepress/dist.

生成されたdistディレクトリをホスティングすれば、ドキュメントサイトのできあがりです。

GitHub Pagesでのホスティング

生成したドキュメントをGitHub Pagesでホスティングしてみましょう。

gh-pagesブランチを作成してpushすればよいのですが、面倒なのでパッケージを使って行います。

次のコマンドでpush-dirをインストールします。

npm install push-dir --save-dev

そしてpackage.jsonのscriptsに次のコマンドを追加します。

"scripts": {
  "deploy": "push-dir --dir=./.vuepress/dist --branch=gh-pages --cleanup"
}

このコマンドnpm run deployを実行すればgh-pagesにdistディレクトリの中身がpushされます。

ここまでのまとめ

今回はVuePressのもっとも基本的な機能を紹介しながら、ドキュメントサイトとしてビルドし、GitHub Pagesでホスティングするところまでを解説しました。Markdownファイルを書くだけで、シンプルな見栄えのドキュメントサイトが作れることを実感してもらえたと思います。

次回はデフォルト設定から少し歩みを進め、コンフィグファイルの設定で各ページのカスタマイズを行ってみましょう。
X GitHub
運営会社