docs: document parity modes, blank-page ownership, document-start exc…

docs/configuration-en.mdx

@@ -915,7 +915,7 @@ Per-level overrides support the same properties as the general defaults — `fon
       <td><code>breakBefore</code></td>
       <td><code>HeadingBreakBeforeConfig</code></td>
       <td><code>&#123; enabled: false, parity: 'any' &#125;</code></td>
-      <td>Force a page break before every heading of this level. <code>parity: 'odd'</code> / <code>'even'</code> further constrains which side of the spread the heading opens on — a blank padding page is inserted when needed (still counted in the page numbering). <code>'always-odd'</code> / <code>'always-even'</code> additionally guarantee at least one mandatory blank separator page between the previous content and the new heading (the separator belongs to the previous chapter; any further parity padding belongs to the new one).</td>
+      <td>Force a page break before every heading of this level. <code>parity: 'odd'</code> / <code>'even'</code> further constrains which side of the spread the heading opens on — a blank padding page is inserted when needed (still counted in the page numbering). <code>'always-odd'</code> / <code>'always-even'</code> additionally guarantee at least one mandatory blank separator page between the previous content and the new heading (the separator belongs to the previous chapter; any further parity padding belongs to the new one). When the heading is the very first block of the document and the first page is still empty, parity enforcement is skipped — the heading lands on page 1 as written.</td>
     </tr>
   </tbody>
 </table>
@@ -933,7 +933,51 @@ headings: {
 
 ### Break before
 
-`breakBefore` is orthogonal to the numbering controls: turning it on forces a page break, but the numeric counter only resets when you explicitly insert a <code>:::numbering</code> directive. Blank parity pages count as real pages in the sequence and receive headers/footers according to their normal odd/even rules.
+`breakBefore` is orthogonal to the numbering controls: turning it on forces a page break, but the numeric counter only resets when you explicitly insert a `:::numbering` directive. Blank parity pages count as real pages in the sequence and receive headers/footers according to their normal odd/even rules.
+
+#### Parity values
+
+<table>
+  <thead>
+    <tr>
+      <th style={{ width: '160px' }}>Value</th>
+      <th>Behavior</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>'any'</code> (default)</td>
+      <td>No parity constraint. The heading just opens on the next page.</td>
+    </tr>
+    <tr>
+      <td><code>'odd'</code></td>
+      <td>Ensure the heading opens on an odd (right-hand) page. A single blank is inserted only when the natural next page is even.</td>
+    </tr>
+    <tr>
+      <td><code>'even'</code></td>
+      <td>Same but for an even (left-hand) page.</td>
+    </tr>
+    <tr>
+      <td><code>'always-odd'</code></td>
+      <td>Guarantee <strong>at least one mandatory blank separator page</strong> between the previous content and the new heading, then ensure odd parity. Useful when every chapter must start on a fresh spread.</td>
+    </tr>
+    <tr>
+      <td><code>'always-even'</code></td>
+      <td>Same but for an even page.</td>
+    </tr>
+  </tbody>
+</table>
+
+#### Blank-page ownership
+
+Blank pages inserted by `breakBefore` carry chapter-title headers based on *why* they were inserted:
+
+- Pages inserted to satisfy a parity constraint (`'odd'`, `'even'`, or the parity tail of `'always-*'`) belong to the **upcoming** chapter. Their `{chapterTitle}` header placeholder resolves to the new chapter's title — because the blank exists only to push the new chapter onto the correct parity.
+- The mandatory leading separator inserted by `'always-odd'` / `'always-even'` belongs to the **previous** chapter. It's a deliberate end-of-chapter breath, so the `{chapterTitle}` header still shows the old chapter's title.
+
+#### Document-start exception
+
+When the very first block of the document is a heading with `breakBefore` enabled — or the source opens with `:::pagebreak` — parity enforcement is skipped while the first page is still empty. The heading lands on page 1 as written, regardless of the configured parity, so a document that begins with a `# Chapter 1` configured `parity: 'odd'` doesn't inherit a spurious leading blank. Once any content has been placed, parity enforcement behaves normally.
 
 
 ## Unordered Lists

docs/configuration-es.mdx

@@ -915,7 +915,7 @@ Las configuraciones por nivel soportan las mismas propiedades que los valores ge
       <td><code>breakBefore</code></td>
       <td><code>HeadingBreakBeforeConfig</code></td>
       <td><code>&#123; enabled: false, parity: 'any' &#125;</code></td>
-      <td>Fuerza un salto de página antes de cada encabezado de este nivel. <code>parity: 'odd'</code> / <code>'even'</code> restringe además en qué lado del pliego se abrirá — se inserta una página en blanco de relleno cuando sea necesario (sigue contando para la numeración). <code>'always-odd'</code> / <code>'always-even'</code> garantizan además al menos una página separadora en blanco obligatoria entre el contenido anterior y el nuevo encabezado (la separadora pertenece al capítulo anterior; cualquier relleno de paridad adicional pertenece al nuevo).</td>
+      <td>Fuerza un salto de página antes de cada encabezado de este nivel. <code>parity: 'odd'</code> / <code>'even'</code> restringe además en qué lado del pliego se abrirá — se inserta una página en blanco de relleno cuando sea necesario (sigue contando para la numeración). <code>'always-odd'</code> / <code>'always-even'</code> garantizan además al menos una página separadora en blanco obligatoria entre el contenido anterior y el nuevo encabezado (la separadora pertenece al capítulo anterior; cualquier relleno de paridad adicional pertenece al nuevo). Cuando el encabezado es el primer bloque del documento y la primera página sigue vacía, la imposición de paridad se omite — el encabezado aterriza en la página 1 tal cual.</td>
     </tr>
   </tbody>
 </table>
@@ -933,7 +933,51 @@ headings: {
 
 ### Saltar antes
 
-`breakBefore` es ortogonal a los controles de numeración: activarlo fuerza un salto de página, pero el contador numérico solo se reinicia cuando insertas explícitamente una directiva <code>:::numbering</code>. Las páginas de relleno por paridad cuentan como páginas reales en la secuencia y reciben encabezados/pies según sus reglas normales de impar/par.
+`breakBefore` es ortogonal a los controles de numeración: activarlo fuerza un salto de página, pero el contador numérico solo se reinicia cuando insertas explícitamente una directiva `:::numbering`. Las páginas de relleno por paridad cuentan como páginas reales en la secuencia y reciben encabezados/pies según sus reglas normales de impar/par.
+
+#### Valores de paridad
+
+<table>
+  <thead>
+    <tr>
+      <th style={{ width: '160px' }}>Valor</th>
+      <th>Comportamiento</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>'any'</code> (por defecto)</td>
+      <td>Sin restricción de paridad. El encabezado simplemente se abre en la siguiente página.</td>
+    </tr>
+    <tr>
+      <td><code>'odd'</code></td>
+      <td>Garantiza que el encabezado se abra en una página impar (lado derecho). Solo se inserta una página en blanco si la siguiente página natural sería par.</td>
+    </tr>
+    <tr>
+      <td><code>'even'</code></td>
+      <td>Igual pero para una página par (lado izquierdo).</td>
+    </tr>
+    <tr>
+      <td><code>'always-odd'</code></td>
+      <td>Garantiza <strong>al menos una página separadora en blanco obligatoria</strong> entre el contenido anterior y el nuevo encabezado, y después fuerza la paridad impar. Útil cuando cada capítulo debe empezar un pliego nuevo.</td>
+    </tr>
+    <tr>
+      <td><code>'always-even'</code></td>
+      <td>Igual pero para una página par.</td>
+    </tr>
+  </tbody>
+</table>
+
+#### Pertenencia de las páginas en blanco
+
+Las páginas en blanco que inserta `breakBefore` reciben el encabezado `{chapterTitle}` en función del motivo de su inserción:
+
+- Las páginas insertadas para satisfacer una restricción de paridad (`'odd'`, `'even'`, o la cola de paridad de `'always-*'`) pertenecen al capítulo **entrante**. Su marcador `{chapterTitle}` resuelve al título del nuevo capítulo — porque la página en blanco solo existe para empujar al nuevo capítulo hasta la paridad correcta.
+- La página separadora obligatoria que inserta `'always-odd'` / `'always-even'` pertenece al capítulo **anterior**. Es una pausa de cierre de capítulo deliberada, así que `{chapterTitle}` sigue mostrando el título del capítulo saliente.
+
+#### Excepción al inicio del documento
+
+Cuando el primer bloque del documento es un encabezado con `breakBefore` activado — o la fuente empieza con `:::pagebreak` —, la imposición de paridad se omite mientras la primera página siga vacía. El encabezado aterriza en la página 1 tal cual, independientemente de la paridad configurada, de modo que un documento que comienza con `# Capítulo 1` con `parity: 'odd'` no arrastra una página en blanco inicial innecesaria. Una vez que se ha colocado cualquier contenido, la imposición de paridad funciona de forma habitual.
 
 
 ## Listas no ordenadas

docs/document-format-en.mdx

@@ -153,6 +153,24 @@ The old chapter ends here.
 # A new chapter
 ```
 
+#### Parity attribute
+
+The `parity` attribute accepts the same five values as `headings.levels[*].breakBefore.parity`:
+
+- `'odd'` / `'even'` — the new page opens on the requested side of the spread; a single blank is inserted only when the natural next page is on the wrong side.
+- `'always-odd'` / `'always-even'` — guarantee at least one mandatory blank separator page between the previous content and the new page, then enforce parity. The separator blank belongs to the **previous** chapter; any further parity padding belongs to whatever follows.
+
+#### Blank-page ownership
+
+The two kinds of blank pages `:::pagebreak` (and `breakBefore`) can introduce are distinguished in the `VDTPage` model:
+
+- `blankForParity: true` — inserted to satisfy a parity constraint. In `{chapterTitle}` headers this page carries the **upcoming** chapter's title, because the blank exists only to push that chapter onto the right parity.
+- `blankForForce: true` — the mandatory leading separator of an `'always-*'` mode. It belongs to the **previous** chapter — a deliberate end-of-chapter breath, not parity padding for the next chapter.
+
+#### Document-start exception
+
+When `:::pagebreak` is the very first construct in a document (or a heading with `breakBefore` would pull one in), parity enforcement is skipped while the first page is still empty. The next block lands on page 1 as written, regardless of the requested parity — no spurious leading blank.
+
 ### `:::numbering`
 
 `:::numbering` is how you restart the page counter mid-document. The canonical book example:

docs/document-format-es.mdx

@@ -153,6 +153,24 @@ El capítulo anterior termina aquí.
 # Un nuevo capítulo
 ```
 
+#### Atributo `parity`
+
+El atributo `parity` acepta los mismos cinco valores que `headings.levels[*].breakBefore.parity`:
+
+- `'odd'` / `'even'` — la nueva página abre en el lado solicitado del pliego; solo se inserta una página en blanco cuando la siguiente página natural cae en el lado equivocado.
+- `'always-odd'` / `'always-even'` — garantizan al menos una página separadora en blanco obligatoria entre el contenido anterior y la nueva página, y después fuerzan la paridad. La separadora pertenece al capítulo **anterior**; cualquier relleno de paridad adicional pertenece a lo que viene después.
+
+#### Pertenencia de las páginas en blanco
+
+Los dos tipos de páginas en blanco que `:::pagebreak` (y `breakBefore`) pueden introducir se distinguen en el modelo `VDTPage`:
+
+- `blankForParity: true` — insertada para satisfacer una restricción de paridad. En el marcador `{chapterTitle}` esta página lleva el título del capítulo **entrante**, porque la página en blanco solo existe para empujar ese capítulo a la paridad correcta.
+- `blankForForce: true` — la página separadora obligatoria que añade un modo `'always-*'`. Pertenece al capítulo **anterior** — es una pausa deliberada de cierre de capítulo, no un relleno de paridad para el capítulo siguiente.
+
+#### Excepción al inicio del documento
+
+Cuando `:::pagebreak` es la primera construcción del documento (o un encabezado con `breakBefore` lo dispara), la imposición de paridad se omite mientras la primera página siga vacía. El siguiente bloque aterriza en la página 1 tal cual, independientemente de la paridad solicitada — no se inserta una página en blanco inicial superflua.
+
 ### `:::numbering`
 
 `:::numbering` es la forma de reiniciar el contador de páginas a mitad del documento. Ejemplo canónico de libro: