⬆️ Add simple upgrade/downgrade package for MyST AST (#1802)

Co-authored-by: Rowan Cockett <rowanc1@gmail.com>

Author: agoose77

.changeset/eight-tools-live.md

@@ -0,0 +1,9 @@
+---
+"myst-transforms": patch
+"myst-spec-ext": patch
+"myst-to-docx": patch
+"myst-config": patch
+"myst-cli": patch
+---
+
+Change footnotes to use enumerator over number

.changeset/eleven-keys-explain.md

@@ -0,0 +1,5 @@
+---
+"myst-config": patch
+---
+
+Add version to config file

.changeset/red-suits-hug.md

@@ -0,0 +1,5 @@
+---
+"myst-cli": patch
+---
+
+Add version to site content outputs

.changeset/sour-spiders-push.md

@@ -0,0 +1,5 @@
+---
+'myst-migrate': patch
+---
+
+Add myst-migrate package

docs/myst.yml

@@ -153,6 +153,7 @@ project:
         - file: document-parts.md
         - file: settings.md
         - file: glossary.md
+        - file: versions.md
     - title: Contribute
       children:
         - file: contributing.md

docs/versions.md

@@ -0,0 +1,18 @@
+---
+title: MyST Content Versions
+---
+
+The following page describes changes to the MyST content that is served from the `.json` endpoint of a MyST Site. The `myst-compat` package can be used to translate between versions by upgrading and downgrading between versions.
+
+The version is a string integer (i.e. `'1'` or `'2'`) and is incremented with every change to the content of a MyST page, which includes metadata as well as the MyST AST.
+
+# MyST Versions
+
+## Version 1 - 2025-02-07 - Footnote Numbering
+
+The footnotes have dropped backwards compatibility with `number`, instead using `enumerator` on both the `FootnoteReference` and `FootnoteDefinition` nodes.
+Previous versions of the AST had both of these defined. The `enumerator` property is used in all other numberings of figures, sections, equations, etc.
+
+## Version 0 - Pre 2025-02-01
+
+This is the first version of MyST AST considered to be versioned, subsequent releases will have changes for migrating the content between versions.

package-lock.json

@@ -15,7 +15,6 @@ import type { ExportWithOutput, ExportFnOptions } from './types.js';
 import { cleanOutput } from './utils/cleanOutput.js';
 import { getFileContent } from './utils/getFileContent.js';
 import { resolveFrontmatterParts } from '../utils/resolveFrontmatterParts.js';
-import { parseMyst } from '../process/myst.js';
 
 function exportOptionsToCFF(exportOptions: ExportWithOutput): CFF {
   // Handle overlap of key "format" between CFF and export

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

@@ -26,6 +26,7 @@ import { collectExportOptions } from '../utils/collectExportOptions.js';
 import { filterPages } from '../../project/load.js';
 import { getRawFrontmatterFromFile } from '../../process/file.js';
 import { castSession } from '../../session/cache.js';
+import { SPEC_VERSION } from '../../spec-version.js';
 
 type ManifestProject = Required<SiteManifest>['projects'][0];
 
@@ -417,9 +418,10 @@ export async function getSiteManifest(
   validatedFrontmatter.options = resolvedOptions;
   const parts = resolveFrontmatterParts(session, validatedFrontmatter);
   const manifest: SiteManifest = {
+    version: SPEC_VERSION,
+    myst: version,
     ...validatedFrontmatter,
     parts,
-    myst: version,
     nav: nav || [],
     actions: actions || [],
     projects: siteProjects,

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

@@ -10,4 +10,5 @@ export * from './session/index.js';
 export * from './store/index.js';
 export * from './transforms/index.js';
 export * from './utils/index.js';
+export * from './spec-version.js';
 export { default as version } from './version.js';