VueとVuePressでドキュメンテーションシステムを構築する方法

序章

ドキュメントは、プロジェクトを成功させるための重要な部分です。ただし、プロジェクトに本格的なドキュメントシステムが必要ない場合があります。このような状況では、静的ページで十分な可能性があります。

VuePress は、フォルダーで構造化されたMarkdownファイルをHTMLファイルに解析して提供します。 VuePressには、 Vue 、 Vue Router 、およびwebpackが付属しています。各MarkdownファイルはVueテンプレートとして解析され、アセットはwebpackによってバンドルされます。 MarkdownファイルをVueテンプレートに解析すると、単一ファイルコンポーネントの形式でネイティブVueスクリプトを利用することもできます。

注：このチュートリアルは、手動インストールを念頭に置いて作成されています。 create-vuepress-siteと呼ばれる自動化されたスキャフォールディングツールも利用できます。

この記事では、Vueを利用した静的サイトビルダーであるVuePressを使用して、シングルページアプリケーションでもある静的ドキュメントWebサイトを構築します。

前提条件

この記事をフォローしたい場合は、次のものが必要になります。

Node.jsのローカル開発環境。 Node.jsをインストールしてローカル開発環境を作成する方法に従ってください。

このチュートリアルは、ノードv16.6.2、npm v8.1.0、およびvuepressv1.8.2で検証されました。

ステップ1—プロジェクトの設定

このセクションでは、プロジェクトを作成し、VuePressをインストールします。

まず、新しいプロジェクトディレクトリを作成します。

mkdir vuepress-example

次に、新しいプロジェクトディレクトリに移動します。

cd vuepress-example

次に、新しいプロジェクトを初期化します。

npm init --yes

このコマンドは、新しいプロジェクトの足場をすばやく作成し、package.jsonファイルを作成します。

次に、VuePressを開発依存関係としてローカルにインストールします。

npm install [email protected] --save-dev

VuePressがプロジェクトにインストールされると、VuePressにはこのプロジェクトで使用されるデフォルトのドキュメントテーマが付属しているため、必要なものがすべて揃っています。

この時点で、スクリプトのpackage.jsonを変更して、VuePressサイトを構築して提供する必要があります。

コードエディタでpackage.jsonを開き、強調表示されたコード行を追加します。

package.json

{
  "name": "vuepress-example",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "vuepress": "^1.8.2"
  }
}

この時点で、VuePressをインストールし、devおよびbuildコマンドをサポートするようにpackage.jsonを変更しました。

ステップ2—ホームページを作成する

このセクションでは、プレースホルダーテキストを使用してディレクトリ構造とマークダウンファイルを作成します。

VuePressでフォルダを作成するときは、ディレクトリ構造に従ってフォルダとMarkdownファイルを評価するので注意してください。フォルダ内の各Markdownファイルは、ルートが親フォルダであるHTMLドキュメントにコンパイルされます。

まず、docsディレクトリを作成して、コンポーネントと構成を格納します。

mkdir docs

次に、コードエディタを使用して、次のディレクトリに新しいindex.mdファイルを作成します。

docs / index.md

---
home: true
actionText: Counter Component
actionLink: /counter/
features:
- title: Embedded Vue Compments
  details: A Vue counter developed using Vue is embedded in this documentation. Now that's the power of VuePress!
- title: Documentation made with VuePress
  details: This entire documentation was made with VuePress which parsed Markdown files and corresponding assets using webpack.
footer: Developed using VuePress by William Imoh
---

Markdownファイルの特別な「フロントマター」構文（YAML、JSON、またはTOML形式のいずれか）は、title、lang、およびその他の属性を提供するようにVuePressに指示します。

この時点で、アプリケーションをビルドして提供し、これまでの状況を観察できます。

npm run docs:dev

アプリケーションが構築されると、アクセスするURLも提供する成功メッセージが表示されます（デフォルトではlocalhost:8080である必要があります）。

次に、このURLをWebブラウザで開きます。マークダウンコードは、 Counter Component のボタン、機能に関する情報列、およびフッターを生成します。

VuePressには、開発中にアプリケーションに加えられた変更を実装するホットリロード機能が付属しています。

ただし、ローカル開発サーバーの稼働中にVueコンポーネントが作成された場合は、開発サーバーを再起動する必要があります。

ステップ3—カウンターページを作成する

このプロジェクトの目的のために、ドキュメントは数値をインクリメントおよびデクリメントするCounterコンポーネントの詳細を追跡します。

docsディレクトリの下に、新しい.vuepressサブディレクトリを作成します。

mkdir docs/.vuepress

そして、この.vuepressディレクトリの下に、新しいcomponentsサブディレクトリを作成します。

mkdir docs/.vuepress/components

次に、コードエディタを使用して、.vuepress/componentsディレクトリに新しいcounter.vueファイルを作成します。

docs / .vuepress / components / counter.vue

<template>
  <div class="counter">
    <h1>{{ number }}</h1>
    <button @click="increment">Increment</button>
    <button @click="decrement">Decrement</button>
  </div>
</template>

<script>
export default {
  data() {
    return {
      number: 0
    };
  },
  methods: {
    increment() {
      if (this.number >= 0) {
        this.number++;
      }
    },
    decrement() {
      if (this.number > 0) {
        this.number--;
      }
    }
  }
};
</script>

<style scoped>
.counter {
  display: inline-block;
  margin-left: 30%;
}

button {
  display: inline-block;
  padding: 20px;
  margin: 10px;
  font-weight: bold;
  border-radius: 5px;
  box-shadow: 0px 0px 5px 0px rgb(11, 11, 114);
}

h1 {
  text-align: center;
}
</style>

このコードは値（number）を表示し、インクリメントまたはデクリメントボタンが操作された回数に応じて、その値が変化します。

次に、<counter/>コンポーネントを表示するページを作成します。

docsディレクトリの下に、新しいcounterサブディレクトリを作成します。

mkdir counter

次に、コードエディタを使用して、docs/counterディレクトリに新しいREADME.mdファイルを作成します。

docs / counter / README.md

---
title: Counter Component
---
# Counter Component

<counter/>

## Details

The `counter` component allows users to **Increment** and **Decrement** numeric values. The value starts at `0` and has a minimum value of `0`.

### Props

n/a

### State

n/a

このディレクトリにいくつかの追加ページを作成します。このデモにはusage.mdが含まれます。

docs / counter / using.md

---
title: Counter Component - Usage
---
# Usage

Currently, this component is used in our app as part of a demonstration.

そしてsee-also.md：

docs / counter / see-also.md

---
title: Counter Component - See Also
---
# See Also

* [Number](https://en.wikipedia.org/wiki/Number)
* [Increment and decrement operators](https://en.wikipedia.org/wiki/Increment_and_decrement_operators)

これらのファイルは後で静的ページに変換されます。

これで、必要なすべてのMarkdownファイルができました。

ステップ4—レイアウトとスタイルの構成

このセクションでは、指定したtitle、description、nav、および sidebarを使用するようにサイトを構成します。

config.jsファイルは、ドキュメントシステムをカスタマイズするために使用されます。コードエディタを使用して、.vuepressディレクトリに新しいcounter.vueファイルを作成します。

docs / .vuepress / config.js

module.exports = {
  title: 'VuePress',
  description: 'A demo documentation using VuePress',
  themeConfig: {
    nav: [
      { text: 'Counter', link: '/counter/' }
    ],
    sidebar: [
      {
        title: 'Counter',
        collapsable: false,
        children: [
          ['/counter/usage', 'Usage'],
          ['/counter/see-also', 'See Also']
        ]
      }
    ]
  }
};

まず、ウェブサイトのtitleを指定し、SEOに適したdescriptionを割り当てます。このtitleおよびdescriptionは、検索バーを備えたWebサイトのインデックス付き検索システムを自動的に提供します。

スクリプトの次はthemeConfigオブジェクトで、テーマに特定の機能を実装するために必要なパラメーターを受け取ります。 navbarを作成するには、各nav要素の表示テキストとルートを指定するオブジェクトを含むnav配列を作成します。

注：ナビゲーションバーの詳細については、公式ドキュメントをご覧ください。

このコードは、グループ化されたsidebarも備えているため、ユーザーはドキュメントでいつでもメニューを一目で確認できます。 sidebarメニューは、サイドバーグループのcollapsableプロパティを使用して、デフォルトで折りたたむように設定できます。

注：サイドバーの詳細については、公式ドキュメントをご覧ください。

デモンストレーションを構成するための最後のステップとして、スタイルを使用してデフォルトの色をオーバーライドします。

docs/.vuepress/ディレクトリ構造の下に、新しいstylesサブディレクトリを作成します。

mkdir docs/.vuepress/styles

次に、コードエディタを使用して、.vuepress/stylesディレクトリに新しいpalette.stylファイルを作成します。

docs / .vuepress / styles/パレット.styl

$accentColor = #cfa809
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34

この構文とファイル拡張子は、スタイラスシート用です。 VuePressは、色とブレークポイントの構成にスタイラスペンを使用します。

変更を保存し、次のコマンドを使用して開発サーバーを再起動します。

npm run docs:dev

.stylファイルに加えられた変更は、すぐにブラウザに反映されることに注意してください。

これで、個々のページを含むドキュメントシステムが完成しました。

結論

このチュートリアルでは、VuePressを使用して、静的なドキュメントWebサイトを開発しました。これもシングルページアプリです。

VuePressは、インタラクティブなデモンストレーションを導入するMarkdownファイル内にVueスクリプトを書く柔軟性を提供します。静的サイトは、速度、セキュリティ、および保守性の点で有用であると考えられています。

VuePressはSEOに対応しており、デフォルトでは、ページにGoogleAnalyticsを使用して分析追跡を実装する手段を提供します。また、VuePressには、Webサイト上のすべてのヘッダーにインデックスを付け、検索時にそれらを表示する最小限の検索システムが付属しています。 VuePressには、ドキュメント用のデフォルトのレスポンシブレイアウトが付属していますが、スタイル設定用のカスタムレイアウトもサポートしています。

追加のフォルダーと対応するMarkdownファイルを含めるようにプロジェクトを変更して、学習を続けます。

VuePressで利用可能なオプションについて詳しく知りたい場合は、VuePressの紹介を参照してください。