はじめに

hkob の雑記録の第507回目(連続80日目)は、Markdown の page への追加の変更について解説します。

ChangeLog の表記

5/15 に以下の ChangeLog が記載されていました。

Update page markdown エンドポイントが insert_content.position をサポートしました。これにより、ページ全体を書き換えずに、Markdown をページの先頭に挿入（prepend）したり、末尾に明示的に追加（append）したりできるようになります。例は Working with markdown content を参照してください。

Update a page’s content as markdown

以前、markdown によるブロックの追加機能が提供され、NotionRubyMapping でも実装してきました。この機能が以下のように変更されています。順に説明していきます。

Updating content with search-and-replace (recommended)

update_content コマンドを使用して、検索と置換の操作（search-and-replace）を配列で指定し、狙った箇所だけを編集します。各操作では、検索する old_str と、置き換える new_str を指定します。ページ全体を書き換えずに正確な編集ができるため、この方法が推奨されます。

ページの一部を書き換える場合には、この update_content を使うようです。以前の replace_content_range はこちらに置き換えられるようです。

Replacing all page content (recommended)

replace_content コマンドを使用して、ページ全体の内容を新しい Markdown で置き換えます。置き換え後の全文を new_str に指定します。

ページの内容を全て書き換える場合に、このコマンドを利用します。ここまでの二つの API だけが現在推奨されるようです。

Inserting content (legacy)

insert_content コマンドを使用して、ページに新しい Markdown コンテンツを追加します。先頭に挿入（prepend）するには position: { "type": "start" }、末尾に明示的に追加（append）するには position: { "type": "end" } を指定します。position を省略すると、ページ末尾に追加されます。特定の位置に挿入したい場合は after セレクションを指定できます。after は 省略記号（...）を使ったセレクション 形式で、"start text...end text" のように指定します。

これは以前 NotionRubyMapping でも実装した markdown コンテンツの挿入です。しかし、これは legacy となってしまいました。以下のように追加説明が書かれています。

代わりに update_content または replace_content の使用を推奨します。insert_content コマンドは引き続きサポートされていますが、将来のバージョンで非推奨（deprecated）になる可能性があります。

これについて、とうまろさんは何故これが legacy なのかとポストされていました。

Notion APIでコンテンツ挿入するときにページの最後に指定できるオプションが追加されてた。

でもよく見たらinsert_contentはレガシーで推奨されていない（どゆこと？）かわりにupdate_content使いましょうと。

追記だけのケースならページ全体を作り直さなくていいから便利だと思うけどな。 pic.twitter.com/xeFLSoVsYS
— Touma Hoshino（とうまろ） (@heytoumaro) 2026年5月19日

これについて、私は以下のように返信しました。個人で API で利用するならあまり問題がないものの、現在は MCP や worker などからもページ更新がされることがあり、複数同時アクセスのことを検討する必要があるのでしょうね。git などの差分管理の場合でも、最終行へのコード追加はコリジョンの元凶になることが多いので、仕方ないのかもしれません。

個人で API 使うのならともかく AI で駆動すると複数同時アクセスなどのことも検討する必要があるので、変更場所を特定したいのでしょうね。

最終行を常に検索するのは面倒なので、私なら最終行に常に決め打ちの固定行を書いてしまって、それを目印にその直前に追加する markdown を書くかも。
— hkob｜Notion Ambassador (@hkob) 2026年5月19日

Replacing a content range (legacy)

replace_content_range コマンドを使用して、既存コンテンツの一致した範囲を新しい Markdown に置き換えます。content_range パラメータは after と同じ 省略記号（...）を使ったセレクション 形式を使用します。

こちらも NotionRubyMapping で実装したばかりですが、こちらも legacy になってしまいました。こちらも update_content を使うように追記がありました。