feat: add "Edit this page" link

Author: AriPerkkio

docs/tutorialkit.dev/src/content/docs/reference/configuration.mdx

@@ -170,3 +170,30 @@ Navigating to a lesson that specifies `autoReload` will always reload the previe
 Specified which folder from the `src/templates/` directory should be used as the basis for the code. See the "[Code templates](/guides/creating-content/#code-templates)" guide for a detailed explainer.
 <PropertyTable inherited type="string" />
 
+#### `editPageLink`
+Display a link in lesson for editing the page content.
+The value is a URL pattern where `:path` is replaced with the lesson's location relative to the `src/content/tutorial`.
+
+<PropertyTable inherited type="string|false" />
+
+```yaml
+editPageLink: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/src/content/tutorial/:path
+```
+
+The inherited value can be disabled in specific parts using `false`.
+
+```yaml
+editPageLink: false
+```
+
+:::tip
+Note that Github will try to automatically render the `.md` files when linked to.
+You can instruct Github to show the source code instead by adding `plain=1` query parameter.
+
+```diff
+-editPageLink: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/src/content/tutorial/:path
++editPageLink: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/src/content/tutorial/:path?plain=1
+```
+
+:::
+

docs/tutorialkit.dev/src/content/docs/reference/images/theming-editpagelink.png

@@ -316,6 +316,20 @@ The navigation cards are the cards at the bottom of a lesson to navigate to the
 | `--tk-elements-navCard-iconColor`            | The icon color of the navigation card.                     |
 | `--tk-elements-navCard-iconColorHover`       | The icon color of the navigation card when hovering.       |
 
+### Edit Page Link
+
+The edit page link is shown above the navigation cards when configured by [`editPageLink` option](../configuration/#editpagelink).
+
+![Edit Page Link](./images/theming-editpagelink.png)
+
+| Token                                       | Description                                         |
+| ------------------------------------------- | --------------------------------------------------- |
+| `--tk-elements-editPageLink-textColor`      | The text color of the edit page link                |
+| `--tk-elements-editPageLink-textColorHover` | The text color of the edit page link when hovering. |
+| `--tk-elements-editPageLink-iconColor`      | The icon color of the edit page link                |
+| `--tk-elements-editPageLink-iconColorHover` | The icon color of the edit page link when hovering  |
+| `--tk-elements-editPageLink-borderColor`    | The border color of the edit page link              |
+
 ### Breadcrumbs
 
 The breadcrumbs are the navigation elements that show the path of the current lesson. The breadcrumbs are divided into multiple parts.

docs/tutorialkit.dev/src/content/docs/reference/theming.mdx

@@ -8,13 +8,28 @@ interface Props {
 }
 
 const { lesson } = Astro.props;
-const { Markdown, prev, next } = lesson;
+const { Markdown, editPageLink, prev, next } = lesson;
 ---
 
 <div class="h-full overflow-auto scrollbar-transparent p-6 sm:p-8">
   <div class="markdown-content text-tk-elements-content-textColor">
     <Markdown />
   </div>
+
+  {
+    editPageLink && (
+      <div class="pb-4 mt-8 border-b border-tk-elements-editPageLink-borderColor">
+        <a
+          href={editPageLink}
+          class="inline-flex flex-items-center text-tk-elements-editPageLink-textColor hover:text-tk-elements-editPageLink-textColorHover hover:underline"
+        >
+          <span class="icon i-ph-note-pencil pointer-events-none h-5 w-5 mr-2 text-tk-elements-editPageLink-iconColor group-hover:text-tk-elements-editPageLink-iconColorHover" />
+          <span>Edit this page</span>
+        </a>
+      </div>
+    )
+  }
+
   <div class="grid grid-cols-[1fr_1fr] gap-4 mt-8">
     <div class="flex">
       {prev && <NavCard lesson={prev} type="prev" />}

packages/astro/src/default/components/TutorialContent.astro

@@ -245,6 +245,13 @@
   --tk-elements-navCard-iconColor: var(--tk-elements-app-textColor);
   --tk-elements-navCard-iconColorHover: var(--tk-text-accent);
 
+  /* Edit Page Link */
+  --tk-elements-editPageLink-textColor: var(--tk-elements-app-textColor);
+  --tk-elements-editPageLink-textColorHover: var(--tk-text-active);
+  --tk-elements-editPageLink-iconColor: var(--tk-elements-app-textColor);
+  --tk-elements-editPageLink-iconColorHover: var(--tk-text-accent);
+  --tk-elements-editPageLink-borderColor: var(--tk-border-secondary);
+
   /* Breadcrumb > Nav Button */
   --tk-elements-breadcrumbs-navButton-iconColor: var(--tk-text-secondary);
   --tk-elements-breadcrumbs-navButton-iconColorHover: var(--tk-text-active);

packages/astro/src/default/styles/variables.css

@@ -90,6 +90,7 @@ export async function getTutorial(): Promise<Tutorial> {
       const lesson: Lesson = {
         data,
         id: lessonId,
+        filepath: id,
         order: -1,
         part: {
           id: partId,
@@ -251,7 +252,18 @@ export async function getTutorial(): Promise<Tutorial> {
       ...lesson.data,
       ...squash(
         [lesson.data, chapterMetadata, partMetadata, tutorialMetaData],
-        ['mainCommand', 'prepareCommands', 'previews', 'autoReload', 'template', 'terminal', 'editor', 'focus', 'i18n'],
+        [
+          'mainCommand',
+          'prepareCommands',
+          'previews',
+          'autoReload',
+          'template',
+          'terminal',
+          'editor',
+          'focus',
+          'i18n',
+          'editPageLink',
+        ],
       ),
     };
 
@@ -274,9 +286,11 @@ export async function getTutorial(): Promise<Tutorial> {
         href: joinPaths(baseURL, `/${partSlug}/${chapterSlug}/${nextLesson.slug}`),
       };
     }
-  }
 
-  // console.log(inspect(_tutorial, undefined, Infinity, true));
+    if (lesson.data.editPageLink && typeof lesson.data.editPageLink === 'string') {
+      lesson.editPageLink = lesson.data.editPageLink.replace(':path', lesson.filepath);
+    }
+  }
 
   return _tutorial;
 }

packages/astro/src/default/utils/content.ts

@@ -252,6 +252,13 @@ export const theme = {
           iconColor: 'var(--tk-elements-navCard-iconColor)',
           iconColorHover: 'var(--tk-elements-navCard-iconColorHover)',
         },
+        editPageLink: {
+          textColor: 'var(--tk-elements-editPageLink-textColor)',
+          textColorHover: 'var(--tk-elements-editPageLink-textColorHover)',
+          iconColor: 'var(--tk-elements-editPageLink-iconColor)',
+          iconColorHover: 'var(--tk-elements-editPageLink-iconColorHover)',
+          borderColor: 'var(--tk-elements-editPageLink-borderColor)',
+        },
         breadcrumbs: {
           navButton: {
             iconColor: 'var(--tk-elements-breadcrumbs-navButton-iconColor)',

packages/theme/src/theme.ts

@@ -40,6 +40,8 @@ export interface Lesson<T = unknown> {
   part: { id: string; title: string };
   chapter: { id: string; title: string };
   slug: string;
+  filepath: string;
+  editPageLink?: string;
   files: FilesRefList;
   solution: FilesRefList;
   next?: LessonLink;

packages/types/src/entities/index.ts

@@ -153,9 +153,18 @@ export const webcontainerSchema = commandsSchema.extend({
   i18n: i18nSchema.optional(),
 });
 
+export const editPageLinkSchema = z.union([
+  // pattern for creating the URL
+  z.string(),
+
+  // `false` for disabling the edit link
+  z.boolean(),
+]);
+
 export const baseSchema = webcontainerSchema.extend({
   title: z.string(),
   slug: z.string().optional(),
+  editPageLink: editPageLinkSchema.optional(),
 });
 
 export type BaseSchema = z.infer<typeof baseSchema>;

packages/types/src/schemas/common.ts

@@ -1,9 +1,10 @@
 import { z } from 'zod';
-import { webcontainerSchema } from './common.js';
+import { webcontainerSchema, editPageLinkSchema } from './common.js';
 
 export const tutorialSchema = webcontainerSchema.extend({
   type: z.literal('tutorial'),
   logoLink: z.string().optional(),
+  editPageLink: editPageLinkSchema.optional(),
   parts: z.array(z.string()).optional(),
 });