はじめに

やってみたら試行錯誤するところがいくつかありましたので、ご報告させていただきました次第です

そういうわけですので本稿はコミュニティへのベスト・プラクティスのご提案などとは程遠く、むしろ私の浅学の結果としての誤解や間違いを多々含むものと存じており、そのような誤謬をみつけられましたら忌憚なくご指摘いただければ大変ありがたい次第です

完成イメージ

既存アプリは対戦相手のポケモンの弱点を調べるアプリです、キー入力なしでポケモンの検索が出来るところが自慢です

関係ないですがカイリュウの中国語名みて衝撃を受けました
おまえ、海のリュウじゃなくて、快速のリュウだったのね！いままで何年も誤解しててごめんね

で、 VuePress でこんなかんじの ユーザーズ・マニュアルを作ります

アプリとマニュアルの間の行き来はそれぞれのメニューから行けるようにしておきます

これのなにが問題だったのか

VuePress のドキュメントにも書いてあるとおりに既存アプリ側に docs フォルダをつくってそこで作業を初めてしばらくして「あれ？どうしよう？」と悩んだのが下記の２点です

1. SPA が２つできてしまう

VuePress が なにかドキュメンテーション用のコンポーネントを作ってくれるのであれば、それを既存アプリの route に取り込めば既存アプリの中にドキュメントがいい具合にできるんですけどそうはなっていなくて、VuePress を build すると ドキュメントのSPA ができてしまう んです

既存アプリも、VuePress でつくったドキュメントのアプリも両方とも 独立した router を持った別々の SPA になってしまう、独立した index.htmlが２つできてしまうんですよね ^^;;;
どこに置こう？

2. ドキュメントのアプリケーションのデプロイ先

で、例えばドキュメントのアプリケーションを public の下に /docs に build するようにしておけば、開発中は既存のアプリからは /docs という route でリソースとしてドキュメントのアプリが参照できる ます、これはいい感じ
でも、Netlify にデプロイするときはリソースは /dist なのでこっちにドキュメントを build したいんですよね

つまり、開発中とデプロイ先でドキュメントの build 先を切り替えたい

解決策

1.アプリとドキュメントとの行き来の実装

とりあえず、VuePress が作る SPA の index.html とそのリソース群を /docs フォルダにまとめて、既存アプリのリソースとして認識できるフォルダ に置く事にします、そうすればドキュメントは既存アプリからリソースとして認識できます

vue-cli で作ったアプリだとリソースは /public なので、そこに docs というフォルダをつくって build してくれるように vuepress の config.js で設定します

module.exports = {
  title: 'Pokéctiveness2',
  description: 'Pokémon move effectiveness chart.',
  dest: 'public/docs',
  base: '/docs/',
}

で、既存アプリケーションの router.js に /docs へのルートを用意します。router の外への参照なので beforeEnter() をつけてあげるのが味噌だとおもいます

  routes: [
  ...
    {
      path: '/docs',
      name: 'docs',
      beforeEnter() {location.href = '/docs'}
    },
...    

ナビゲーションに追加します
ドキュメントは英語版を /docs に、日本語版を /docs/ja につくってます

export default {
  data(){
    return {
      wordings: wordings,
      drawer: false,
      links: [
        {icon: 'home', text: 'Home', route: '/'},
      ],
      doc_links: {
        en: {icon: '', text: 'How To Use', route: '/docs'},
        ja: {icon: '', text: '使い方', route: '/docs/ja'}
      }
    }
  },

同様にドキュメントのリソースとしてアプリケーションの index.html を参照なんてできないというか強引にやったとすると元のアプリに戻らず別のアプリへのジャンプになってしまいます ^^;;;

ここは良いアイデアがでなかったのですが、あきらめてドキュメントのメニューにアプリケーションへの URL を直にいれてしまいます

   themeConfig: {
    sidebar: 'auto',
    locales: {
      '/': {
        nav: [
          { text: 'back to App', link: 'https://pokectiveness2.netlify.com/'},
        ]
      },
      '/ja/': {
        nav: [
          { text: 'アプリに戻る', link: 'https://pokectiveness2.netlify.com/'},
        ]
      }  
    }
  },

ただし、VuePress のナビゲーションから外へのジャンプは別タブを開いてしまううので元のアプリにバックしたかんじになりません
これは VuePress の デフォルト・テーマにちょこっと手を入れる ことで、タブを開かないように変更します

2. Netlify への Deploy

Publish directory が dist だったとすると、Build command で既存アプリの build の後で VuePress を /dist/docs に build するように --dest オプション付きで vuepress buildを実行します

That's it!

これで冒頭のアプリケーションが Netlify にデプロイできました！めでたしめでたし

感想

アドベンチャーウィークで現在絶賛出現中のリリーラの中国語名に違和感を覚えます