【トラブルシューティング】Notionブログのレイアウト崩れ対策 — callout・コードブロック・目次の罠

概要: Notion APIをCMSとしてブログを運用する際に遇遇したレイアウト崩れの原因と対策。calloutの子ブロック問題、連続コードブロック、[toc]残り、絵文字重複の4つの罠と解決策。

はじめに#

Notion 上ではきれいに見える記事が、ブログ上ではレイアウトが崩れる。Notion API のブロック構造の特性を理解しないと解決できない問題が 4 つありました。

1. callout/quoteの子ブロック問題#

症状#

Notionで1つのcallout内にリストを書いても、ブログでは各項目が個別のcalloutとして表示される。

原因#

Notion APIではcallout/quote内のリスト項目は子ブロックとして格納される。rich_textだけ取得してもリストは含まれない。

対策#

has_childrenをチェックし、子ブロックを再帰取得:

if (block.has_children) {
  const children = await notionFetch(
    `/blocks/${block.id}/children`
  );
  for (const child of children.results) {
    if (child.type === 'bulleted_list_item') {
      childContent += `\n- ${richTextToMarkdown(
        child.bulleted_list_item.rich_text
      )}`;
    }
  }
}

2. 連続コードブロックの間隔#

症状#

2つのコードブロックがくっついて表示される。

原因#

pre要素にmarginがなかった。

対策#

CSSで.znc pre { margin: 1.5rem 0; }を追加。またNotion記事側でも連続コードブロックの間に説明テキストを入れる運用ルールを追加。

3. [toc] テキスト残り#

症状#

記事内に [toc] や "[toc]" がそのまま表示される。

当時の対策#

HTML 生成後に正規表現で除去していました。

processedHtml = processedHtml
  .replace(/<p>\s*\[toc\]\s*<\/p>/gi, '')
  .replace(/"\[toc\]"/gi, '')
  .replace(/\[toc\]/gi, '');

4. callout絵文字重複#

症状#

calloutのアイコンとテキスト内の絵文字が両方表示される。

対策#

テキスト先頭の絵文字を正規表現で除去:

let cleanText = text.replace(
  /^[\u{1F300}-\u{1F9FF}\u{2600}-\u{27BF}]+\s*/u,
  ''
).trim();

Tips#

参考リンク#

• Notion API - Block children
• Notion calloutブロックをNext.jsでカラフルUIにする（別記事）
• Notion APIでブログシステムを構築する（別記事）

まとめ#

• Notion API のブロック構造を理解することが重要
• callout/quote の子ブロックは再帰取得が必要
• 整形後の HTML に正規表現を当てない。ブロック構造が残っている段階で処理する
• コード側の除去だけでなく、記事の書き方ルールも整備する