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

インストール

ようこそ！このガイドでは、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 パッケージマネージャー「npm」が含まれています。インストール中は：* デフォルトのオプションを選択したままにしてください（これには必要な依存関係が含まれています） * インストーラーが完了したら、ターミナルを閉じてから再度開いてください。
  3. （オプション）異なるNodeバージョンを必要とする複数のプロジェクトに取り組んでいる場合は、nvm（Node Version Manager）をインストールしてください。nvmを使用すると、環境設定を壊すことなくNodeのバージョンを切り替えることができます。

Yarnのインストール​

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

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

yarn -v

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

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

npm install -g yarn
注記

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

sudo npm install -g yarn
注意

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

docStatic を入手する​

docStatic のコピーを入手するには、2 つの方法があります：

  1. `create-docstatic` を使用して新しいサイトを作成する（推奨）。1 つのコマンドを実行するだけで、独自の名前と Git 履歴を持つ、新しいスタンドアロンサイトが作成されます。
  2. リポジトリをフォークしてクローンする。 docStatic 本体への貢献を希望する場合、または Git でのマージを通じて更新を管理したい場合は、この方法を選択してください。

新しいサイトの作成​

ターミナル（コマンドプロンプトまたは Terminal アプリ）を開き、お使いのパッケージマネージャーに応じて、以下のコマンドのいずれかを実行してください。my-docs をプロジェクト名に置き換えてください。

npx create-docstatic@latest my-docs

このコマンドを実行すると、最新の docStatic テンプレートがダウンロードされ、my-docs フォルダが作成され、それが Git リポジトリとして設定され、プロジェクトの依存関係がインストールされます。完了したら、ローカルの開発サーバーを起動してください：

cd my-docs
yarn dev
ヒント

npx create-docstatic@latest --help を実行すると、依存関係のインストールをスキップする --no-install など、利用可能なオプションを確認できます。

この方法でサイトを作成した場合は、プロジェクト構造のセクションへ進んでください。

サイトを最新の状態に保つ​

docStaticの新しいバージョンがリリースされたら、サイトのルートフォルダから次のコマンドを実行してください:

npx create-docstatic@latest --update

このコマンドは、docStatic が管理するファイル（React コンポーネント、ビルドスクリプト、Docusaurus および Tina の設定、依存関係のバージョン）を更新し、コンテンツ（docs/、blog/、config/、reuse/、static/）には手を加えません。 サイトの名前や、追加したカスタム package.json スクリプトは保持されます。

更新にはクリーンな Git ワーキングツリーが必要ですので、まず作業内容をコミットしてください。その後、git diff で結果を確認し、更新されたファイルに対して行ったカスタマイズを再度適用してからコミットしてください。

ヒント

--dry-run を追加すると、実際に書き込みを行わずに、どのような変更が行われるかを確認できます。

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

docStatic への貢献を計画している場合、または将来の docStatic リリースを git を使って自分のサイトにマージしたい場合は、フォークとクローンを行うのが適切な選択です。

  1. GitHub のアカウントにログインします。
  2. https://github.com/aowendev/docstatic にアクセスします。
  3. 「Fork」をクリックします（通常は右上にあります）。
  4. 「リポジトリ名」はデフォルトのままにします。
  5. プロジェクトの説明を入力します。
  6. 「メインブランチのみをコピーする」にチェックが入っていることを確認します。
  7. 「フォークを作成」をクリックします。

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

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

この手順は、リポジトリをフォークしてクローンした場合にのみ適用されます。create-docstatic を使用すれば、依存関係は自動的にインストールされます。

cd コマンドを使用して、クローンした docStatic リポジトリのルートフォルダに移動し、パッケージをインストールします：

cd docstatic
yarn install

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

プロジェクト構造​

サイトを作成するか、リポジトリをクローンすると、プロジェクトフォルダ内にさまざまなファイルが表示されます。以下に、知っておくべきプロジェクト構造のファイルやフォルダを一部紹介します。これはプロジェクト内のすべてを網羅したリストではありません。

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

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

  • /apis/ - OpenAPI YAML ファイル。
  • /bin/ - create-docstatic が新しいサイトを作成する際に実行する docstatic CLI のエントリーポイント。docStatic リポジトリをクローンした場合にのみ存在します。
  • /blog/ - ブログ用 MDX ファイル。
  • /config/ - TinaCMS が docStatic を設定するために使用する JSON ファイル。チャットボットとテーマの設定を含みます。
  • /create-docstatic/ - create-docstatic として公開されている npm パッケージ。docStatic リポジトリをクローンした場合にのみ存在します。
  • /docs/ - ドキュメント用 MDX ファイル。
  • /i18n/ - 翻訳ファイル。
  • /mcp-server/ - AIアシスタントがドキュメントにアクセスできるようにする MCPサーバー。
  • /reuse/ - 再利用可能なコンテンツ。管理された URL やホームページ、メディアの設定を含みます。
  • /scripts/ - prebuild および predev によって自動的に実行されるビルド時のスクリプト。
  • /src/ - ページやカスタム React コンポーネントなど、ドキュメント以外のファイル。
    • /src/components - ダッシュボードやチャットボットなど、カスタム React コンポーネント。
    • /src/pages - このディレクトリ内の JSX/TSX/MDX ファイルは、すべてウェブサイトのページに変換されます。
  • /static/ - 静的フォルダ。ここにあるコンテンツはすべて、最終的なビルドフォルダのルートにコピーされます。
  • /template/ - メインサイトと同期を保ち、create-docstatic によって新しいサイトに配布されるスキャフォールディングテンプレート。docStatic リポジトリをクローンした場合にのみ存在します。CLI を参照してください。
  • /test/ - プロジェクトのテストスイート。docStatic リポジトリをクローンした場合にのみ存在します。
  • /tina/ - TinaCMS の設定および GraphQL スキーマ。
  • /docusaurus.config.ts - サイト設定を含む設定ファイル。
  • /package.json - docStatic ウェブサイトは React アプリです。必要な npm パッケージを自由にインストールして使用できます。
  • /sidebars.ts - サイドバー内のドキュメントの順序を指定します。「目次」構造を作成する際に使用してください。

Docs フォルダの削除​

docs/ フォルダには、docStatic のドキュメント（現在ご覧になっているページ）のコピーが含まれています。これは実例として用意されているものであり、サイト用のコンテンツではありません。公開する前にこのフォルダを削除し、代わりに独自のトピックを docs/ に保存してください。 このフォルダを残したままにすると、docStaticのマニュアルがあなたの名前で公開されてしまいます。

モノレポ​

docStaticでは、プロジェクトのコードとドキュメントの両方を単一のリポジトリに格納することができます。 Docusaurusの用語では、この概念を「モノレポ」と呼びます。

詳細については、Docusaurusのドキュメントにある モノレポ を参照してください。

変更内容のプレビュー​

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

ターミナルまたはコマンドプロンプトを開き、次のように入力してください：

yarn dev

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

ビルド​

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

yarn build-local

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