Theme-Aware Discovery
How the smart discovery logic works without CSS selectors
Our Table of Contents isn't just a static tool—it’s a dynamic engine that "looks" at the page like a human would to find your article content. Instead of requiring you to provide an exact CSS selector for every single theme, the engine uses intelligent discovery to adapt to your store automatically.
---
🧠 Why is it "Smart"?
In the past, if a theme changed its container from .article-content to .post-body, the Table of Contents would simply disappear. Our discovery engine fixes this with three layers of intelligence:
1. The H1 Proximity Anchor
The engine starts by finding your Article Title (H1). It knows that the actual content is almost always the largest block of text immediately following that title.2. Lowest Common Ancestor (LCA) Algorithm
If multiple blocks of text are found, the engine analyzes the HTML tree to find the "Lowest Common Ancestor"—the single container that holds all your headings and paragraphs together. This ensures the ToC is injected exactly where your readers are looking.3. Self-Healing Verification Loop
Websites can be dynamic. If a theme lazily loads content or changes its layout via JavaScript, our 2-second verification loop will detect the change, re-run the discovery logic, and ensure the ToC remains visible and correctly positioned.---
⚡ Performance & Compatibility
Zero Dependencies
The engine is built with Pure Vanilla JavaScript (ES6). It does not require jQuery or any other external libraries, making it compatible with modern headless themes and legacy liquid themes alike.Optimized Discovery
The discovery logic runs once immediately upon page load. If the content is found, the ToC is injected; if not, the engine waits for the DOM to stabilize and tries again. This "Wait & Verify" strategy ensures compatibility with apps that modify the page structure after load.---
Want to see exactly how your theme is being discovered? Check out the Developer API & Events guide to hook into the discovery lifecycle.