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

はじめに：クラウドでの docStatic の使い方

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

GitHub やドキュメント・アズ・コードを使ったことがない方もご安心ください。必要なことや理由、詳細情報の参照先をわかりやすく説明します。

前提条件​

docStatic はローカル（お使いのコンピュータ上）で実行するか、クラウドでホストすることができます。この記事では、クラウドでホストする方法を説明します。

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

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

docStatic リポジトリをフォークする​

docStatic のソースコードは GitHub 上にあります。最初に、フォークを作成する必要があります。これにより、オリジナルのバージョンに影響を与えることなく、ご自身のリポジトリで使用できる個人用のコピーが作成されます。

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

プロジェクト構造​

リポジトリをフォークしてクローンすると、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 - サイドバーのドキュメント順序を指定します。「目次」の構造に使用してください。

次に、ドキュメントファイルの作成と保存場所を確認しましょう。

Docs フォルダを整理する​

Docs フォルダには docStatic のドキュメントのコピーが含まれています。docStatic のドキュメントを削除して、ご自身のドキュメントを作成する際にこの Docs フォルダに保存するという考え方です。

モノレポ​

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

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

変更をプレビューする​

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

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

yarn dev

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

ビルド​

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

yarn build-local

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