📄 Support new-page/page-break tags in tex/typst/docx

.changeset/happy-gorillas-argue.md

@@ -0,0 +1,8 @@
+---
+'myst-to-typst': patch
+'myst-to-docx': patch
+'myst-common': patch
+'myst-to-tex': patch
+---
+
+Support new-page/page-break tags in tex/typst/docx

.changeset/young-snakes-cough.md

@@ -0,0 +1,6 @@
+---
+'myst-to-typst': patch
+'myst-to-tex': patch
+---
+
+Support no-pdf, no-typst alongside no-tex

docs/blocks.md

@@ -19,6 +19,14 @@ cell 2
 To identify a [part of a document](./document-parts.md), like an abstract, use `+++ { "part": "abstract" }`, this will allow tools like the [](./creating-pdf-documents.md) to be created with the appropriate parts of information.
 ```
 
+### Page Breaks
+
+You may use `block` metadata to insert page breaks into your PDF or docx export with `+++ { "page-break": true }`. This will have no impact on your MyST site build nor other static exports that disregard "pages" (e.g. JATS).
+
+```{tip}
+You may also use `"new-page"` instead of `"page-break"`. This distinction only matters for $\LaTeX$ where `\newpage` and `\pagebreak` will be used, respectively.
+```
+
 ## Comments
 
 You may add comments by putting the `%` character at the beginning of a line. This will prevent the line from being shown in the output document.

docs/creating-pdf-documents.md

@@ -209,7 +209,7 @@ Please consider [contributing your template](/jtex/contribute-a-template) to the
 
 ## Excluding Source
 
-If you have a block or notebook cell that you do now want to render to your LaTeX output, add the `no-tex` tag to the cell.
+If you have a block or notebook cell that you do not want to render to your $\LaTeX$ output, add the `no-tex` tag to the cell. Similarly, to exclude a cell from Typst, use `no-typst`. To exclude a cell from both formats, use `no-pdf`.
 
 (multi-article-exports)=
 

packages/myst-common/src/index.ts

@@ -12,6 +12,7 @@ export {
   copyNode,
   mergeTextNodes,
   writeTexLabelledComment,
+  getMetadataTags,
 } from './utils.js';
 export { plural } from './plural.js';
 export { selectBlockParts, extractPart } from './extractParts.js';

packages/myst-common/src/utils.ts

@@ -181,3 +181,14 @@ export function writeTexLabelledComment(title: string, commands: string[], comme
   const titleBlock = `${start}  ${title}  ${end}\n`;
   return `${titleBlock}${commands.join('\n')}\n`;
 }
+
+export function getMetadataTags(node: GenericNode) {
+  if (!node.data) return [];
+  const tags: string[] = node.data.tags ?? [];
+  Object.entries(node.data).forEach(([key, val]) => {
+    if (val === true || (typeof val === 'string' && val.toLowerCase() === 'true')) {
+      tags.push(key);
+    }
+  });
+  return tags.map((tag) => tag.toLowerCase());
+}

packages/myst-to-docx/src/schema.ts

@@ -18,8 +18,9 @@ import {
   Table,
   TableCell,
   Paragraph,
+  PageBreak,
 } from 'docx';
-import { RuleId, fileError } from 'myst-common';
+import { RuleId, fileError, getMetadataTags } from 'myst-common';
 import type {
   Parent,
   Heading,
@@ -85,6 +86,10 @@ const paragraph: Handler<ParagraphNode> = (state, node) => {
 
 const block: Handler<Block> = (state, node) => {
   if (node.visibility === 'remove') return;
+  const metadataTags = getMetadataTags(node);
+  if (metadataTags.includes('page-break') || metadataTags.includes('new-page')) {
+    state.current.push(new PageBreak());
+  }
   state.renderChildren(node as Parent);
 };
 

packages/myst-to-tex/src/index.ts

@@ -2,7 +2,7 @@ import type { Root, Parent, Code, Abbreviation } from 'myst-spec';
 import type { Plugin } from 'unified';
 import type { VFile } from 'vfile';
 import type { GenericNode, References } from 'myst-common';
-import { RuleId, fileError, toText } from 'myst-common';
+import { RuleId, fileError, toText, getMetadataTags } from 'myst-common';
 import { captionHandler, containerHandler } from './container.js';
 import { renderNodeToLatex } from './tables.js';
 import type { Handler, ITexSerializer, LatexResult, Options, StateData } from './types.js';
@@ -131,9 +131,10 @@ const handlers: Record<string, Handler> = {
     state.closeBlock(node);
   },
   block(node, state) {
+    const metadataTags = getMetadataTags(node);
     if (state.options.beamer) {
       // Metadata from block `+++ { "outline": true }` is put in data field.
-      if (node.data?.outline) {
+      if (metadataTags.includes('outline')) {
         // For beamer blocks that are outline, write the content as normal
         // This will hopefully just be section and subsection
         state.data.nextHeadingIsFrameTitle = false;
@@ -149,7 +150,13 @@ const handlers: Record<string, Handler> = {
       return;
     }
     if (node.visibility === 'remove') return;
-    if (node.data?.tags?.includes('no-tex')) return;
+    if (metadataTags.includes('no-tex')) return;
+    if (metadataTags.includes('no-pdf')) return;
+    if (metadataTags.includes('new-page')) {
+      state.write('\\newpage\n');
+    } else if (metadataTags.includes('page-break')) {
+      state.write('\\pagebreak\n');
+    }
     state.renderChildren(node, false);
   },
   blockquote(node, state) {

packages/myst-to-tex/tests/basic.yml

@@ -344,3 +344,102 @@ cases:
               value: H₂O-CO₂
     latex: |-
       H\textsubscript{2}O-CO\textsubscript{2}
+  - title: block visibility removes
+    mdast:
+      type: root
+      children:
+        - type: block
+          visibility: remove
+          children:
+            - type: text
+              value: H₂O-CO₂
+    latex: ''
+  - title: block no-tex tag removes
+    mdast:
+      type: root
+      children:
+        - type: block
+          data:
+            tags:
+              - some-tag
+              - no-tex
+          children:
+            - type: text
+              value: H₂O-CO₂
+    latex: ''
+  - title: block no-tex metadata removes
+    mdast:
+      type: root
+      children:
+        - type: block
+          data:
+            no-tex: true
+          children:
+            - type: text
+              value: H₂O-CO₂
+    latex: ''
+  - title: block no-pdf metadata removes
+    mdast:
+      type: root
+      children:
+        - type: block
+          data:
+            no-pdf: true
+          children:
+            - type: text
+              value: H₂O-CO₂
+    latex: ''
+  - title: block no-typst metadata ignored
+    mdast:
+      type: root
+      children:
+        - type: block
+          data:
+            no-typst: true
+          children:
+            - type: text
+              value: H₂O-CO₂
+    latex: |-
+      H\textsubscript{2}O-CO\textsubscript{2}
+  - title: block new-page metadata adds newpage
+    mdast:
+      type: root
+      children:
+        - type: block
+          data:
+            new-page: true
+          children:
+            - type: text
+              value: H₂O-CO₂
+    latex: |-
+      \newpage
+      H\textsubscript{2}O-CO\textsubscript{2}
+  - title: block page-break tag adds pagebreak
+    mdast:
+      type: root
+      children:
+        - type: block
+          data:
+            tags:
+              - page-break
+          children:
+            - type: text
+              value: H₂O-CO₂
+    latex: |-
+      \pagebreak
+      H\textsubscript{2}O-CO\textsubscript{2}
+  - title: block new-page takes priority
+    mdast:
+      type: root
+      children:
+        - type: block
+          data:
+            tags:
+              - page-break
+              - new-page
+          children:
+            - type: text
+              value: H₂O-CO₂
+    latex: |-
+      \newpage
+      H\textsubscript{2}O-CO\textsubscript{2}

packages/myst-to-typst/src/index.ts

@@ -2,9 +2,8 @@ import type { Root, Parent, Code } from 'myst-spec';
 import type { Plugin } from 'unified';
 import type { VFile } from 'vfile';
 import type { GenericNode } from 'myst-common';
-import { fileError, fileWarn, toText } from 'myst-common';
+import { fileError, fileWarn, toText, getMetadataTags } from 'myst-common';
 import { captionHandler, containerHandler } from './container.js';
-// import { renderNodeToLatex } from './tables.js';
 import type { Handler, ITypstSerializer, TypstResult, Options, StateData } from './types.js';
 import {
   getLatexImageWidth,
@@ -96,7 +95,13 @@ const handlers: Record<string, Handler> = {
     state.write('\n\n');
   },
   block(node, state) {
+    const metadataTags = getMetadataTags(node);
+    if (metadataTags.includes('no-typst')) return;
+    if (metadataTags.includes('no-pdf')) return;
     if (node.visibility === 'remove') return;
+    if (metadataTags.includes('page-break') || metadataTags.includes('new-page')) {
+      state.write('#pagebreak(weak: true)\n');
+    }
     state.renderChildren(node, 2);
   },
   blockquote(node, state) {

packages/myst-to-typst/tests/basic.yml

@@ -279,3 +279,87 @@ cases:
             - type: text
               value: '*escaped symbols*'
     typst: '\*escaped symbols\*'
+  - title: block hidden
+    mdast:
+      type: root
+      children:
+        - type: block
+          visibility: remove
+          children:
+            - type: paragraph
+              children:
+                - type: text
+                  value: '*escaped symbols*'
+    typst: ''
+  - title: block no-typst
+    mdast:
+      type: root
+      children:
+        - type: block
+          data:
+            tags:
+              - 'no-typst'
+          children:
+            - type: paragraph
+              children:
+                - type: text
+                  value: '*escaped symbols*'
+    typst: ''
+  - title: block no-tex
+    mdast:
+      type: root
+      children:
+        - type: block
+          data:
+            tags:
+              - 'no-tex'
+          children:
+            - type: paragraph
+              children:
+                - type: text
+                  value: '*escaped symbols*'
+    typst: '\*escaped symbols\*'
+  - title: block no-pdf
+    mdast:
+      type: root
+      children:
+        - type: block
+          data:
+            no-pdf: true
+          children:
+            - type: paragraph
+              children:
+                - type: text
+                  value: '*escaped symbols*'
+    typst: ''
+  - title: block page break
+    mdast:
+      type: root
+      children:
+        - type: block
+          data:
+            tags:
+              - page-break
+          children:
+            - type: paragraph
+              children:
+                - type: text
+                  value: '*escaped symbols*'
+    typst: |-
+      #pagebreak(weak: true)
+      \*escaped symbols\*
+  - title: block new page
+    mdast:
+      type: root
+      children:
+        - type: block
+          data:
+            new-page: true
+          children:
+            - type: paragraph
+              children:
+                - type: text
+                  value: '*escaped symbols*'
+    typst: |-
+      #pagebreak(weak: true)
+      \*escaped symbols\*