kakakakakku blog

Weekly Tech Blog : Keep on Learning 👍

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

ポートフォリオ的な静的サイトを実装する機会があり,選択肢として GatsbyHugo も検討したけど,前から気になっていた「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」をインストールすることにした.yarnnpm をサポートしているけど,ドキュメントには 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 

f:id:kakku22:20190403181637p:plain

設定

次に 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 にリンクを定義するとナビゲーションバーを生成できるのは便利だと思う.

f:id:kakku22:20190403181654p:plain

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

vuepress.vuejs.org

vuepress.vuejs.org

Markdown

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

f:id:kakku22:20190403181721p:plain

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種類を使って,以下のようにサイトをリッチに表示できるようになった.

f:id:kakku22:20190403181744p:plain

検索機能

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

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

Toa で正常に検索できている.

f:id:kakku22:20190403182113p:plain

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

vuepress.vuejs.org

まとめ

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

github.com