🚫 Add page frontmatter option to disable execution (#1842)

.changeset/dirty-ducks-tie.md

@@ -0,0 +1,6 @@
+---
+"myst-frontmatter": patch
+"myst-cli": patch
+---
+
+Add support for skipping execution of individual notebooks

docs/execute-notebooks.md

@@ -65,6 +65,24 @@ name = input("What is your name?")
 
 Additional [cell tags](#tbl:notebook-cell-tags) to hide, remove, or raise exceptions are also possible.
 
+## Skip entire notebooks
+
+You may wish to disable execution for certain notebooks. This can be done by setting the top-level `skip_execution` frontmatter option to `true`, e.g.
+
+````markdown
+---
+kernelspec:
+  name: python3
+  display_name: Python 3
+
+skip_execution: true
+---
+
+```{code-cell}
+print("This will never be executed!")
+```
+````
+
 ## Cache execution outputs
 
 When MyST executes your notebook, it will store the outputs in a cache in a folder called `execute/` in your MyST build folder.

docs/frontmatter.md

@@ -229,6 +229,9 @@ The following table lists the available frontmatter fields, a brief description
 * - `kernelspec`
   - configuration for the kernel (see [](#kernel-specification))
   - page only
+* - `skip_execution`
+  - opt-out of execution for a particular document (see [](./execute-notebooks))
+  - page only
 ```
 
 +++
@@ -850,4 +853,4 @@ These fields provide a more complete superset of publication metadata than the [
 
 > Old-timey bibliographic info for this work. This is mostly useful only in citation/reference contexts. These are all strings because sometimes you'll get fun values like "Spring" and "Inside cover."
 
-If MyST frontmatter includes an OpenAlex `biblio` object, it will be coerced to valid publication metadata.
+If MyST frontmatter includes an OpenAlex `biblio` object, it will be coerced to valid publication metadata.

packages/myst-cli/src/process/mdast.ts

@@ -219,7 +219,7 @@ export async function transformMdast(
   // Combine file-specific citation renderers with project renderers from bib files
   const fileCitationRenderer = combineCitationRenderers(cache, ...rendererFiles);
 
-  if (execute) {
+  if (execute && !frontmatter.skip_execution) {
     const cachePath = path.join(session.buildPath(), 'execute');
     await kernelExecutionTransform(mdast, vfile, {
       basePath: session.sourcePath(),

packages/myst-frontmatter/src/page/types.ts

@@ -13,6 +13,7 @@ export const PAGE_FRONTMATTER_KEYS = [
   'site',
   'enumerator',
   'content_includes_title',
+  'skip_execution',
 ];
 
 export type PageFrontmatter = ProjectAndPageFrontmatter & {
@@ -21,6 +22,8 @@ export type PageFrontmatter = ProjectAndPageFrontmatter & {
   jupytext?: Jupytext;
   tags?: string[];
   enumerator?: string;
+  // Disable execution for this page
+  skip_execution?: boolean;
   /** Flag if frontmatter title is duplicated in content
    *
    * Set during initial file/frontmatter load

packages/myst-frontmatter/src/page/validators.ts

@@ -51,6 +51,12 @@ export function validatePageFrontmatterKeys(value: Record<string, any>, opts: Va
   if (defined(value.jupytext)) {
     output.jupytext = validateJupytext(value.jupytext, incrementOptions('jupytext', opts));
   }
+  if (defined(value.skip_execution)) {
+    output.skip_execution = validateBoolean(
+      value.skip_execution,
+      incrementOptions('skip_execution', opts),
+    );
+  }
   if (defined(value.enumerator)) {
     output.enumerator = validateString(value.enumerator, incrementOptions('enumerator', opts));
   }