TinyCADマニュアルへの貢献
このマニュアルはGitHub Pagesで公開されています。誤り、手順の不足、分かりにくいスクリーンショット、または古い情報を見つけた場合は、プルリクエスト(PR)で修正を提案できます。
このガイドでは、次の2つの方法を説明します。
- ブラウザーで手早く編集(小さなテキスト修正に最適)
- ローカルで編集してプレビュー(大きな変更に最適)
始める前に
必要なもの:
- GitHubアカウント
- ローカルで編集する場合:Git、Node.js、Ruby、Bundler
リポジトリの詳細:
- ソースリポジトリ:
https://github.com/matt123p/TinyCAD-docs - 公開サイト: このリポジトリから生成されるGitHub Pages
- ドキュメントのソースフォルダー:
docs/ - v4ページ:
docs/v4/
方法A:GitHubで手早く編集(ローカル環境の準備不要)
誤字の修正、簡単な説明の追加、リンクの更新には、この方法を使います。
1) GitHubでページのソースを開く
- TinyCADドキュメントのリポジトリに移動します:
https://github.com/matt123p/TinyCAD-docs docs/v4/で編集したいページを探します。- Markdownファイルを開きます(例:
Rulers.md)。
2) 編集を開始する
- 鉛筆アイコン(このファイルを編集)をクリックします。
- 表示された場合、GitHubがフォークの作成を自動で案内します。
- Markdownで変更を加えます。
3) 変更をコミットする
- 変更をコミットまでスクロールします。
- 明確なコミットメッセージを入力します。例:
docs(v4): clarify ruler units in Rulers - このコミット用に新しいブランチを作成を選択します。
- 変更を提案をクリックします。
4) プルリクエストを作成する
- 比較してプルリクエストを作成をクリックします。
- ベースリポジトリに
matt123p/TinyCAD-docs、ベースブランチにmainを設定します。 - PRのタイトルと説明を入力します(下のテンプレートを参照)。
- PRを送信します。
方法B:ローカルで編集してプレビュー(大きな変更におすすめ)
複数のファイルを編集する場合、リンクを確認する場合、または書式をプレビューする場合は、この方法を使います。
1) フォークしてクローンする
- GitHubで
matt123p/TinyCAD-docsをフォークします。 - フォークをクローンします:
git clone https://github.com/<your-username>/TinyCAD-docs.git
cd TinyCAD-docs
- upstreamリモートを追加します:
git remote add upstream https://github.com/matt123p/TinyCAD-docs.git
2) 依存関係をインストールする
このリポジトリには、BundlerとJekyllを実行するnpmスクリプトが用意されています:
npm install
npm run bundle:install
3) 変更用のブランチを作成する
git checkout -b docs/v4-fix-rulers
ブランチ名の例:
docs/fix-typo-...docs/v4-update-...docs/add-...
4) 編集する
ユーザー向けページの多くは次の場所にあります:
docs/v4/*.md(v4マニュアルのページ)docs/v3/*.md(v3マニュアルのページ)docs/_data/navigation.yml(左側のナビゲーション)
新しいページを追加した場合は、ユーザーが見つけられるようナビゲーションも更新してください。
5) サイトをローカルでプレビューする
npm run serve
次に、ターミナルに表示されたローカルURLを開きます(通常はhttp://127.0.0.1:4000)。
確認事項:
- 見出しの構成が読みやすい
- 内部リンクが機能する
- ナビゲーションに新規ページや名称変更したページが含まれている
- 画像が正しく読み込まれる
6) コミットしてプッシュする
git add .
git commit -m "docs(v4): improve Rulers instructions"
git push -u origin docs/v4-fix-rulers
7) PRを作成する
- GitHubで自分のフォークを開きます。
- ブランチの比較してプルリクエストを作成をクリックします。
- マージ先に
matt123p/TinyCAD-docs:mainを指定します。 - PRのタイトルと説明を入力して送信します。
文章の品質チェックリスト
PRを作成する前に、次の点を簡単に確認してください:
- 変更範囲が絞られている(1つのPRにつき1つのトピック/課題)
- 手順が現在のTinyCADの動作に即している
- 表現が明確で簡潔である
- リンク先が有効である
- 必要に応じてページがナビゲーションからリンクされている
- 既存のスタイルと用語が維持されている
再利用可能なブラウザー/デスクトップのタブセット
ページでTinyCADのブラウザー版とデスクトップアプリ版の異なる手順を示す必要がある場合は、ページ固有のマークアップを独自に作成せず、共通のタブセットコンポーネントを使用してください。
<div class="manual-tabset" data-tabset="product-mode" data-tabset-label="Choose your TinyCAD product" data-default-tab="Browser" markdown="1">
### Browser
Browser-specific content.
### Desktop App
Desktop-specific content.
</div>
注意事項:
data-tabsetは同期/保存用のキーです。同じページ上の複数のタブセットを同期させるには、同じ値を再利用します。data-default-tabは初回訪問時に選択されるタブを指定します。- 各タブの見出しは同じレベルにします(上の例では
###)。
PRテンプレートの例
次の内容をPRの説明にコピーして貼り付けてください:
## Summary
-
## What changed
-
## Why
-
## Validation
- [ ] Previewed locally with `npm run serve`
- [ ] Checked navigation and links
- [ ] Confirmed formatting on rendered page
## Screenshots (if relevant)
-
フォークを最新の状態に保つ
PRがしばらくオープンのままの場合は、ブランチを最新のmainに同期してください:
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
git checkout docs/v4-fix-rulers
git merge main
git push
よくある問題と対処法
- PRに無関係なファイル変更が表示される
- 更新済みの
mainから新しいブランチを作成し、自分のコミットだけをcherry-pickします。
- 更新済みの
- ナビゲーション項目が見つからない
docs/_data/navigation.ymlを更新し、URLがページのパーマリンクパスと一致していることを確認します。
- ページの表示がおかしい
- 見出しレベル、リストのインデント、フェンス付きコードブロックのマーカーを確認します。
- ローカルではリンクが機能するが、Pagesでは機能しない
- このリポジトリ内で使用されている相対リンクを優先し、ページ名の一貫性を保ちます。
提出後
メンテナーから修正を依頼される場合があります。追加のコミットは同じブランチ/PRに加えてください。PRは自動的に更新されます。承認されてマージされると、GitHub Pagesの再ビルド後に変更が公開マニュアルに反映されます。
TinyCADドキュメントの改善にご協力いただき、ありがとうございます。
- v4の目次に戻る