WP-TOC: Най-леката Table of Contents за WordPress

WP-TOC се роди от една наглед обикновена поръчка, която се превърна в техническо предизвикателство и удоволствие за решаване. Клиентът се свърза с мен с конкретна болка — всички налични Table of Contents плъгини за WordPress бяха прекалено тежки, натоварваха DOM-а, вкарваха jQuery или бяха ограничени до определени теми. „Искам нещо, което просто работи,“ каза той. „Без панели с настройки, без скрити опции, без ненужен CSS. Само плъгин, който знае кога и къде да се появи.“ Това беше моментът, в който идеята за WP-TOC започна да се оформя — минималистичен плъгин, който не се опитва да бъде „по-добър“ от другите, а просто по-чист. Без зависимости, без скриптове от трети страни, без нужда от визуален интерфейс. Всичко да се случва тихо и интелигентно, още при зареждането на съдържанието. Идеята беше една: автоматично, леко и невидимо Table of Contents решение, което не нарушава структурата на публикацията, а я прави по-достъпна и удобна — както за читателя, така и за търсачките. Поръчката дойде днес сутринта — от онези съобщения, които започват с „Имам нещо малко, но спешно.“ Клиентът беше прекарал предишната седмица в тестване на поне пет различни TOC решения от WordPress репозиторито. Всички изглеждаха добре на пръв поглед, но след инсталация се оказваха или прекалено бавни, или твърде натоварващи за страниците. Някои добавяха по 200 KB ненужен JavaScript, други зареждаха по няколко CSS файла, а трети просто чупеха структурата на съдържанието при custom теми. Той искаше нещо различно — плъгин, който се интегрира естествено, без панел за настройки, без тежък UI, без конфликти. Да може да постави Table of Contents във всеки пост автоматично, без shortcode, без блокове и без да се тревожи дали ще изглежда „добре“. Просто функционално, минималистично, и най-важното — бързо. Тази конкретика ми хареса. Когато някой знае какво иска — скорост, чистота и автоматизация — решението винаги идва бързо. В този случай, идеята за WP-TOC се оформи още преди да съм затворил имейла.

Идеята

WP-TOC анализира съдържанието и вмъква списък от заглавия преди първия <h2>.
Използва само един WordPress hook:

Php

add_filter('the_content', function($content) {
  if (is_singular() && strpos($content, '<h2') !== false) {
    $toc = '<div id="wp-toc"><ul></ul></div>';
    return preg_replace('/(<h2[^>]*>)/', $toc . '$1', $content, 1);
  }
  return $content;
});

Резултатът

За по-малко от 9 часа – готов, лек и функционален плъгин. WP-TOC вече е open-source в GitHub и може да се интегрира с всяка тема. Без настройки. Без конфигурация. Само чист код.

Поуката

Понякога най-добрите WordPress решения се раждат от нуждата за простота. WP-TOC е точно такъв проект – създаден за скорост и яснота.

Процесът на разработка

Планиране (1 час):
Първо дефинирах логиката – автоматично парсване на заглавията и вмъкване преди първия H2.
Записах 3 основни правила:

Без външни зависимости
Малки админ настройки
Под 10 KB общ размер

Техническа реализация и архитектура

След като определих целта — лек, автоматичен и беззависим Table of Contents плъгин — започнах да изграждам архитектурата около три прости принципа: Без jQuery или външни библиотеки Минимално DOM взаимодействие Пълна съвместимост с всички билдъри Плъгинът сканира съдържанието на публикацията, идентифицира всички H1–H6 заглавия и автоматично генерира Table of Contents преди първия H2. Всяка секция получава anchor с хеш линк, а фронтенд частта използва IntersectionObserver за „жив“ scroll spy и плавна навигация. Основни функционалности:

Автоматично генериране на TOC от H1–H6
Опция за автоматично вмъкване по тип публикация или чрез shortcode/widget
Поддръжка на плавно скролиране и йерархична структура
Вграден брояч (вътрешен или външен)
Sticky TOC widget с toggle бутон
Пълна съвместимост с Classic Editor, Gutenberg, Elementor, Divi и WPBakery
Напълно преводим (translation-ready), включително възможност за принудителен език в админ панела

Инсталация и употреба

Качи плъгина в wp-content/plugins/wp-toc/ или инсталирай чрез WordPress Admin → Plugins.
Активирай го.
Отвори Settings → Table of Contents, за да конфигурираш опциите.

Начини за използване:

Автоматично вмъкване: Settings → Table of Contents → General → Auto Insert

Shortcode: [wp-toc]

Sticky widget: Appearance → Widgets → TOC Sticky

Shortcode параметри:

Php

[wp-toc 
  header_label="Title" 
  display_header_label="no" 
  toggle_view="no" 
  initial_view="hide|show" 
  display_counter="no" 
  heading_levels="2,3" 
  class="custom_toc"
]

Локализация

Text domain: wp-table-of-contents
Преводи: постави .mo/.po файлове в директорията languages/
Принудителен език на админ интерфейса: Settings → Table of Contents → General → Plugin UI Language

Философия на кода

Всяка функция е написана с идеята за предвидимост и стабилност. Никакви магии – само логичен, четим и оптимизиран код, който можеш да разбереш за минути.

Тестване (2 часа):
Пробвах го с класически теми (Twenty Twenty-Four, Astra) и headless среда с Next.js.
Резултатът: стабилно, мигновено зареждане без конфликти.

Оптимизация в реално време

Вместо да добавям кеш или компресия, оптимизацията беше в самия код — минимално DOM взаимодействие и почти нулев footprint.

Защо е важно едно леко Table of Contents решение

Критерий	Тежки TOC плъгини	WP-TOC
Размер на скриптовете	100–300 KB	под 9 KB
Зависимости	jQuery, lodash	Никакви
Рендиране	След DOM load	Сървърно + JS за обновяване
Скорост на зареждане	Видима латентност	Незабавно
Поддръжка	Чести конфликти с теми	Универсална съвместимост

Скорост и UX

Едно TOC, което се зарежда мигновено, подобрява UX и SEO едновременно — Google оценява чиста структура и достъпност.

Производителност и ефективност

Разпределение на времето за разработка

WP-TOC е пример как правилната архитектура елиминира нуждата от оптимизация след това.
Когато кодът е структуриран чисто, скоростта идва естествено.

Може да разгледате кода тук:WP-TOC в GitHub →

WP-TOC е пример, че ефективният код не се мери по редове, а по това колко незабележимо подобрява преживяването.

Ако и ти искаш custom WordPress плъгин, който е бърз, лек и създаден точно за твоя проект — пиши ми и ще го направим да просто работи.