Vuepressとは
- VuepressはVue.jsの作者が作った、Vueで動く静的ページジェネレーターです
- markdownで書かれたファイルをhtmlに変換してくれます
- markdownの中でvueが書けます
- イメージはGitbookのVue版に近いです
開発リポジトリは以下です。 (Github:vuejs/vuepress)
Vuepressを使うメリット
- ドキュメントドリブンで運用しやすい(1マークダウン1ページ)
- Vueのコンポーネントを使えるので、markdownを拡張しなくてもよい
- 快適なmarkdown環境が最初から用意されている (Config Reference:Markdown)
導入
node環境が用意されていることが前提です。
公式の手順は https://vuepress.vuejs.org/guide/getting-started.html を参照してください。
作業用フォルダを作成し、移動。
mkdir vp_test
cd vp_test
プロジェクトを初期化
npm init //とりあえずenter連打
vuepressの導入
npm install --save-dev vuepress //公式ではグローバルだけどローカルにインストール
コマンドを用意
グローバルにインストールしていない(vuepress devを叩いても動かない)ので、package.jsonにコマンドを用意します。
"scripts": {
"dev":"vuepress dev", //開発中
"build":"vuepress build" // 静的ファイルをジェネレート
},
これで環境が用意できました
ディレクトリ構造
プロジェクトフォルダ直下にあるmarkdownファイルは、自動でコンパイルされるようです。
今回はこのような構成でいきます。
vp_test
├ .vuepress //vuepress関連のファイルが配置される
│ ├ dist // npm run buildで生成されたファイルが入ってる
│ ├ components // vueコンポーネントを入れる。vueファイルは自動で登録され、markdown内で自由に使用できます。
│ │ └ ColorTip.vue
│ ├ public // ドキュメントの生成に直接関係ない静的ファイル(画像とか)
│ └ config.js // vuepressの設定ファイル
├ Readme.md // ルートとなるmarkdown
└ docs // markdownファイルを置くディレクトリ
└ color.md // ページのmarkdown
config.jsの編集
module.exports = {
head: [
['link', { rel: 'icon', href: `/logo.png` }] //[タグ名,{キー:バリュー}]
],
port:'3000', //開発中のポート番号
themeConfig:{
// Vueファイル内で、$site.themeConfigでアクセスできます
// 今回は出てきませんが、テンプレートの出し分けなどに使います
// この辺を参照 https://github.com/vuejs/vuepress/blob/master/lib/default-theme/Layout.vue
},
}
markdownファイルを書く
# カラーコード一覧
* 色を一覧にします
* components以下は自動でグローバルに登録
<color-tip v-for="color in colors" :hex="color" />
<script>
const colors = ["#FF0000","#00FF00","#0000FF"]
export default{
data(){
return{
colors
}
}
}
</script>
<template lang="html">
<span :style="{ color: hex }">{{hex}}</span>
</template>
<script>
export default {
props:{
hex:{
type:String,
reqire:true
}
}
}
</script>
<style lang="css">
span{
display: inline-block;
}
</style>
Scssの導入
カスタムテーマ
カスタムテーマを使いたい場合は、config.jsに下記を追加します。
theme:"customtheme" // node_modules/vuepress-theme-customtheme を用いる
与えた値がそのままディレクトリ名に反映されます。node_module以下なので別途リポジトリを立ててそこでテンプレート管理するほうが楽でしょう。
(まだ出来たてなので特に記述ないですが、多分そういう運用前提なのでは)