change to myst-migrate

Author: rowanc1

.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

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

@@ -25,6 +25,7 @@ import { getSiteTemplate } from './template.js';
 import { collectExportOptions } from '../utils/collectExportOptions.js';
 import { filterPages } from '../../project/load.js';
 import { getRawFrontmatterFromFile } from '../../process/file.js';
+import { SPEC_VERSION } from '../../spec-version.js';
 
 type ManifestProject = Required<SiteManifest>['projects'][0];
 
@@ -411,9 +412,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

@@ -389,6 +389,7 @@ export async function writeFile(
   const parts = resolveFrontmatterParts(session, frontmatter);
   const frontmatterWithExports = { ...frontmatter, exports, downloads, parts };
   const mystData: MystData = {
+    version: SPEC_VERSION,
     kind,
     sha256,
     slug,
@@ -398,7 +399,6 @@ export async function writeFile(
     widgets,
     mdast,
     references,
-    version: SPEC_VERSION,
   };
   const jsonFilenameParts = [session.contentPath()];
   if (projectSlug) jsonFilenameParts.push(projectSlug);

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

@@ -1 +1 @@
-export const SPEC_VERSION = '1';
+export const SPEC_VERSION = 1;

packages/myst-cli/src/spec-version.ts

@@ -17,6 +17,7 @@ function mystDataFilename(dataUrl: string) {
 }
 
 export type MystData = {
+  version: number;
   kind?: SourceFileKind;
   sha256?: string;
   slug?: string;
@@ -30,7 +31,6 @@ export type MystData = {
   widgets?: Record<string, any>;
   mdast?: GenericParent;
   references?: References;
-  version?: string;
 };
 
 async function fetchMystData(

packages/myst-cli/src/transforms/crossReferences.ts

@@ -69,6 +69,7 @@ type ManifestProject = {
 } & Omit<ProjectFrontmatter, 'downloads' | 'exports' | 'parts'>;
 
 export type SiteManifest = Omit<SiteFrontmatter, 'parts'> & {
+  version: number;
   myst: string;
   id?: string;
   projects?: ManifestProject[];