docs-gen v0.6.0

はじめよう

はじめよう

1分もかからずにドキュメントサイトを作れます。

インストール

cargo install docs-gen

cargo install docs-gen

Rust が必要です。インストール後、docs-gen コマンドがグローバルに使えるようになります。

1. プロジェクトを初期化する

docs-gen init my-docs

docs-gen init my-docs

次のような構造が作られます:

my-docs/
├── config.toml              # サイト設定
└── pages/
    ├── en/                      # 英語ページ
    │   ├── index.md             # ホームページ
    │   ├── users-guide/         # セクション（独自のサイドバーを持つ）
    │   │   ├── index.md
    │   │   └── *.md
    │   └── developers-guide/    # コントリビューター向けセクション
    │       ├── index.md
    │       └── *.md
    └── ja/                      # 日本語ページ（en/ と同じ構造）

my-docs/
├── config.toml              # サイト設定
└── pages/
    ├── en/                      # 英語ページ
    │   ├── index.md             # ホームページ
    │   ├── users-guide/         # セクション（独自のサイドバーを持つ）
    │   │   ├── index.md
    │   │   └── *.md
    │   └── developers-guide/    # コントリビューター向けセクション
    │       ├── index.md
    │       └── *.md
    └── ja/                      # 日本語ページ（en/ と同じ構造）

テーマはあとからカスタマイズできます。詳しくはテーマのカスタマイズをどうぞ。

2. ローカルでプレビューする

docs-gen serve my-docs --open

docs-gen serve my-docs --open

--open フラグをつけると、デフォルトブラウザが自動で開きます。ローカルサーバーが http://localhost:8080 で起動し、ライブリロードが有効になります。

Markdown ファイル、config.toml、テンプレートを保存するたびに、ブラウザが自動でリロードします。手動でリフレッシュする必要はありません。

サーバーを起動したら、pages/en/index.md（または pages/ja/index.md）を編集して、サンプルのトップページを自分のプロジェクトの説明に書き換えてみましょう。static/ に自分の favicon.svg を置けば、デフォルトのアイコンも差し替えられます。

3. 本番用にビルドする

docs-gen build my-docs docs

docs-gen build my-docs docs

docs/ ディレクトリに静的 HTML が生成されます。あとはデプロイするだけです。

ヒント: 先に cd my-docs しておけば、すべてのコマンドでディレクトリ引数を省略できます:

mkdir my-docs && cd my-docs
docs-gen init                 # docs-gen init my-docs と同じ
docs-gen serve --open         # docs-gen serve my-docs --open と同じ
docs-gen build . docs         # docs-gen build my-docs docs と同じ

mkdir my-docs && cd my-docs
docs-gen init                 # docs-gen init my-docs と同じ
docs-gen serve --open         # docs-gen serve my-docs --open と同じ
docs-gen build . docs         # docs-gen build my-docs docs と同じ

次へ: ページを書く

ESC