✨ Add extends field to myst.yml for composing multiple yamls (#1215)

* 🔧 Refactor config loading to separate validation from saving
* 🏄‍♀️  Add extend key to top-level config
* ⛽️ Load and fill frontmatter from extend config key
* 🔄 Support circular deps and live reloading for extending config
* 🧪 Add page frontmatter to extend-config test
* 📚 Move composing-myst-yml from note to section in docs

.changeset/green-brooms-applaud.md

@@ -0,0 +1,5 @@
+---
+'myst-cli': patch
+---
+
+Support circular deps and live reloading for extending config

.changeset/large-peas-melt.md

@@ -0,0 +1,6 @@
+---
+'myst-frontmatter': patch
+'myst-cli': patch
+---
+
+Load and fill frontmatter from extend config key

.changeset/many-worms-know.md

@@ -0,0 +1,6 @@
+---
+'myst-config': patch
+'myst-cli': patch
+---
+
+Add extend key to top-level config

.changeset/stupid-experts-pull.md

@@ -0,0 +1,5 @@
+---
+'myst-cli': patch
+---
+
+Refactor config loading to separate validation from saving

docs/frontmatter.md

@@ -54,6 +54,24 @@ project:
   open_access: true
 ```
 
+(composing-myst-yml)=
+#### Composing multiple `.yml` files
+
+You may separate your frontmatter into multiple, composable files. To reference other files from your main `myst.yml` file, use the `extends` key with relative path(s) to the other configuration files:
+
+```yaml
+version: 1
+site: ...
+project: ...
+extends:
+  - ../macros.yml
+  - ../funding.yml
+```
+
+Each of these files listed under `extends` must contain valid `myst.yml` structure with `version: 1` and `site` or `project` keys. They may also have additional files listed under `extends`.
+
+Composing files together this way allows you to have a single source of truth for project frontmatter that may be reused across multiple projects, for example math macros or funding information.
+
 +++
 
 ## Available frontmatter fields

docs/quickstart-myst-websites.md

@@ -246,7 +246,7 @@ site:
   ...
 ```
 
-Doing this will keep the `_build` directory at the root level, but everything else outside of the `content` folder will be ignored. If you have a project in the same configuration file it can be accessed with `path: .`. Projects are "mounted" at the `slug:` (i.e. `/my-content/`) above.
+Doing this will keep the `_build` directory at the root level, but everything else outside of the `content` folder will be ignored. If you have a project in the same configuration file it can be accessed with `path: .`. Projects are "mounted" at the `slug:` (e.g. `/my-content/` above).
 :::
 
 ## Additional options

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

@@ -16,8 +16,10 @@ function watchConfigAndPublic(
   opts: ProcessSiteOptions,
 ) {
   const watchFiles = ['public'];
-  const siteConfigFile = selectors.selectCurrentSiteFile(session.store.getState());
+  const state = session.store.getState();
+  const siteConfigFile = selectors.selectCurrentSiteFile(state);
   if (siteConfigFile) watchFiles.push(siteConfigFile);
+  watchFiles.push(...selectors.selectConfigExtensions(state));
   return chokidar
     .watch(watchFiles, {
       ignoreInitial: true,
@@ -37,6 +39,7 @@ function triggerProjectReload(
   const projectConfigFile = projectPath
     ? selectors.selectLocalConfigFile(state, projectPath)
     : selectors.selectCurrentProjectFile(state);
+  if (selectors.selectConfigExtensions(state).includes(file)) return true;
   if (file === projectConfigFile || basename(file) === '_toc.yml') return true;
   // Reload project if file is added or remvoed
   if (['add', 'unlink'].includes(eventType)) return true;
@@ -64,8 +67,11 @@ async function processorFn(
     !KNOWN_FAST_BUILDS.has(extname(file)) ||
     ['add', 'unlink'].includes(eventType)
   ) {
-    let reloadProject = false;
-    if (file && triggerProjectReload(session, file, eventType, siteProject?.path)) {
+    let reloadProject = opts?.reloadProject ?? false;
+    if (
+      reloadProject ||
+      (file && triggerProjectReload(session, file, eventType, siteProject?.path))
+    ) {
       session.log.info('💥 Triggered full project load and site rebuild');
       reloadProject = true;
     } else {