change to myst-migrate

jupyter-book · Feb 8, 2025 · 21e9b9c · 21e9b9c
1 parent 7b048a3
commit 21e9b9c
Show file tree

Hide file tree

Showing 34 changed files with 262 additions and 268 deletions.
diff --git a/.changeset/eight-tools-live.md b/.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
diff --git a/.changeset/eleven-keys-explain.md b/.changeset/eleven-keys-explain.md
@@ -0,0 +1,5 @@
+---
+"myst-config": patch
+---
+
+Add version to config file
diff --git a/.changeset/red-suits-hug.md b/.changeset/red-suits-hug.md
@@ -0,0 +1,5 @@
+---
+"myst-cli": patch
+---
+
+Add version to site content outputs
diff --git a/docs/myst.yml b/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

diff --git a/docs/versions.md b/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.
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/myst-cli/src/build/site/manifest.ts b/packages/myst-cli/src/build/site/manifest.ts
@@ -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,

diff --git a/packages/myst-cli/src/process/site.ts b/packages/myst-cli/src/process/site.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);

diff --git a/packages/myst-cli/src/spec-version.ts b/packages/myst-cli/src/spec-version.ts
@@ -1 +1 @@
-export const SPEC_VERSION = '1';
+export const SPEC_VERSION = 1;
diff --git a/packages/myst-cli/src/transforms/crossReferences.ts b/packages/myst-cli/src/transforms/crossReferences.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(

diff --git a/packages/myst-compat/README.md b/packages/myst-compat/README.md
diff --git a/packages/myst-compat/src/downgrade/index.ts b/packages/myst-compat/src/downgrade/index.ts
diff --git a/packages/myst-compat/src/downgrade/version_2_1.ts b/packages/myst-compat/src/downgrade/version_2_1.ts
diff --git a/packages/myst-compat/src/index.ts b/packages/myst-compat/src/index.ts
diff --git a/packages/myst-compat/src/types/index.ts b/packages/myst-compat/src/types/index.ts
diff --git a/packages/myst-compat/src/types/v1.ts b/packages/myst-compat/src/types/v1.ts
diff --git a/packages/myst-compat/src/types/v2.ts b/packages/myst-compat/src/types/v2.ts
diff --git a/packages/myst-compat/src/upgrade/index.ts b/packages/myst-compat/src/upgrade/index.ts
diff --git a/packages/myst-compat/src/upgrade/version_1_2.ts b/packages/myst-compat/src/upgrade/version_1_2.ts
diff --git a/packages/myst-config/src/site/types.ts b/packages/myst-config/src/site/types.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[];

diff --git a/packages/myst-compat/.eslintrc.cjs → packages/myst-migrate/.eslintrc.cjs b/packages/myst-compat/.eslintrc.cjs → packages/myst-migrate/.eslintrc.cjs
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		export const SPEC_VERSION = '1';
		export const SPEC_VERSION = 1;