f:id:moyashidaisuke:20191004235126p:plain

概要

前回はとりあえずVueStyleguildを動かすところまで解説しました。今回はページの設定である「Sections」の解説をします。

前回の www.moyashidaisuke.com

概要
マニュアル
ベース
sections
name, description
components、ignore
content
usageMode
exampleMode
href
sectionDepth
次

マニュアル

ここです。

vue-styleguidist.github.io

ベース

最初は前回の解説で使ったとりあえず動く設定から。styleguide.config.jsです。

const VueLoaderPlugin = require('vue-loader/lib/plugin')
module.exports = {
  webpackConfig: {
    module: {
      rules: [
        // Vue loader
        {
          test: /\.vue$/,
          exclude: /node_modules/,
          loader: 'vue-loader'
        },
      ]
    },
    plugins: [
      // add vue-loader plugin
      new VueLoaderPlugin()
    ]
  },

  components: 'resources/js/components/**/[A-Z]*.vue',
}

この段階ではこんな見た目です。

f:id:moyashidaisuke:20191005223317p:plain

sections

いきなりマニュアルと順番が違いますが、多分この順番がわかりやすいです。

そもそもsectionってなんぞや、なのですが、既に動いているデモがあります。

vue-styleguidist.github.io

このサイドバーを見たらわかりやすいのですが、コンポーネントをグルーピングしつつ、階層構造にする事ができます。このグルーピングされてる一つ一つがsectionです。

f:id:moyashidaisuke:20191005223852p:plain

sectionsの設定も、この階層構造を表現できるようになっています。

例えば

sections: [
    {
      name: '階層1',
      components: 'resources/js/components/**/[A-Z]*.vue',
      sections: [
        {
          name: '階層2-1',
          components: 'resources/js/components/**/[A-Z]*.vue',
        },
        {
          name: '階層2-2',
          components: 'resources/js/components/**/[A-Z]*.vue',
        },
      ],
    },
    {
      name: '階層a',
      components: 'resources/js/components/**/[A-Z]*.vue',
      sections: [
        {
          name: '階層a-1',
          components: 'resources/js/components/**/[A-Z]*.vue',
        },
        {
          name: '階層a-2',
          components: 'resources/js/components/**/[A-Z]*.vue',
        },
      ],
    },
  ]

とすると、こんな感じになります。（nameとかcomponentsは後で説明します）

f:id:moyashidaisuke:20191005224500p:plain

以降説明する設定は、基本的にこのsectionsの中のobjectに対して設定していく事になります。

name, description

簡単なのでまとめて。

module.exports = {
  sections: [
    {
      name: 'nameだよ',
      description: 'descriptionだよ',
      components: 'resources/js/components/**/[A-Z]*.vue',
      sections: [
        {
          name: 'nestしたsectionのnameだよ',
          description: 'nestしたsectionのdescriptionだよ',
          components: 'resources/js/components/**/[A-Z]*.vue',
        },
      ]
    },
  ]
}

見た目

f:id:moyashidaisuke:20191006225932p:plain

サイドバーにも第2階層以降のnameは表示されます。

components、ignore

この2つはセットで、sectionの対象とするとコンポーネントへのpathを設定します。 componentsがホワイトリスト、ignoreはブラックリストです。componentsに含まれていて、ignoreに含まれていないものが対象となります。

どちらも、stringと配列の両方をうけとるので、

{
      components: 'lib/components/ui/*.vue',
      ignore: 'lib/components/ui/ignoreComponent.vue',
}

{
      components: ['lib/components/ui/*.vue'],
      ignore: ['lib/components/ui/ignoreComponent.vue'],
}

どちらでもいけます。が、後から増やそうと思ったときに手間なので、最初から配列に統一した方が良いと思います。

なお、pathの指定はglob patternというもので指定します。

詳しくはこちら。

github.com

content

name、descriptionと各コンポーネントの説明の間にoverview（概要）として任意のmarkdownファイルを指定できます。

  sections: [
    {
      name: 'nameだよ',
      description: 'descriptionだよ',
      components: 'resources/js/components/**/[A-Z]*.vue',
      content: 'doc/test.md', // これ
      sections: [
        {
          name: 'nestしたsectionのnameだよ',
          description: 'nestしたsectionのdescriptionだよ',
          components: 'resources/js/components/**/[A-Z]*.vue',
        },
      ]
    },
  ]

doc/test.md

# test.md h1

test.md本文

f:id:moyashidaisuke:20191006231128p:plain

usageMode

PROPS, METHODS, EVENTS & SLOTS の部分の事がusageModeです。

collapse（デフォルト）

javascript

  sections: [
    {
      name: 'nameだよ',
      description: 'descriptionだよ',
      components: 'resources/js/components/**/[A-Z]*.vue',
      usageMode: 'collapse',
    },
  ]

f:id:moyashidaisuke:20191006232006p:plain

↑をクリックすると

f:id:moyashidaisuke:20191006232021p:plain

hide

  sections: [
    {
      name: 'nameだよ',
      description: 'descriptionだよ',
      components: 'resources/js/components/**/[A-Z]*.vue',
      usageMode: 'hide',
    },
  ]

f:id:moyashidaisuke:20191006232204p:plain

リンクすらでなくなります。

expand

  sections: [
    {
      name: 'nameだよ',
      description: 'descriptionだよ',
      components: 'resources/js/components/**/[A-Z]*.vue',
      usageMode: 'expand',
    },
  ]

最初から展開された状態で表示されます。

f:id:moyashidaisuke:20191006232317p:plain

個人的にはこれがデフォルトでいいんじゃないの・・？と思います。

exampleMode

まず、exampleなのですが、何もしないと「Add examples to this component」というメッセージが画面に表示されていて、クリックすると下記のメッセージが出ます。

Create Readme.md or TestComponent.md file in the component’s folder like this:

TestComponent example:

指定のファイル名でmarkdownファイルを作ると、使用例とともに実際に動くコンポーネントをドキュメントに挿入する事ができます。

こんな感じです。

f:id:moyashidaisuke:20191006231613p:plain

ここもusageModeと同じく、collapse、hide、expandが指定できます。やっぱりなぜかcollapseがデフォルトです、、、

href

外部リンクを作成できます。

  sections: [
    {
      name: 'nameだよ',
      description: 'descriptionだよ',
      components: 'resources/js/components/**/[A-Z]*.vue',
      sections: [
        {
          name: '外部リンク',
          href: 'https://www.google.jp',
          external: true,
        },
      ]
    },
  ]