From 6c0b519cbafd5a6c66534db9d68135c7743abcaa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ignacio=20Ferro=20Pic=C3=B3n?= Date: Thu, 23 Apr 2026 10:42:07 +0200 Subject: [PATCH] docs: document parity modes, blank-page ownership, document-start exception MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Expands the Break-before section in configuration-{en,es}.mdx with a parity-values table, a blank-page ownership explainer, and the document-start exception. Mirrors the same content in the pagebreak section of document-format-{en,es}.mdx so the directive docs match the per-heading config docs word for word. These aren't new features — just bringing the published reference in line with the current pipeline behavior. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/configuration-en.mdx | 48 +++++++++++++++++++++++++++++++++++-- docs/configuration-es.mdx | 48 +++++++++++++++++++++++++++++++++++-- docs/document-format-en.mdx | 18 ++++++++++++++ docs/document-format-es.mdx | 18 ++++++++++++++ 4 files changed, 128 insertions(+), 4 deletions(-) diff --git a/docs/configuration-en.mdx b/docs/configuration-en.mdx index 453379c..c092a14 100644 --- a/docs/configuration-en.mdx +++ b/docs/configuration-en.mdx @@ -915,7 +915,7 @@ Per-level overrides support the same properties as the general defaults — `fon breakBefore HeadingBreakBeforeConfig { enabled: false, parity: 'any' } - Force a page break before every heading of this level. parity: 'odd' / 'even' 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). 'always-odd' / 'always-even' 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). + Force a page break before every heading of this level. parity: 'odd' / 'even' 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). 'always-odd' / 'always-even' 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. @@ -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 :::numbering 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueBehavior
'any' (default)No parity constraint. The heading just opens on the next page.
'odd'Ensure the heading opens on an odd (right-hand) page. A single blank is inserted only when the natural next page is even.
'even'Same but for an even (left-hand) page.
'always-odd'Guarantee at least one mandatory blank separator page between the previous content and the new heading, then ensure odd parity. Useful when every chapter must start on a fresh spread.
'always-even'Same but for an even page.
+ +#### 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 diff --git a/docs/configuration-es.mdx b/docs/configuration-es.mdx index c83a160..33e79e6 100644 --- a/docs/configuration-es.mdx +++ b/docs/configuration-es.mdx @@ -915,7 +915,7 @@ Las configuraciones por nivel soportan las mismas propiedades que los valores ge breakBefore HeadingBreakBeforeConfig { enabled: false, parity: 'any' } - Fuerza un salto de página antes de cada encabezado de este nivel. parity: 'odd' / 'even' 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). 'always-odd' / 'always-even' 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). + Fuerza un salto de página antes de cada encabezado de este nivel. parity: 'odd' / 'even' 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). 'always-odd' / 'always-even' 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. @@ -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 :::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. +`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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValorComportamiento
'any' (por defecto)Sin restricción de paridad. El encabezado simplemente se abre en la siguiente página.
'odd'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.
'even'Igual pero para una página par (lado izquierdo).
'always-odd'Garantiza al menos una página separadora en blanco obligatoria 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.
'always-even'Igual pero para una página par.
+ +#### 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 diff --git a/docs/document-format-en.mdx b/docs/document-format-en.mdx index d330986..c95d633 100644 --- a/docs/document-format-en.mdx +++ b/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: diff --git a/docs/document-format-es.mdx b/docs/document-format-es.mdx index adecfb2..71c497a 100644 --- a/docs/document-format-es.mdx +++ b/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: