🔧 Add edit url to file frontmatter

jupyter-book · Jan 23, 2025 · 8c3dcca · 8c3dcca
1 parent d9d7386
commit 8c3dcca
Show file tree

Hide file tree

Showing 6 changed files with 48 additions and 0 deletions.
diff --git a/.changeset/quiet-toys-dream.md b/.changeset/quiet-toys-dream.md
@@ -0,0 +1,6 @@
+---
+'myst-frontmatter': patch
+'myst-cli': patch
+---
+
+Add edit url to file frontmatter
diff --git a/docs/frontmatter.md b/docs/frontmatter.md
@@ -175,6 +175,9 @@ The following table lists the available frontmatter fields, a brief description
 * - `github`
   - a valid GitHub URL or `owner/reponame`
   - page can override project
+* - `edit`
+  - URL to edit the page source. If this value is unset but `github` is specified, MyST will attempt to compute the specific github URL for the page. You may disable this behavior by explicitly setting `edit` to `null`.
+  - page can override project
 * - `binder`
   - any valid URL
   - page can override project

diff --git a/packages/myst-cli/src/process/mdast.ts b/packages/myst-cli/src/process/mdast.ts
@@ -77,6 +77,7 @@ import { parseMyst } from './myst.js';
 import { kernelExecutionTransform, LocalDiskCache } from 'myst-execute';
 import type { IOutput } from '@jupyterlab/nbformat';
 import { rawDirectiveTransform } from '../transforms/raw.js';
+import { addEditUrl } from '../utils/addEditUrl.js';
 
 const LINKS_SELECTOR = 'link,card,linkBlock';
 
@@ -167,6 +168,7 @@ export async function transformMdast(
     },
     projectPath,
   );
+  await addEditUrl(session, frontmatter, file);
   const references: References = {
     cite: { order: [], data: {} },
   };

diff --git a/packages/myst-cli/src/utils/addEditUrl.ts b/packages/myst-cli/src/utils/addEditUrl.ts
@@ -0,0 +1,30 @@
+import which from 'which';
+import type { PageFrontmatter } from 'myst-frontmatter';
+import { makeExecutable, silentLogger } from 'myst-cli-utils';
+import type { ISession } from '../session/types.js';
+
+function gitCommandAvailable(): boolean {
+  return !!which.sync('git', { nothrow: true });
+}
+
+export async function addEditUrl(session: ISession, frontmatter: PageFrontmatter, file: string) {
+  if (frontmatter.edit || frontmatter.edit === null) return;
+  if (!gitCommandAvailable()) return;
+  try {
+    const gitLog = silentLogger();
+    const getGitOrigin = makeExecutable('git config --get remote.origin.url', gitLog);
+    const gitOrigin =
+      frontmatter.github ??
+      (await getGitOrigin()).trim().replace('git@github.com:', 'https://github.com/');
+    const getGitBranch = makeExecutable('git rev-parse --abbrev-ref HEAD', gitLog);
+    const gitBranch = (await getGitBranch()).trim();
+    const getGitRoot = makeExecutable('git rev-parse --show-toplevel', gitLog);
+    const gitRoot = (await getGitRoot()).trim();
+    if (gitOrigin && gitBranch && gitRoot && file.startsWith(gitRoot)) {
+      frontmatter.edit = `${gitOrigin}/blob/${gitBranch}${file.replace(gitRoot, '')}`;
+      session.log.debug(`Added edit URL ${frontmatter.edit} to ${file}`);
+    }
+  } catch {
+    session.log.debug(`Unable to add edit URL to ${file}`);
+  }
+}
diff --git a/packages/myst-frontmatter/src/project/types.ts b/packages/myst-frontmatter/src/project/types.ts
@@ -33,6 +33,7 @@ export const PROJECT_AND_PAGE_FRONTMATTER_KEYS = [
   'exports',
   'downloads',
   'settings', // We maybe want to move this into site frontmatter in the future
+  'edit',
   ...KNOWN_EXTERNAL_IDENTIFIERS,
   // Do not add any project specific keys here!
   ...SITE_FRONTMATTER_KEYS,
@@ -73,6 +74,7 @@ export type ProjectAndPageFrontmatter = SiteFrontmatter & {
   exports?: Export[];
   downloads?: Download[];
   settings?: ProjectSettings;
+  edit?: string | null;
 };
 
 export type ProjectFrontmatter = ProjectAndPageFrontmatter & {

diff --git a/packages/myst-frontmatter/src/project/validators.ts b/packages/myst-frontmatter/src/project/validators.ts
@@ -235,6 +235,11 @@ export function validateProjectAndPageFrontmatterKeys(
     );
     if (settings) output.settings = settings;
   }
+  if (value.edit === null) {
+    output.edit = null;
+  } else if (defined(value.edit)) {
+    output.edit = validateUrl(value.edit, incrementOptions('edit', opts));
+  }
   return output;
 }