Markdown Extensions / 検索機能などをサポートした静的サイトジェネレーター「VuePress」を試した

ポートフォリオ的な静的サイトを実装する機会があり，選択肢として Gatsby と Hugo も検討したけど，前から気になっていた「VuePress」を試すことにした．VuePress は Vue で実装された「Vue-Powered な」静的サイトジェネレーターで，Markdown で書くことができ，さらに設定次第では Service Worker を有効化することもできる．今回はドキュメントを読みながら VuePress に入門して，良さそう！と感じた機能を紹介する．ローカル環境で実装をして，ホスティングは Netlify や AWS Amplify Console を使えばお手軽にできるのも助かる．

vuepress.vuejs.org

github.com

インストール

まず，ドキュメントにある Getting Started を参考に進める．VuePress は今日時点で「v0.14.10」が最新バージョンとなり，並行して「v1.0.0-alpha.46」も開発が進められている．今回は v1 で使える新機能（後述する）を試したくて，「v1.0.0-alpha.46」をインストールすることにした．yarn と npm をサポートしているけど，ドキュメントには yarn 推奨と書いてある．

$ yarn add vuepress@next -D

vuepress.vuejs.org

次に自動生成された package.json に以下を追記する．

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

さっそく ./docs/README.md に1行追記し，yarn docs:dev を実行すると，ローカル環境が起動する．もう http://localhost:8080 にアクセスできるようになっている！タイトルと検索機能のみだけどー．

$ mkdir docs
$ echo '# Hello VuePress' > ./docs/README.md
$ yarn docs:dev 

設定

次に VuePress の設定ファイル ./docs/.vuepress/config.js を作成する．

$ mkdir ./docs/.vuepress
$ vim ./docs/.vuepress/config.js

最初に以下の項目を設定した．

• title ... title tag
• description ... meta tag
• themeConfig.nav ... ナビゲーションバー

module.exports = {
  title: 'Hello @kakakakakku',
  description: 'Hello @kakakakakku',
  themeConfig: {
    nav: [
      {text: 'Top', link: '/'},
      {text: 'VuePress', link: 'https://vuepress.vuejs.org/'},
      {text: 'kakakakakku blog', link: 'https://kakakakakku.hatenablog.com/'}
    ]
  }
}

themeConfig.nav にリンクを定義するとナビゲーションバーを生成できるのは便利だと思う．

他にも Google Analytics を設定したり，Service Worker を有効化したり，設定できる項目が多くある．詳しくはドキュメントに載っている．

vuepress.vuejs.org

vuepress.vuejs.org

Markdown

よく使う一般的な Markdown 記法を試す．今回は「リスト記法」と「テーブル記法」を書いてみた．特に違和感はなく，期待通り！

Markdown Extensions

VuePress には「Markdown Extensions」という機能があり，Markdown を拡張した独自記法をサポートしている．VuePress を使うメリットの1個とも言える．今回は3種類を紹介する（キャプチャは最後に載せてある）．

• 目次
• メッセージ
• シンタックスハイライト

Markdown Extensions : 目次

以下のように [[toc]] と書くと，目次になる．デフォルトだと「h2 / h3」を対象にしているけど，設定ファイルに markdown.toc を定義すれば，カスタマイズもできる．

## 目次

[[toc]]

Markdown Extensions : メッセージ

以下のように ::: を使うと，メッセージを書くことができる．今までよく見てきた Bootstrap で言えば，Alerts とほぼ同じ．

## メッセージ

::: tip
This is a tip
:::

::: warning
This is a warning
:::

::: danger
This is a danger
:::

Markdown Extensions : シンタックスハイライト

以下のように書くと，コードにシンタックスハイライトを適用できる．さらに js{4} のように書くことにより，特定の行を強調することもできる．なお，今回の記事は Markdown で書いているため，期待通りにレンダリングできず，今回は意図的に *"``" にしている．正しくは "```" となる．

`` js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
``

さらに VuePress v1 で使える新機能に「Line Numbers」があり，有効化するとコードに行数を表示できるようになる．今回は「v1.0.0-alpha.46」を使っているので，./docs/.vuepress/config.js に以下の設定を追加して，有効化した．

module.exports = {
  （中略）
  markdown: {
    lineNumbers: true
  },
  （中略）
}

最終的に「Markdown Extensions」3種類を使って，以下のようにサイトをリッチに表示できるようになった．

検索機能

ナビゲーションバーに「検索機能」があり，特に設定をしなくても「インクリメンタルサーチ」をサポートしている．静的サイトジェネレータだからこそ，ビルド時にインデックスを作ることができるし，超便利機能だと思う．本格的に全文検索をするなら Elasticsearch や Algolia を検討することになるけど，簡易的な検索なら十分に使える．今回は docs 直下を以下の構成にしている．

$ tree .
.
├── README.md
├── topic_a.md
├── topic_b.md
└── topic_c.md

To と a で正常に検索できている．

ドキュメントを読むと「title / h2 / h3」をインデックス対象にしていると書いてあった！

vuepress.vuejs.org

まとめ

• 静的サイトを実装する機会があり「VuePress」を試した
• 一般的な Markdown 以外に「Markdown Extensions」が多くあり，リッチにサイトを作れる
• 細かな設定も .vuepress/config.js に定義できる
• サクッと VuePress でサイトを実装し，ホスティングは Netlify や AWS Amplify Console を使えばお手軽にできる
• 今回試した VuePress のサンプルコードは GitHub に置いてある

github.com