Typemark Documentation

ReadMeから移行する

ReadMeプロジェクトをGitHubに同期するか書き出して、リポジトリをインポートします。カテゴリフォルダがナビゲーションになり、ページの順序は_order.yamlで決まり、MDXの構文はそのまま残ります。

2026年11月19日更新

ReadMeは双方向同期機能で、プロジェクトをフォルダ構成のMarkdownファイルとしてGitHubリポジトリに書き出せます。Typemarkはそのリポジトリをインポートします。カテゴリフォルダごとにナビゲーショングループが作られ、_order.yamlでページの順序が決まり、APIリファレンスページはOpenAPIファイルからエンドポイントを表示します。

ReadMeのページはMDXなので、Typemarkはそのまま読み込みます。excerptはページの説明として機能し、<Callout>、<Image>、<Cards>、<Embed>は変更なしで表示されます。インポートではURLが変わらないようにファイルを移動し、ReadMeでしか表示されない絵文字付きのコールアウトやdoc:リンクなどは、レビューできる1つのコミットで変換します。

始める前に

  • ReadMeのプランにGitHub同期が含まれているか、プロジェクトを書き出せること。プランはReadMeで確認できます。
  • ReadMeの同期には、新規で空のリポジトリが必要です。コミットもREADMEもない状態にしてください。
  • リポジトリのサイズは100 MB以下であること。

プロジェクトをインポートする

  1. プロジェクトをGitHubに同期する

    ReadMeで、プロジェクトを新規の空のGitHubリポジトリに接続します。ReadMeはdocs/、reference/などのフォルダを書き込みます。ReadMeの各バージョンはブランチになっており、Typemarkは接続時に選んだブランチをインポートします。別のブランチを選ばなければ、デフォルトブランチが使われます。

  2. Typemarkプロジェクトを作成する

    New projectをクリックして名前を付け、Start fromでImport from GitHubを選びます。Create and connect GitHubをクリックし、Typemark GitHub Appにリポジトリへのアクセスを許可します。

  3. リポジトリを選ぶ

    TypemarkにReadMe project detectedと表示されます。Importをクリックして確認します。

  4. インポート結果を確認する

    Typemarkがtypemark.jsonを書き出し、旧来の構文を1つのコミットで変換して、プッシュし、サイトをビルドします。プロジェクトの概要にインポートのサマリーが表示されます。

  5. 画像を移行する

    ReadMeにアップロードした画像はfiles.readme.ioでホストされています。現時点では引き続き表示されますが、ReadMe上に置かれたままです。サマリーには、それらを使っているページが一覧で表示されます。images/にダウンロードしてリンクを更新してから、ReadMeを解約してください。コーディングエージェントにやらせることもできます。

  6. 同期を止めて公開する

    ReadMeでGitHub同期を切断し、公開前チェックリストを済ませてから、Settings > PublishingでGo liveをクリックします。

変換される内容

ReadMeTypemark
docs/内のカテゴリフォルダフォルダ名のナビゲーショングループ。Guidesタブに表示
ページファイルReadMeのURLに合わせて移動されるため、/docs/my-pageは/docs/my-pageのまま。入れ子になったページの古いフラットURLにはリダイレクトが設定される
_order.yamlグループ内のページ順序。ファイル自体は削除される
index.mdとサブページを持つフォルダインデックスページが先頭に来て、その後に同じグループ内のサブページが続く
APIリファレンスページ(operationId付きのapi:)同じURL・同じ位置のエンドポイントページ。API Referenceタブに表示される。各ページは、ページ本来のテキストと一緒に仕様のエンドポイントを表示する。Typemarkはフロントマターにopenapi: "<spec> METHOD /path"を追加する
リファレンスページのないreference/内のOpenAPIファイルAPI Referenceタブに生成されたAPIページ
titletitle
excerptページの説明として、そのまま使われる
hidden: trueサイドバーから非表示になるが、URLからは引き続きアクセスできる
<Callout icon="📘" theme="info">コールアウトとして表示され、ビジュアルエディタで開く。書かれたとおりに保存される
<Image>、<Cards>、<Columns>、<Embed>、<Table>、<Anchor>書かれたとおりに表示される。YouTube、Vimeo、Loom、Wistiaの動画の<Embed>は再生される
> 📘 Title形式の絵文字付きコールアウト対応するテーマの<Callout>
doc:、ref:、recipe:リンクTypemarkのページへのリンク
用語集プレーンテキスト
HTMLコメントMDXではビルドできないため削除される
レシピとカスタムページ通常のページとして、RecipesとPagesグループに入る

引き継がれない内容

  • files.readme.io上の画像は、移動するまで外部に置かれたままです。手順5を参照してください。
  • 複数バージョン。 1つのプロジェクトでインポートできるのは、接続時に選んだ1つのブランチだけです。
  • APIの「Try it」設定と保存済みのキー。TypemarkのAPIページは、仕様ファイルのリファレンスを表示します。
  • <<company>>などの変数はテキストのまま残り、サマリーに一覧されます。
  • changelogs/内の変更履歴の投稿はインポートされません。必要なものは変更履歴エントリで作り直してください。
  • **<HTMLBlock>と<TutorialTile>**はサポートされておらず、サマリーに一覧されます。
  • カスタムCSSと、リポジトリではなくReadMe側にある他の設定。

ターミナルから実行する

書き出したファイルや同期済みのリポジトリをお使いのコンピュータで変換するには:

cd my-readme-project
typemark migrate             # detects the ReadMe project and converts it, then offers to create the project and push it

「yes」を2回答えれば、サイトはTypemarkに移行されます。公開するまではオフラインのままです。CIやコーディングエージェントから実行する場合は、代わりにtypemark migrate --create "My Docs" --pushを使ってください。

typemark migrateは、GitHubインポートと同じ変更を書き込みます。結果をgit diffで確認できるよう、先に作業をコミットするかstashしてください。

コーディングエージェントと使う

コーディングエージェントは、files.readme.ioの画像をダウンロードし、レシピをガイドにまとめ、サマリーに挙がった問題を修正できます:

typemark migrate --from readme --agent claude

コーディングエージェントと使うを参照してください。