GitHub 連携
記事を Markdown または Markdoc ファイルとして GitHub リポジトリに公開し、Keystatic などの Git ベース CMS で利用できます。
Rankturn は、記事を Markdown（.md）または Markdoc（.mdoc）ファイルとして GitHub リポジトリに直接公開できます。各記事は、先頭にタイトルや説明などの情報がまとめられた 1 ファイルとして、指定したブランチ・フォルダに保存されます。これにより、Keystatic、Astro の content collections、Next.js の MDX ブログ、Hugo といった Git ベースの公開ツールや静的サイト構成に、Rankturn をそのままコンテンツソースとして組み込めます。
公開すると、Rankturn はファイルを新規作成（または既存ファイルを更新）し、その変更に [rankturn] というラベルを付けるため、変更履歴の中で見分けやすくなっています。
双方向ワークフロー全体での位置づけは双方向同期を参照してください。
接続する
- 設定 → 連携 を開き、GitHub のカードを探します。
- 接続 をクリックして接続ウィザードを開きます。
- GitHub の Personal Access Token（PAT） を作成します。
- github.com/settings/tokens/new を開きます。
- 名前を付け、repo スコープを選択します（Rankturn はリポジトリ内容への読み取り・書き込みアクセスが必要です）。
- トークンを生成してコピーします。GitHub はトークンを一度しか表示しません。
- ウィザードの各項目を入力します。
| 項目 | 説明 | 既定値 |
|---|---|---|
| Personal Access Token | 作成した PAT。 | — |
| オーナー（Owner） | リポジトリのオーナー（GitHub のユーザー名または Organization 名）。 | — |
| リポジトリ（Repository） | リポジトリ名（URL ではなく名前のみ）。 | — |
| ブランチ（Branch） | Rankturn がコミットするブランチ。 | main |
| ディレクトリ（Directory） | ファイルを書き込むリポジトリ内のフォルダ。 | content/posts |
| ファイル形式（File Format） | Markdown（.md） または Markdoc（.mdoc）。 | Markdown |
- 接続 をクリックします。保存前に Rankturn が接続を確認し、トークンが有効か、リポジトリとブランチが存在するか、トークンに書き込み（push）権限があるかをチェックします。いずれかに失敗すると、具体的なメッセージが表示されます（トラブルシューティングを参照）。
接続が完了すると、記事を公開・予約する際の公開先として GitHub が表示されます。
接続内容の編集。 GitHub カードの 設定を編集（Edit Settings） をクリックすると、オーナー・リポジトリ・ブランチ・ディレクトリ・ファイル形式を変更できます。トークン欄を空欄のままにすると既存のトークンが保持され、新しい値を入力したときだけ置き換えられます。
トークンについて。 Personal Access Token はリポジトリへの書き込みアクセスを許可します。Rankturn はトークンを暗号化して保存します。詳細は認証情報とセキュリティを参照してください。
ファイル形式
接続ごとに 1 つの形式を選び、それがファイル拡張子になります。
| 形式 | 拡張子 | 主な用途 |
|---|---|---|
| Markdown | .md | 多くの静的サイトジェネレーター、MDX ブログ、Hugo、Astro。 |
| Markdoc | .mdoc | Keystatic など Markdoc ベースの CMS。 |
公開される各ファイルは、先頭に情報のまとめ、続いて Markdown 形式の本文という構成です。このまとめには、タイトル、メタディスクリプション、公開日、著者（設定されている場合）、タグ（記事に付いている場合）、カノニカル URL（設定されている場合）、そして生成済みの構造化データ（Schema.org）が含まれます。
記事のスラッグはこのまとめには含まれず、代わりにファイル名になります（記事は your-slug.md / your-slug.mdoc として保存されます）。これは Keystatic のように、独立したスラッグ項目を想定していないツールとの互換性を保つためです。同じ理由から、キーワードも意図的に出力されません。
双方向同期
GitHub 連携は初期状態では一方向で、Rankturn からリポジトリへ記事をプッシュするだけです。双方向同期（Bidirectional Sync） をオンにすると、GitHub 側で行った編集が Rankturn に取り込まれるようになり、共同編集者がファイルを直接編集した場合でもリポジトリを正本として保てます。
有効化する。 GitHub カードで 双方向同期 をオンに切り替えると、Rankturn がリポジトリに即時通知のしくみを設定し、プッシュするたびにすぐ Rankturn へ通知が届くようになります。（この設定にはリポジトリの Webhook を管理する権限が必要です。接続は内部で安全に保護されます。）
プッシュごとの処理。 変更をプッシュすると、Rankturn は次のように処理します。
- 通知が本当にあなたのリポジトリから届いたものかを確認し、確認できないものは無視します。
[rankturn]のラベルが付いた変更はスキップします。 これは Rankturn 自身の公開によるものなので、スキップすることで終わりのない同期ループを防ぎます。プッシュに Rankturn 自身の変更しか含まれない場合は、そのプッシュ全体を無視します。- 選択したフォルダ内の
.mdおよび.mdocファイルのみを対象とし、それ以外は無視します。 - 変更された各ファイルを既存記事と照合し、一致すればその記事を更新します。一致するものがなければ、新しい記事を下書きとして作成します。
同じ記事が両方で変更された場合。 Rankturn は同期した各記事について、GitHub 側の最新バージョンを記録しています。変更が届いたとき、
- 前回同期時からファイルが実際には変わっていない場合、Rankturn はそのファイルをスキップします（無駄な更新は行いません）。
- 前回同期後に Rankturn 側でも記事が編集されていた（真のコンフリクト）場合は、GitHub 側の内容が優先され、リポジトリが正本として扱われます。コンフリクトとして記録されるため、発生したことを確認できます。
ファイルを削除しても記事は削除されません。 リポジトリから Markdown ファイルを削除しても、対応する記事は Rankturn では削除されません。削除は記録されたうえでスキップされるため、誤って削除しても Rankturn のコンテンツが失われることはありません。
手動同期。 プッシュを待つ必要はありません。カードの GitHub から同期（Sync from GitHub） をクリックすると、選択したフォルダ内に現在ある Markdown／Markdoc ファイルをすべて取り込み、記事と一括で突き合わせます。初回取り込みや、まとめて編集したあとに便利です。完了後、同期できた件数と失敗した件数が表示されます。
無効化する。 双方向同期 をオフに切り替えると、Rankturn は GitHub から即時通知のしくみを削除し、保存していた接続情報を消去します（GitHub 側ですでに削除されていても問題なく、見つからないケースは適切に処理されます）。
パスの安全性
入力したフォルダは、ファイルが保存される前にチェックされ、無効または安全でないパスからリポジトリを保護します。
- 先頭・末尾のスラッシュと前後の空白は除去されます。
- 使用できるのは英数字、ハイフン（
-）、アンダースコア（_）、スラッシュ（/）のみで、それ以外は拒否されます。 ..や//を含むフォルダは拒否されるため、ファイルが指定したフォルダの外に出ることはありません。
スラッグにまれに含まれる特殊文字も安全に扱われます。
トラブルシューティング
「Invalid GitHub token. Please check your Personal Access Token.」 — トークンが誤っているか期限切れです。repo スコープ付きの新しい PAT を作成し、接続し直してください。
「Repository … not found.」 — オーナーまたはリポジトリ名が誤っています。オーナー（ユーザー名または Organization 名）と、URL ではなくリポジトリ名のみを入力してください。
「Branch '…' not found in repository.」 — 指定したブランチが存在しません。Rankturn はメッセージ内に利用可能なブランチ一覧を表示するので、正しいものを選べます（リポジトリが空の場合はその旨も表示されます）。
「Your token does not have write access to this repository.」 — トークンでリポジトリを読めても push できません。repo スコープ付きで作り直し、書き込み（push）権限を付与してください。
双方向同期が有効化できない／「webhook 権限」エラー — 即時通知のしくみの設定には、リポジトリの Webhook を管理する権限が必要です。そのリポジトリで Webhook を管理できるトークン（およびアカウント）を使用してください。
プッシュが同期されない — 双方向同期 がオンであること、編集が正しいブランチに保存され、正しいフォルダ内に置かれていること、ファイルの拡張子が .md または .mdoc であることを確認してください。[rankturn] のラベルが付いた変更は仕様によりスキップされます。うまくいかない場合は GitHub から同期 をクリックして手動で突き合わせてください。
Rankturn で行った編集が上書きされた — 同じ記事が GitHub 側でも変更されていた場合に発生する、想定どおりの動作です。コンフリクト時は GitHub 側が優先されます。正本となる編集はリポジトリ側で行うか、先に同期してから Rankturn で編集し、次のプッシュに反映してください。
保存されるトークンや接続情報がどのように安全に保たれるかについては認証情報とセキュリティを参照してください。