🚸 Take users directly to the GitHub editing interface when clicking "Edit this page" (#2138)

Co-authored-by: Rowan Cockett <[email protected]>
Co-authored-by: Angus Hollands <[email protected]>
Co-authored-by: Franklin Koch <[email protected]>

Author: 4 people

.changeset/new-hounds-appear.md

@@ -0,0 +1,5 @@
+---
+"myst-cli": patch
+---
+
+When clicking "edit this page" take the user directly to the GitHub edit interface

docs/frontmatter.md

@@ -206,7 +206,10 @@ The following table lists the available frontmatter fields, a brief description
   - a valid GitHub URL or `owner/reponame`
   - page can override project
 * - `edit_url`
-  - 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_url` to `null`.
+  - 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_url` to `null`.
+  - page can override project
+* - `source_url`
+  - URL to view 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 `source_url` to `null`.
   - page can override project
 * - `binder`
   - any valid URL

docs/website-navigation.md

@@ -144,14 +144,7 @@ See [](./frontmatter.md) for many kinds of metadata that configure this section.
 
 ### Use the Edit this Page button
 
-If you've added [`github` MyST frontmatter](#table-frontmatter), the MyST themes will display an "Edit this page" link for your page. This link will point to the source file for your page in GitHub, allowing a reader to quickly view the source and make an edit using GitHub's UI.
-
-:::{tip} How to use GitHub's UI to edit a page
-There are two ways to edit a URL in GitHub:
-
-1. Click the pencil icon {kbd}`✏️` to open a lightweight editor on the page.
-2. Replace `.com` with `.dev` in the URL (or, simply press the period button {kbd}`.`). This will open a VSCode editor session you can use to make more extensive edits.
-:::
+If you've added [`github` MyST frontmatter](#table-frontmatter), the MyST themes will display an "Edit this page" link for your page. This link will take the user directly to GitHub's editing interface for the given page.
 
 To override this behavior and set a manual edit URL, use the `edit_url` field in [MyST frontmatter](#table-frontmatter).
 

packages/myst-cli/src/utils/addEditUrl.ts

@@ -25,7 +25,8 @@ export async function addEditUrl(session: ISession, frontmatter: PageFrontmatter
     const getGitRoot = makeExecutable('git rev-parse --show-toplevel', gitLog);
     const gitRoot = (await getGitRoot()).trim();
     if (gitBranch && gitRoot && file.startsWith(gitRoot)) {
-      frontmatter.edit_url = `${frontmatter.github}/blob/${gitBranch}${file.replace(gitRoot, '')}`;
+      frontmatter.source_url = `${frontmatter.github}/blob/${gitBranch}${file.replace(gitRoot, '')}`;
+      frontmatter.edit_url = `${frontmatter.github}/edit/${gitBranch}${file.replace(gitRoot, '')}`;
       session.log.debug(`Added edit URL ${frontmatter.edit_url} to ${file}`);
     }
   } catch {

packages/myst-frontmatter/src/page/validators.ts

@@ -6,6 +6,7 @@ import {
   validateString,
   validateBoolean,
   validateObject,
+  validateUrl,
 } from 'simple-validators';
 import { validateProjectAndPageFrontmatterKeys } from '../project/validators.js';
 import { PAGE_FRONTMATTER_KEYS, type PageFrontmatter } from './types.js';

packages/myst-frontmatter/src/project/types.ts

@@ -35,6 +35,7 @@ export const PROJECT_AND_PAGE_FRONTMATTER_KEYS = [
   'downloads',
   'settings', // We maybe want to move this into site frontmatter in the future
   'edit_url',
+  'source_url',
   ...KNOWN_EXTERNAL_IDENTIFIERS,
   // Do not add any project specific keys here!
   ...SITE_FRONTMATTER_KEYS,
@@ -75,7 +76,9 @@ export type ProjectAndPageFrontmatter = SiteFrontmatter & {
   exports?: Export[];
   downloads?: Download[];
   settings?: ProjectSettings;
+  /** URLs to edit or view the current page source - may be disabled by setting to null at project level */
   edit_url?: string | null;
+  source_url?: string | null;
 };
 
 export type ProjectFrontmatter = ProjectAndPageFrontmatter & {

packages/myst-frontmatter/src/project/validators.ts

@@ -241,6 +241,11 @@ export function validateProjectAndPageFrontmatterKeys(
   } else if (defined(value.edit_url)) {
     output.edit_url = validateUrl(value.edit_url, incrementOptions('edit_url', opts));
   }
+  if (value.source_url === null) {
+    output.source_url = null;
+  } else if (defined(value.source_url)) {
+    output.source_url = validateUrl(value.source_url, incrementOptions('source_url', opts));
+  }
   return output;
 }