Add options and parts to frontmatter (#736)

* 🍰 Add parts to page frontmatter
* 📀 Add options to site/project/page frontmatter
* 🔧 Consume frontmatter parts alongside tagged parts
* 🔧 Consume frontmatter options for template/site options
* 🔧 Write myst-cli version in site config
* 🔧 Simplify site template options handling
* 🪄 Transform frontmatter parts into blocks in the mdast
* 🔧 Correctly mark frontmatter part blocks as visibility: remove
* 🦾 Add part --> parts alias
* 🥇 Improve `myst init` to new options
* 👁 Ensure that extracted blocks are visible (#741)
* 📖 More docs updates for options/logo
* 🧹 Remove SiteTemplateOptions type
* 👩‍🎨 Check for hide_authors under options
* 🤫 Quiet warnings about extra options
* 🧠 Expand known parts and alias
* 🌆 Image --> thumbnail alias
* 📝 Allow parts to be a list, consume these in templates
* 📝 Support markdown lists for parts as list

---------

Co-authored-by: Rowan Cockett <[email protected]>

.changeset/fluffy-clocks-complain.md

@@ -0,0 +1,5 @@
+---
+'myst-cli': patch
+---
+
+Do not duplicate site template options in redux store

.changeset/gentle-moons-film.md

@@ -0,0 +1,6 @@
+---
+'myst-config': patch
+'myst-cli': patch
+---
+
+Write myst-cli version in site config

.changeset/late-doors-dress.md

@@ -0,0 +1,8 @@
+---
+'myst-frontmatter': patch
+'myst-to-jats': patch
+'myst-common': patch
+'myst-cli': patch
+---
+
+Consume frontmatter parts alongside tagged parts

.changeset/long-penguins-remember.md

@@ -0,0 +1,8 @@
+---
+'myst-frontmatter': patch
+'myst-to-jats': patch
+'myst-common': patch
+'myst-cli': patch
+---
+
+Transform frontmatter parts into blocks in the mdast

.changeset/long-zoos-shout.md

@@ -0,0 +1,5 @@
+---
+'myst-cli': patch
+---
+
+Resolve site logo path with other template options of type file

.changeset/many-ravens-develop.md

@@ -0,0 +1,7 @@
+---
+'myst-templates': patch
+'myst-cli': patch
+'jtex': patch
+---
+
+Template parts may now specify as_list

.changeset/pretty-zebras-warn.md

@@ -0,0 +1,7 @@
+---
+'myst-frontmatter': patch
+'myst-config': patch
+'myst-cli': patch
+---
+
+Consume frontmatter options for template/site options

.changeset/sixty-sloths-impress.md

@@ -0,0 +1,5 @@
+---
+'myst-frontmatter': patch
+---
+
+Add options to site/project/page frontmatter

.changeset/small-pens-arrive.md

@@ -0,0 +1,5 @@
+---
+'myst-common': patch
+---
+
+Ensure the block is visible by default in extractParts

.changeset/stupid-knives-eat.md

@@ -0,0 +1,5 @@
+---
+'myst-frontmatter': patch
+---
+
+Add parts to page frontmatter

.changeset/swift-eagles-call.md

@@ -0,0 +1,6 @@
+---
+'myst-frontmatter': patch
+'myst-cli': patch
+---
+
+Frontmatter parts each coerce to list

docs/frontmatter.md

@@ -133,6 +133,12 @@ The following table lists the available frontmatter fields, a brief description
 * - `abbreviations`
   - a dictionary of abbreviations in the project (see [](#abbreviations))
   - page can override project
+* - `parts`
+  - a dictionary of arbitrary content parts, not part of the main article, for example `abstract`, `data_availability`
+  - page only
+* - `options`
+  - a dictionary of arbitrary options validated and consumed by templates, for example, during site or PDF build
+  - page can override project
 ```
 
 +++

docs/quickstart-myst-websites.md

@@ -183,7 +183,8 @@ project:
 site:
   template: book-theme
   # title:
-  # logo:
+  # options:
+  #   logo: my_logo.png
   nav: []
   actions:
     - title: Learn More

packages/jtex/src/types.ts

@@ -9,6 +9,6 @@ export type TexRenderer = {
   CONTENT: string;
   doc: RendererDoc;
   options: Record<string, any>;
-  parts: Record<string, string>;
+  parts: Record<string, string | string[]>;
   IMPORTS?: string;
 };

packages/myst-cli/package.json

@@ -111,6 +111,7 @@
     "@types/mime-types": "^2.1.1",
     "@types/which": "^3.0.0",
     "@types/ws": "^8.5.5",
-    "concurrently": "^8.2.0"
+    "concurrently": "^8.2.0",
+    "unist-util-visit": "^5.0.0"
   }
 }

packages/myst-cli/src/build/docx/single.ts

@@ -110,7 +110,7 @@ export async function runWordExport(
   const { options, doc } = mystTemplate.prepare({
     frontmatter: data.frontmatter,
     parts: [],
-    options: exportOptions,
+    options: { ...data.frontmatter.options, ...exportOptions },
     sourceFile: file,
   });
   const renderer = exportOptions.renderer ?? defaultWordRenderer;

packages/myst-cli/src/build/init.ts

@@ -25,7 +25,8 @@ function createProjectConfig({ github }: { github?: string } = {}) {
 const SITE_CONFIG = `site:
   template: book-theme
   # title:
-  # logo:
+  # options:
+  #   logo: site_logo.png
   nav: []
   actions:
     - title: Learn More

packages/myst-cli/src/build/jats/single.ts

@@ -73,6 +73,7 @@ export async function runJatsExport(
         title: 'Data Availability',
       },
     ],
+    // if we want to add templating here, we have access to { ...processedArticle.frontmatter.options, ...exportOptions }
   });
   logMessagesFromVFile(session, jats);
   session.log.info(toc(`📑 Exported JATS in %s, copying to ${output}`));

packages/myst-cli/src/build/site/manifest.ts

@@ -2,11 +2,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { hashAndCopyStaticFile } from 'myst-cli-utils';
 import { RuleId, TemplateOptionType } from 'myst-common';
-import type { SiteAction, SiteManifest, SiteTemplateOptions } from 'myst-config';
+import type { SiteAction, SiteManifest } from 'myst-config';
 import { PROJECT_FRONTMATTER_KEYS, SITE_FRONTMATTER_KEYS } from 'myst-frontmatter';
 import type MystTemplate from 'myst-templates';
 import { filterKeys } from 'simple-validators';
-import { addWarningForFile } from '../../index.js';
+import { addWarningForFile, resolveToAbsolute, version } from '../../index.js';
 import { resolvePageExports } from '../../process/site.js';
 import type { ISession } from '../../session/types.js';
 import type { RootState } from '../../store/index.js';
@@ -113,14 +113,18 @@ export async function localToManifestProject(
 async function resolveTemplateFileOptions(
   session: ISession,
   mystTemplate: MystTemplate,
-  options: SiteTemplateOptions,
+  options: Record<string, any>,
 ) {
   const resolvedOptions = { ...options };
   mystTemplate.getValidatedTemplateYml().options?.forEach((option) => {
     if (option.type === TemplateOptionType.file && options[option.id]) {
+      const configPath = selectors.selectCurrentSitePath(session.store.getState());
+      const absPath = configPath
+        ? resolveToAbsolute(session, configPath, options[option.id])
+        : options[option.id];
       const fileHash = hashAndCopyStaticFile(
         session,
-        options[option.id],
+        absPath,
         session.publicPath(),
         (m: string) => {
           addWarningForFile(session, options[option.id], m, 'error', {
@@ -172,21 +176,23 @@ export async function getSiteManifest(
   const { nav } = siteConfig;
   const actions = siteConfig.actions?.map((action) => resolveSiteManifestAction(session, action));
   const siteFrontmatter = filterKeys(siteConfig as Record<string, any>, SITE_FRONTMATTER_KEYS);
-  const siteTemplateOptions = selectors.selectCurrentSiteTemplateOptions(state) || {};
   const mystTemplate = await getMystTemplate(session, opts);
   const siteConfigFile = selectors.selectCurrentSiteFile(state);
-  const validatedOptions = mystTemplate.validateOptions(siteTemplateOptions, siteConfigFile);
+  const validatedOptions = mystTemplate.validateOptions(
+    siteFrontmatter.options ?? {},
+    siteConfigFile,
+  );
   const validatedFrontmatter = mystTemplate.validateDoc(
     siteFrontmatter,
     validatedOptions,
     undefined,
     siteConfigFile,
   );
   const resolvedOptions = await resolveTemplateFileOptions(session, mystTemplate, validatedOptions);
+  validatedFrontmatter.options = resolvedOptions;
   const manifest: SiteManifest = {
     ...validatedFrontmatter,
-    ...resolvedOptions,
-    myst: 'v1',
+    myst: version,
     nav: nav || [],
     actions: actions || [],
     projects: siteProjects,