VuePressの使い方

# VuePressインストール

ターミナルを使います

  1. プロジェクトの名前でフォルダ(vuepress-starter)を作りそのフォルダに移動します
デスクトップにフォルダを作る場合は先にデスクトップに移動する

cd desktop

mkdir vuepress-starter && cd vuepress-starter
  1. npmの初期化処理
npm init -y
  • これでプロジェクトの直下にpackage.jsonができます
  1. VuePressをローカル（このアプリケーションにだけ）にインストールします
npm install -D vuepress

このインストールで　package-lock.jsonファイルとnode_modulesフォルダがプロジェクト直下にできます

  1. 下記のコマンドでプロジェクトの直下にsrcフォルダを作り、README.mdフォルダを作って　# Hello VuePressと書き込みます
mkdir src && echo '# Hello VuePress' > src/README.md

  • README.mdがマークダウン記法でのindex.htmlのようなものです

  • 今作った　README.mdが/　HOME(base)の index.htmlで、これからどんどん.mdファイルを追加していきます

  • 必要な.vuepressフォルダを作っておきます

mkdir src/.vuepress
  1. package.jsonの編集をします

package.jsonの scriptsの箇所を下記に変更します

"scripts": {
    "dev": "vuepress dev src",
    "build": "vuepress build src"
  },
  1. ターミナルからスクリプトを実行します（右上のshがコマンドの目印）
npm run dev
  1. 止まったら、表示されたhttp://localhost:.../をコーピーしてブラウザのアドレスバーに貼り付けます

An image

  • この画面になればOKです
  • ここからはファイルを追加編集していきます
  • npm run devでスクリプトを走らせておけば変更は自動で反映します
  • スクリプトを止めるときは　controlを押しながらcを押します
  • もしリロードしても反映されない場合は一度止めて、再度、npm run devして下さい

# ホーム場面の設定

  • src/README.md を編集します(コピぺして下さい)
---
home: true
heroImage: /hero.png
heroText: Hero Title
tagline: Hero subtitle
actionText: Get Started →
actionLink: /guide/
features:
- title: Simplicity First
  details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
  details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
  details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2018-present Evan You
---

An image

注意

インデントがずれてもエラーになるので、上手く表示されない時はお手数ですが、ドキュメントからコピペして下さい

  • Frontmatter (YAMLやJSONフォーマットでテンプレート上部に記述することが できるページ固有の変数)というものらしく、ページごとの設定をする時にもFrontmatterを書きます。
  • titleの値が、 サイドバーに表示 されます
---
title: 私のタイトル
---
  • heroImage: /hero.png　画像を表示させる場合は./vuepressフォルダの直下にpublicフォルダを作りその中に画像をおきます
.
└─  src
　  └─ .vuepress
　     └─ public
　　　　　　└─ hero.png

# ページの構成

ナビゲーションバーに合わせて、Aパターン(typeA)、Bパターン(typeB,typeB2)、Cパターン(typeC)としています

  • パターンによってフォルダ構成が異なり、Aパターンが一番シンプルで、B Cの順により細かくなります

独り言

１枚の.mdに詰め込みすぎると、編集や分類するときに大変そう😟 サイドバーとナビゲーションバーを自分の用途に合わせて最適化できるといいのだけど... 🤔 とはいえ.mdファイルはどんどん追加できるし、個別で設定もできそうだから、どうとでもなりそう😅

.
├─ README.md(ホームページ)
├─ typeA.md (Aパターンはフォルダではなく.md)
├─ one.md
├─ two.md
├─ typeB（Bパターンの構成）
│  ├─ README.md
│  ├─ three.md
│  └─ four.md
├─ typeB2（Bパターンの構成）
│  ├─ README.md
│  ├─ five.md
│  └─ six.md
└─ typeC（Cパターンの構成）
│   ├─ README.md
│   ├─ seven.md
│   ├─ eight.md
│   ├─ typeC-child
│   │    └─ README.md
│   └─ typeC-child2
│       └─ README.md
│       └─ README.md
└─ typeD
    └─ nine.md
    └─ ten.md

# ルーティングパス

ナビゲーションバーやサイドバーのリンクをクリックしてURLを確認してみて下さい （内部リンクやナビゲーションバーをカスタマイズする時に参考になると思います）

相対パス Page Routing
/README.md /
/typeB/README.md /typeB/
/typeA.md /typeA.html

見出しは先頭に#がつきます

# Config File(設定ファイル)

# config.jsファイルを作る

  • src/.vuepress/config.js(.vuepressフォルダの中にconfig.js ファイルを作ります)
.
├─ src
│  ├─ README.md
│  └─ .vuepress
│     └─ config.js
└─ package.json

//module.exportsでオブジェクトをまとめて、エクスポートする
module.exports = {
  // 　この中に機能(オブジェクトのプロパティ)を追加します
　}

memo

  • config.jsには サイト全体の設定 を書きます
  • ちなみに、Frontmatterで事前定義された変数を使い、.mdファイルごとに 個別の設定 もできます Frontmatterの変数 (opens new window)

INFO

ここから config.jsですがめちゃくちゃごちゃごちゃしてしまいました 😩 コピペ用にまとめたものがあります コピペ用はこちら

アレンジにはオブジェクトや配列は必須だと思います(わかりやすくい説明だったので、メモしていたものです) オブジェクト
  • 名前(キー)と値の集合です
  • 名前(キー)と値が対になったものをプロパティと呼ぶ
  • プロパティの値は、文字列や数値はもちろんオブジェクトや配列なども入れられる
  • オブジェクトは{で始まり}で終わります。プロパティは,で区切り、プロパティの名前(キー)と値は:で区切る

 




 

 

 



{
  //オブジェクトを値として持っているパターン
  name: {
  first: "taro",
  last: "yamada"
  },
  //文字列を値として持っているパターン
  blog: "http://xxx.com",
  //数値を値として持っているパターン
  age: 34,
  //配列を値として持っているパターン
  skills: ["HTML", "CSS", "JavaScript"]
}
  • 上の例はname、blog、age、skillsの4つのプロパティを持つオブジェクト
配 列
  • 配列は順序を持った値の集合です、ゼロ個以上の値を持つ
  • 文字列の配列 ["foo", "bar", "baz"]
  • オブジェクトの配列 [{foo: "bar"}, {hoge: "piyo"}]
  • 配列の配列 [10, 101, [40, 50]]
  • 空配列 []
  • 複雑な配列（オブジェクト、文字列、数値、） [{foo: "bar"}, "baz", 100]
  • 配列は[で始まり、]で終わります。値は,で区切る

# 言語の設定

module.exports = {
    locales: {
        '/': {
          lang: 'ja',
          title: 'ここにはタイトル',
          description: 'サイトの説明を必要に応じて',
        }
    　},
    //次はここから
　}
  • titleの値は ナビゲーションバー に表示されます
  • descriptionはHTMLの<meta>タグとしてレンダリングされます

# HEADの設定

HTMLに挿入する追加の<head>タグを設定します

    head: [
    ['link', { rel: 'icon', type: 'image/png', href: '/apple-touch-icon.png' }],
    ['link', { rel: 'icon', type: 'image/png',   href: '/favicon32.png' }],
    ['link', { rel: 'icon', type: 'image/png', href: '/favicon16.png' }]
    ],
    // 次はここから
  • ここではファビコンを設定する場合を例に書いています(画像はpublicフォルダ直下におきます)
  • グーグル検索結果に表示されないようする場合は、['meta', { name: 'robots', content: 'noindex' }]でいけるかと思います
  • [tagName, { attrName: attrValue }, innerHTML?]

# ナビゲーションバーの設定

  • smoothScroll: true,はスムーズなスクロールを有効にします（スルスルっと動くアレです）
themeConfig: {
   smoothScroll: true,
    // ここの中に
  },
  • navbar: false,　はナビゲーションバーを無効にする設定です

😩

入り繰りが複雑になってきました🤕〜

  • ,　や、名前(キー)と値、値の型を意識しないと、どこで閉じてるかわからなくなりそう😩
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'Dorp',  items: [
          { text: 'Dorp1', link: '/Dorp1/' },
          { text: 'Dorp2', link: '/Dorp1/hoge.html' },
       　]
      },
    ],
  • navは配列を値にとります、配列の値はtextとlinkを名前(キー)に持つオブジェクトです
  • textの値はナビゲーションバーのタイトルです
  • linkの値はPage Routingです Page Routing
  • linkをitemsに変えて、その値を配列にし、ドロップダウンメニューにすることもでます

# サイドバーの設定

参考

config.jsではなくFrontmatterで 個別に 設定できること

# Frontmatterで設定できるもの

( .mdファイル に書くもの)

  • sidebarDepth: 2 デフォルトはh2をサイドバーに抽出します、これをh2,h3にします。
---
sidebarDepth: 2
---
  • 現在のページのヘッダーリンクのみ含むサイドバーを自動的に生成します
---
sidebar: auto
---
  • 特定のページのサイドバーを無効にします
---
sidebar: false
---

config.js

ここからはconfig.jsに書くもの themeConfigのプロパティです(続きから)

# サイドバーのデフォルトの設定を変更する

  • displayAllHeaders

displayAllHeaders: true サイドバーは、現在アクティブなページへのリンクのみが表示されますが、この設定ですべてのページのすべてのヘッダーリンクを表示できます

  • activeHeaderLinks

activeHeaderLinks: false,ヘッダーリンクとURLのハッシュは、ユーザーがスクロールしてページのさまざまなセクションを表示すると更新されます（色が変わる）。この動作を無効にできます

# サイドバー(sidebar)を有効にする

  • sidebar

sidebar: auto autoはすべてのページで有効にすることもできる

Aパターン

  sidebar: ['/','/one','/two',['/typeA', 'Aパターン']],
  • /は*/README.md 、リンクのテキストはタイトルなどから自動的に推測されます（リンクテキストを明示的に指定するには、[link, text]形式の配列を使用します）

# 複数のサイドバー

  • コンテンツの セクションごと に異なるサイドバーを表示する （Bパターンに使用）
   sidebar: {
     '/typeB/': ['','three','four'],
     '/typeB2/': ['','five','six'],
    },

# サイドバーグループ

  • オブジェクトを使用して、サイドバーリンクをグループに分割できる （Cパターンは複数のサイドバーとサイドバーグループを併用しています）

実は...

サイドバーグループをどういう時に使うのか、よくわかっていません 💦

追記

サイドバーグループが一番使い勝手良さそうなので、typeDとしてページの最後に追記しました

    sidebar: [
          {
           title: 'Group1',　//必須
           path: '/typeC/typeC-child/' //グループtitleへまとめてリンクするpathを指定できる(オプション)
           children: ['typeC-child/', 'typeC-child2/',],
           collapsable: false,
           sidebarDepth: 2, //サイドバーへの表示をh3までにする場合
          },
          {
　　　　　　　title: 'Group2',
            // 省略
　　　　　　　　
          },
      　],
  • children の値(配列)にはネストされたREADME.mdへのpathを追加できる
  • collapsable: false 折りたたみを無効にする場合に追加

# 検索ボックスの設定

module.exports = {
  themeConfig: {
    search: false,
    searchMaxSuggestions: 10
  }
}
  • search: false 検索ボックスを無効
  • searchMaxSuggestions 候補の数をカスタマイズ

# config.jsまとめ (コピペ用)

  • Aパターンのみの場合
module.exports = {
  locales: {
    '/': {
      lang: 'ja',
      title: 'VuePressの紹介',
      description: 'ノーコード、無料で専用マニュアルが作れます',
    }
  },
 //HEADの設定は必要に応じて追加して下さい
 themeConfig: {
    smoothScroll: true,
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Aパターン', link: '/typeA' },
      { text: 'ONE', link: '/one.html' },
      { text: 'TWO', link: '/two.html' },
    ],
   sidebar: ['/','/one','/two',['/typeA', 'Aパターン']],　
  },
  // ここからもう少し追加します
}
  • A、B、Cをミックスする場合(不要なものを削除して下さい)
module.exports = {
  locales: {
    '/': {
      lang: 'ja',
      title: 'VuePressの紹介',
      description: 'ノーコード、無料で専用マニュアルが作れます',
    }
  },
 //HEADの設定は必要に応じて追加して下さい
 themeConfig: {
    smoothScroll: true,
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Aパターン', link: '/typeA' },
      { text: 'ONE', link: '/one.html' },
      { text: 'TWO', link: '/two.html' },

       { text: 'Bパターン', items: [
          { text: 'Bページ', link: '/typeB/' },
          { text: 'THREE', link: '/typeB/three.html' },
          { text: 'FOUR', link: '/typeB/four.html' },
        ]
       },
       { text: 'B2パターン', items: [
          { text: 'B2ページ', link: '/typeB2/' },
          { text: 'FIVE', link: '/typeB2/five.html' },
          { text: 'SIX', link: '/typeB2/six.html' },
        ]
       },

      { text: 'Cパターン',  items: [
          { text: 'Cホーム', link: '/typeC/' },
          { text: 'SEVEN', link: '/typeC/seven.html' },
          { text: 'EIGHT', link: '/typeC/eight.html' },
          { text: 'CHILD', link: '/typeC/typeC-child/' },
       ]
      },

    ],

    sidebar: {
    　// Bパターン
       '/typeB/': ['','three','four'],
       '/typeB2/': ['', 'five', 'six'],

　　　 // Cパターン
       '/typeC/':['','seven', 'eight',
           {
             title: 'CHILD',
             // ナビからのリンクはCHILDでpathも一箇所にしている
             path: '/typeC/typeC-child/',
             children: ['typeC-child/', 'typeC-child2/',],
        　 　collapsable: false,　//折りたたまないない場合
           },
      　 ],

    　 // Aパターン
       '/': [['/typeA', 'Aパターン'],'/one', '/two',]
    },
  },
  // ここからもう少し追加します
}
  • 追記分：typeDグループはフォルダでグループ分け、Homeグループはフォルダ関係なくまとめています
      '/': [
         {
          title: "Homeグループ",
        // collapsable: false,
           children: [
             ["/", "Home"],
             ["/one", "HomeグループONE"],
             ["/two", "HomeグループTWO"]
           ]
         },
         {
          title: "typeDグループ",
        // collapsable: false,
          children: [
            ["/typeD/nine", "DグループNINE"],
            ["/typeD/ten", "DグループTEN"]
          ]
         },
       ]

装飾 →