メインコンテンツまでスキップ

Installation

ようこそ！このガイドでは、docStaticを初めてセットアップする手順を説明します。

GitHubやdocs-as-codeを使ったことがない方でもご安心ください。必要なもの、その理由、詳細情報の入手先を説明します。

前提条件​

docStaticはローカル（自分のコンピューター）で実行するか、クラウドでホストすることができます。

最も簡単なクラウドセットアップには、以下のサービスで無料アカウントを作成してください。

  • GitHub—コンテンツを保存して変更を追跡します
  • TinaCMS—ブラウザベースの編集を可能にします
  • LanguageTool—オプションの文法とスタイルチェックを提供します

代わりにdocStaticをローカルで実行する場合は、ローカル開発の要件を参照してください。

ローカル開発の要件​

このセクションは、ローカルで作業する場合にのみ適用されます。

統合開発環境（IDE）またはテキストエディターが必要です。オープンソースの選択肢として以下の2つがあります。

また、ビルドツールのためにNode.jsを、パッケージ管理のためにYarnをインストールする必要があります。

Node.jsのインストール​

Node.jsバージョン22.0以上をインストールする必要があります。

Node.jsがすでにインストールされているか確認してください。ターミナル（コマンドプロンプトまたはターミナルアプリ）を開いて実行します。

node -v

v22以上のバージョン番号が表示されれば問題ありません。

Node.jsがインストールされていないか古いバージョンの場合：

  1. Node.jsの公式ダウンロードページにアクセスします。

  2. お使いのオペレーティングシステム向けのLTS（長期サポート）バージョンを選択します。

    インストーラーには、後の手順で必要なNode Package Manager（npm）が含まれています。

    インストール中：

    * デフォルトオプションを選択したままにします（必要な依存関係が含まれています） * インストールが完了したら、ターミナルを閉じて再度開きます。

  3. （オプション）異なるNodeバージョンが必要な複数のプロジェクトで作業する場合は、nvm（Node Version Manager）をインストールします。nvmを使用すると、セットアップを壊さずにNodeのバージョンを切り替えられます。

Yarnのインストール​

docStaticはパッケージ管理にYarnを使用しています。

Yarnがすでにインストールされているか確認してください。ターミナルまたはコマンドプロンプトを開いて入力します。

yarn -v

バージョン番号が表示されれば、Yarnはすでにインストールされています。

「command not found」というメッセージまたは類似のエラーが表示された場合は、ターミナル（コマンドプロンプトまたはターミナルアプリ）を開いて実行します。

npm install -g yarn
注意

macOSまたはLinuxでは、権限を付与するためにコマンドの前に sudo を付ける必要がある場合があります。

sudo npm install -g yarn
注意

Windowsでは sudo は使用しません。ターミナルを管理者として開き、コマンドを実行してください。

docStaticリポジトリの取得​

docStaticのソースコードはGitHubにあります。始めるには、自分のコピーを作成する必要があります。

  1. docStaticリポジトリの フォークを作成する フォークすることで、自分のプロジェクトで独立して作業できるコピーが作成されます。
  2. フォークの クローンを作成する クローンすることで、作成した元のフォークに関連付けられたコピーが作成されます。後でスキーマの問題が発生した場合に修正するのに役立ちます。

docStaticリポジトリのフォーク​

  1. GitHubのアカウントにログインします。
  2. https://github.com/aowendev/docstaticにアクセスします。
  3. Fork をクリックします（通常は右上にあります）。
  4. デフォルトのリポジトリ名をそのままにします。
  5. プロジェクトの説明を入力します。
  6. 「Copy the main branch only」がチェックされていることを確認します。
  7. Create fork をクリックします。

GitHubがあなたのGitHubアカウントにリポジトリの新しいブランチを作成します。

docStaticリポジトリのフォークをクローン​

クローンを作成するには：

  1. GitHubアカウントにログインします。
  2. フォークのリポジトリに移動します。
  3. リポジトリをクリックして開きます。
  4. <> Code をクリックしてURLをコピーします。
  5. ターミナルまたはコマンドプロンプトを開き、cd を使用してクローンを保存したい場所に移動します。たとえば、cd Documents/Projects/ のように入力します。
  6. git clone に続けてクローンのURLを入力します。
git clone https://github.com/acme-projects/docstatic.git

プロジェクトの依存関係のインストール​

ローカルで作業する場合は、プロジェクトの依存関係もインストールする必要があります。cd を使用して、クローンまたはフォークしたdocStaticリポジトリのルートフォルダーに移動し、パッケージをインストールします。

cd docstatic
yarn install

Yarnがpackage.jsonに記載されているすべてのものをダウンロードします。数分かかる場合があります。

プロジェクト構造​

リポジトリをフォークまたはクローンすると、docstatic/ フォルダー内にさまざまなファイルが表示されます。以下に、把握しておく必要があるプロジェクト構造のファイルとフォルダーの 一部 を記載しています。これはプロジェクト内のすべてのものの完全なリストではありません。

docstatic
├── apis
│   └── petstore.yaml
├── blog
│   └── hybrid.mdx
├── config
│   ├── docusaurus
│   │   └── index.json
│   ├── homepage
│   │   └── index.json
│   └── sidebar
│       └── index.json
│   
├── docs
│   └── introduction.mdx
├── i18n
│   └── fr
├── mcp-server
│   └── src
│       └── server.ts
├── reuse
│   ├── code
│   │   └── example.xml
│   ├── conditions
│   │   └── index.json
│   ├── glossaryTerms
│   │   └── index.json
│   ├── snippets
│   │   └── example.mdx
│   ├── taxonomy
│   │   └── index.json
│   ├── variableSets
│   │   └── index.json
│   ├── code-files.json
│   └── snippets-files.json
├── scripts
│   └── generate-media-index.js
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── example-page.mdx
│       ├── index.js
│       └── index.module.css
├── static
│   └── img
├── tina
│   └── config.jsx
├── docusaurus.config.ts
├── package.json
├── README.md
├── sidebars.ts
└── yarn.lock

プロジェクト構造の概要​

  • /apis/ - OpenAPI YAMLファイル
  • /blog/ - ブログのMDXファイル
  • /config/ - TinaCMSがdocStaticを設定するために使用するJSONファイル
  • /docs/ - ドキュメントのMDXファイル
  • /i18n/ - 翻訳ファイル
  • /mcp-server/ - AIアシスタントがドキュメントにアクセスできるようにするMCPサーバー
  • /reuse/ - 再利用可能なコンテンツ
  • /scripts/ - prebuild と predev によって自動実行されるビルド時スクリプト
  • /src/ - ページやカスタムReactコンポーネントなどのドキュメント以外のファイル
    • /src/pages - このディレクトリ内のJSX/TSX/MDXファイルはウェブサイトページに変換されます
  • /static/ - スタティックフォルダー。ここに含まれるコンテンツは最終ビルドフォルダーのルートにコピーされます
  • /tina/ - TinaCMSの設定とGraphQLスキーマ
  • /docusaurus.config.ts - サイト設定を含む設定ファイル
  • /package.json - docStaticウェブサイトはReactアプリです。お好みのnpmパッケージをインストールして使用できます
  • /sidebars.ts - サイドバー内のドキュメントの順序を指定します。「目次」構造に使用します

モノレポ​

docStaticは、プロジェクトコードとプロジェクトドキュメントの両方を含む単一のリポジトリの使用を許可します。Docusaurusの用語では、この概念を「モノレポ」と呼びます。

詳細については、DocusaurusドキュメントのMonoreposを参照してください。

変更のプレビュー​

ファイルを編集しながら変更をプレビューするには、ウェブサイトを提供して最新の変更を反映するローカル開発サーバーを実行できます。

ターミナルまたはコマンドプロンプトを開いて入力します。

yarn dev

デフォルトでは、http://localhost:3000でブラウザウィンドウが開きます。

ビルド​

docStaticは静的サイトジェネレーターを使用してウェブサイトを静的コンテンツのフォルダーにビルドし、閲覧できるウェブサーバーに配置します。ウェブサイトをビルドするには次を使用します。

yarn build-local

コンテンツは /build フォルダーに生成され、GitHub Pages、Netlify、Vercelなどの任意の静的ファイルホスティングサービスにコピーできます。詳細については、DocusaurusドキュメントのDeploymentを参照してください。