{{page>public:condition_toc_resolution_banner&inline}}
====== Condition Plugin, Include Plugin, and TOC Interaction (Resolution – April 2026) ======

This page documents the resolution of a cascading Table of Contents issue that occurred when using the Condition plugin together with the Include plugin on a PHP 8 environment. It is published for the benefit of other administrators who may encounter similar behavior.

~~NOCACHE~~

===== Summary =====

A page that used the Condition plugin to display a time‑based announcement behaved correctly on a local DokuWiki installation, but produced duplicated and cascading TOC entries when deployed on a shared hosting environment. The issue was reproducible only when the Condition plugin and an Include block were placed near the top of the page, causing the parser to misinterpret heading boundaries.

The root cause was a combination of:

  * The Condition plugin’s TOC‑merging behavior in both XHTML and metadata modes  
  * The Include plugin creating implicit section boundaries  
  * A DokuWiki parser rule that no plugin block may appear between the page title and the first heading  
  * Differences in PHP 8 handling of the Condition plugin’s internal logic  
  * The discovery that plugin blocks placed immediately after the first heading also destabilize TOC construction  
  * The final finding that an Include block is safe only when placed at the very top of the page, before all headings, where it is evaluated during the pre‑parse stage rather than during TOC assembly  

After applying PHP 8 compatibility fixes and restructuring the page so that the Include banner appears as the first element on the page—above the page title and before any headings—the TOC stabilized and the Condition plugin behaved consistently across environments.

===== Environment =====

  * DokuWiki: current stable release  
  * PHP: 8.x  
  * Condition plugin: original Etienne Méleard version with local fixes  
  * Include plugin: standard  
  * Discussion plugin: enabled  
  * Hosting: shared hosting environment  

===== Technical Findings =====

==== 1. Condition Plugin Behavior ====

The Condition plugin merges TOC arrays during rendering. When a Condition block appears before the first heading, the merge occurs before DokuWiki has established the page’s section structure. This results in duplicated or flattened TOC entries.

Local fixes applied:

  * Guard against null TOC arrays  
  * Skip ``document_start`` and ``document_end`` instructions  
  * Safe metadata TOC merging  
  * Added PHP 8‑safe string offsets  

==== 2. Include Plugin Interaction ====

The Include plugin introduces implicit section boundaries. When combined with Condition blocks above the first heading, this caused the parser to enter a “frozen heading state,” producing:

  * duplicated top‑level headings  
  * cascading TOCs  
  * phantom sections  

Wrapping the include with ``nosection`` prevents this.

==== 3. Structural Rule (Critical) ====

DokuWiki cannot tolerate plugin blocks between the page title and the first heading.

**Rule:**  
Do not place Condition, Include, or WRAP blocks between the page title and the first heading.

This is a core parser behavior, not a plugin bug.

===== Temporal Conditions =====

The Condition plugin’s ``time`` test accepts full date and time formats. A ``date`` test has been added locally and mirrors the same logic.

Examples:\\ 
''<if date >= 2026-04-01>\\ 
Content visible on or after April 1, 2026.\\ 
</if>\\ 
\\ 
<if date >= 2026-04-01 && date <= 2026-04-20>\\ 
Content visible only during April 1–20, 2026.\\ 
</if>\\ 
\\ 
<if date >= "2026-04-01 08:00" && date < "2026-04-01 17:00">\\ 
Content visible during business hours on April 1.\\ 
</if>''\\ 

===== Rules for Stable Operation =====

  * No plugin blocks above the first heading  
  * Wrap includes with ``nosection``  
  * Do not wrap headings inside Condition blocks  
  * Purge cache after modifying Condition logic (``?do=purge``)  
  * Avoid Condition blocks inside table cells  

===== Resolution =====

After applying the PHP 8 fixes, adding the ``date`` test, and restructuring the page so that the Include banner appears as the first element on the page, the TOC now renders correctly and the Condition plugin behaves consistently across environments. This placement ensures that conditional and included content is fully evaluated before DokuWiki constructs the TOC, preventing cascading, duplication, and frozen heading states across all tested environments.

<WRAP noprint>{{page>site:site-footer-comment_feedback_block}}</WRAP>
~~DISCUSSION~~