Cocoonの目次が記事の途中に出る問題を、子テーマで本文冒頭に動かした話

子テーマの functions.php に関数を一つ書き足したら、目次が本文の一番上に出るようになりました。実質的に書き換えたのは2行です。

Cocoon の目次は、本文中の最初の H2 タグの直前に挿入されます。設定画面に位置を変える項目はありません。preg_replace で H2 を探している処理を、本文冒頭への単純な連結に置き換えれば、目次は記事の頭へ動きます。

そう書くと2分で終わる話ですが、ここへたどり着くまでに数日使いました。設定タブを何度も見直し、検索を続け、実装してからカテゴリーページを壊しています。同じところで止まっている方のために、遠回りのほうから先に書きます。

設定タブに項目があるはずだと思い込んでいた

記事を書いていて自分のサイトを開いたら、目次が本文の途中に出ていました。導入文を4段落ほど書いて、最初の H2 に入ったところです。読み手からすれば、目次にたどり着くまでにそれなりの分量を読み終えていることになります。

Cocoon には、プラグインを入れなくても使える目次機能が標準で付いています。「Cocoon 設定」→「目次」タブを開くと、表示・非表示の切り替え、タイトル文言、見出しの深さ、何個以上の見出しで出すか、開閉ボタンの有無といった項目が並びます。

上が実際の目次タブで、いま見ても位置に関する項目はありません。下は、デフォルトで目次がどこに入るかを描いたものです。私はこのタブを3回くらい行ったり来たりしました。位置、表示場所、挿入箇所、Position。それらしい語を探して何度もスクロールしたのですが、表示位置を変える項目はどこにもありませんでした。あるはずだという前提で見ていたので、見つからないことに納得できなかったわけです。

記事構成で書くと、デフォルトの挿入位置はこうなります。

導入文が1行で済む記事なら、目次は実質的にほぼ冒頭へ出ます。4〜5段落書く記事だと、目次は数スクロール分だけ下へずれます。記事の全体像を先に把握したい読者は、そこまでスクロールするか、目次に気づかないまま本文を読み進めることになります。私は導入文を書いてから H2 に入るスタイルなので、これがずっと気になっていました。H3 から見出しを始める記事だと、設定によっては目次そのものが出ないこともあります。

数日かけて検索して、何も見つからなかった

Cocoon 目次 位置、Cocoon 目次 冒頭、Cocoon 目次 カスタマイズ。この種のキーワードで数日検索しました。国内で利用者の多いテーマなので、同じ悩みを書いた人が必ずいるはずだ、という前提で探していたわけです。ところが、設定タブの使い方を説明した記事はいくらでも出てくるのに、表示位置を変える話にはたどり着けませんでした。

目次の位置という、売上にも表示速度にも関係のない一点に数日使っている自分に、途中で少し笑えてきました。それでも気になるものは気になります。

設定で変えられず、検索でも出てこない。読むしかありません。lib/toc.php を開いたのは、そこからです。

カテゴリーページに目次が出て、慌てて直した

先に、実装したあとで踏んだほうの失敗を書きます。

最初のバージョンでは、表示の判定を親テーマと同じ is_total_the_page_toc_visible() だけにしていました。挿入処理を「本文の先頭に連結する」という雑な形にしたので、カテゴリーアーカイブとタグアーカイブの本文、つまり各記事の抜粋がまとまっている部分の先頭にも、目次が出ました。

サイトを開いたら、カテゴリーページの一番上、本来は記事一覧があるはずの場所に、見出しらしきリンク群がドンと出ています。目次がアーカイブのデザインを乗っ取ったように見えて、ぎょっとしました。原因は単純で、アーカイブ用の本文フィルターでも同じ関数が動いていただけです。

lib/toc.php を読んだとき、the_content に加えて the_category_content と the_tag_content にも同じフィルターが登録されているのは目に入っていました。目に入っていたのに、最初のコードには反映していません。

いま動いているコードを、先に全部置きます

子テーマの functions.php に追記しているのは、これで全部です。長く見えますが、親テーマの関数をコピーしてきて、挿入処理と表示判定の2か所を書き換えただけです。

lib/toc.php を読んだら、正体は1行だった

書き換える前に、Cocoon がどうやって目次の位置を決めているのかを読みました。仕組みを分からないまま触ると、関係のない場所まで壊しかねません。目次まわりは、Cocoon の中でこう分かれていました。

いじりたいのは挿入位置なので、本体は lib/toc.php です。311行目あたりに、こんな登録がありました。

the_content フィルターで、本文が表示される前に add_toc_before_1st_h2 を通しています。関数名がそのまま挙動です。ここで the_category_content と the_tag_content にも同じ登録があるのが、さきほどの事故の伏線でした。

同じファイルの389行目あたりに、実際の挿入処理があります。

効いているのは最後の行です。

分解すると、H2_REG が H2 タグを検出する正規表現、$html が生成された目次の HTML、$h2result がマッチした H2 タグそのもの、最後の引数 1 が「最初にマッチした1つだけ置換する」という指定です。正規表現で本文の最初の H2 を探し、その位置に目次を割り込ませている。これがデフォルト動作の正体でした。

H2_REG の定義も見ておくと、lib/ad.php の166行目にありました。

<h2 という文字列にマッチするだけの、素朴な正規表現です。/i フラグで大文字小文字は区別していません。

親テーマを触らずに、関数だけ差し替える

Cocoon は更新頻度の高いテーマです。親テーマのファイルを書き換えても動きはしますが、アップデートのたびに消えます。それは続けられないので、子テーマ「Cocoon Child」を使います。公式サイトでダウンロードできます。

コードを読んでいて気づいたのが、関数定義の書き方でした。

function_exists で「この名前の関数がまだ定義されていなければ」と条件を付けて、その中で定義しています。先に同名の関数があれば、こちらは何もしない、というロジックです。WordPress は子テーマの functions.php を親テーマより先に読み込むので、子テーマで同じ名前の関数を定義しておけば、親テーマ側の判定が「もうあるから定義しない」になり、こちらの関数が使われます。

カスタマイズしやすいように、あえてこの書き方にしてあるようです。ここは素直にありがたかった。

上の3枚は、順に preg_replace で H2 を探して挿入する流れ、親テーマと子テーマの読み込み順と function_exists の判定、そして変更前と変更後の処理の違いです。

書き換えたのは2か所だけ

ひとつ目。親テーマでは、最初の H2 を正規表現で探して、その位置に目次を挿入していました。

子テーマでは、これを単純な文字列連結に変えました。

H2 タグを探さなくなったので、$h2result も get_h2_included_in_body() の呼び出しも要りません。

ふたつ目。親テーマの表示判定は、これだけでした。

子テーマでは is_singular() を足しています。

is_singular() は、個別の投稿・固定ページが表示されているかを判定する WordPress の関数です。これを足すと、目次が出るのは個別記事だけになります。最初のバージョンには、この1行が入っていませんでした。カテゴリーページを壊してから足しています。

1行だけ書けばいいのに、関数まるごとコピーした理由

挿入の1行だけ書き換えたいなら、その1行だけ書けばいいのでは。私も最初はそう考えました。

ただ、この関数の中には、挿入処理のほかにも残したい処理が入っています。Table of Contents Plus プラグインとの競合を避けるチェック、ページ単位の表示・非表示の判定、それに各見出しへ id="toc1" id="toc2" のような ID を振る処理。最後の ID 付与がないと、目次のリンクをクリックしても何も起きません。挿入位置だけ書き換えて元の関数を呼ぶ形も検討しましたが、それなら関数ごと差し替えるほうが素直だと判断しました。

動かしてから、ここを見た

変更前と変更後です。

導入文より前、本文の一番上に目次が出ています。H2 で始まる記事でも、p タグで始まる記事でも、同じ位置に出ます。

あとは順に、目次の各項目をクリックして対応する見出しまでスクロールするか。ID 付与処理を残しているので、ここが動かないならコードの貼り付けに漏れがあります。目次タブで設定したタイトル文言、見出しの深さ、開閉ボタン、表示条件が反映されているか。投稿編集画面の「目次を表示しない」にチェックを入れた記事で、目次が消えるか。そしてカテゴリーアーカイブとタグアーカイブを開いて、目次が出ていないこと。最後のひとつは、自分で壊した場所なので念入りに見ました。

うまく動かないときに見る場所

検証中に引っかかった順に書きます。目次が出てこないときは、ブラウザのキャッシュを消して Ctrl+F5 で強制リロード。キャッシュプラグインが入っていれば、そちらもクリアします。Cocoon 設定で目次が表示するになっているか、記事に表示条件を満たすだけの H2 / H3 があるかも見ます。

PHP エラーが出るときは、コピペで全角スペースが混ざっていないか。functions.php の先頭にすでに <?php があるのに、もう一つ書いていないか。波括弧の対応が合っているか。

目次が2つ出るなら、子テーマの関数定義が親テーマより後に読み込まれています。外観 → テーマで、子テーマが有効になっているか確認します。

カテゴリーページにも目次が出るなら、is_singular() が抜けています。条件式が if (is_total_the_page_toc_visible() && is_singular()) になっているか見直してください。&& の位置を間違えても文法上は通ってしまうので、閉じ括弧の位置ごとエディタで確認するのが確実です。

ショートコードでもできる、けれど選ばなかった

Cocoon には [ toc ] ショートコードもあります。自動表示をオフにして、好きな位置に書く方法です。記事ごとに目次の位置を変えたいなら、こちらのほうが向いています。

私の目的は全記事で本文冒頭に出すことだったので、毎回ショートコードを書く形は選びませんでした。書き忘れます。記事数が増えるほど、運用は雑になります。

遠回りのほうが長かった

差分そのものは小さい話でした。preg_replace の1行を、文字列連結の1行に置き換えただけです。

いちばん時間を使ったのは、設定タブに位置の項目があるはずだと信じて、画面を何度も見直していた時間でした。便利なテーマならこういう項目はあるはずだ、という思い込みが、画面を素直に読むのを邪魔していました。次に取った行動が検索で、これも数日続けて、表示位置のカスタマイズを扱った記事には行き当たりませんでした。ソースを開いてみれば、関数名を見ただけで挙動が想像できる構造です。function_exists でラップされていることに気づくのも、ファイルを開いてしまえばすぐでした。

検索して答えが見つからない問題は、ある意味では当たりだとも思いました。同じところで困っている人がいて、まだ誰も書いていないということだからです。だからこの記事を残しています。Cocoon は function_exists でラップされた関数が多いので、目次に限らず、設定では届かない挙動を子テーマで書き換えられるはずです。

ただ、設定タブを諦めてからソースを開くまでの数日を、どこまで詰めればよかったのかは、いまも決めかねています。設定で変えられないと分かった時点で、すぐコードを読みに行くべきだったのか。それとも、数日検索してから読みに行くくらいが、ちょうどよかったのか。あなたなら、どのあたりで見切りをつけますか。

Cocoonでサムネイルがぼやけた｜以前あったRetina設定が見つからなかった話と、子テーマで直した記録

Cocoon のサムネイルが MacBook や iPhone でぼやけて見えたとき、公式マニュアル通りに探しても見つからなかった Retina 設定を、子テーマの functions.php から復活させた検証記録です(2026年1月、私の環境での実測)。

raplsworks.com

参考リンク

• Cocoon 公式サイト
• Cocoon 子テーマのダウンロード
• Cocoon 目次機能の使い方