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

投稿日: 2022-10-23 2022-10-23
タグ: Development, javascript, Vue.js

序章

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

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

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

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

前提条件

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

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

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

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

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

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

mkdir vuepress-example

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

cd vuepress-example

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

npm init --yes

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

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

npm install vuepress@1.8.2 --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をインストールし、 package.json サポートする dev と build コマンド。

ステップ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形式のいずれか）は、VuePressに提供するように指示します title, lang、およびその他の属性。

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

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

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

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

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

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.

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

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 ウェブサイトの description、これはSEOに適しています。これ title と description ウェブサイトに検索バーを備えたインデックス付き検索システムを自動的に提供します。

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

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

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

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

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

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

mkdir docs/.vuepress/styles

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

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の紹介を参照してください。

getdocs

13036