feat: add "Edit this page" link (#130)

Author: AriPerkkio

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

@@ -48,6 +48,13 @@ type I18nText = {
    */
   partTemplate?: string,
 
+  /**
+   * Text of the edit page link.
+   *
+   * @default 'Edit this page'
+   */
+  editPageText?: string
+
   /**
    * Text shown when there are no previews or steps to show in the prepare environment section.
    *
@@ -170,3 +177,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](/reference/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>{lesson.data.i18n!.editPageText}</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

@@ -7,7 +7,7 @@ import type {
   Tutorial,
   TutorialSchema,
 } from '@tutorialkit/types';
-import { folderPathToFilesRef } from '@tutorialkit/types';
+import { folderPathToFilesRef, interpolateString } from '@tutorialkit/types';
 import { getCollection } from 'astro:content';
 import glob from 'fast-glob';
 import path from 'node:path';
@@ -44,6 +44,7 @@ export async function getTutorial(): Promise<Tutorial> {
           partTemplate: 'Part ${index}: ${title}',
           noPreviewNorStepsText: 'No preview to run nor steps to show',
           startWebContainerText: 'Run this tutorial',
+          editPageText: 'Edit this page',
         } satisfies Lesson['data']['i18n'],
         tutorialMetaData.i18n,
       );
@@ -90,6 +91,7 @@ export async function getTutorial(): Promise<Tutorial> {
       const lesson: Lesson = {
         data,
         id: lessonId,
+        filepath: id,
         order: -1,
         part: {
           id: partId,
@@ -251,7 +253,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 +287,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 = interpolateString(lesson.data.editPageLink, { path: lesson.filepath });
+    }
+  }
 
   return _tutorial;
 }

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

@@ -50,7 +50,7 @@
   ],
   "scripts": {
     "build": "node ./scripts/build.js",
-    "test": "vitest"
+    "test": "vitest --passWithNoTests"
   },
   "dependencies": {
     "@codemirror/autocomplete": "^6.16.3",

packages/components/react/package.json

@@ -1,11 +1,10 @@
-import type { Lesson, NavItem, NavList } from '@tutorialkit/types';
+import { interpolateString, type Lesson, type NavItem, type NavList } from '@tutorialkit/types';
 import * as Accordion from '@radix-ui/react-accordion';
 import navStyles from './styles/nav.module.css';
 import { classNames } from './utils/classnames.js';
 import { AnimatePresence, cubicBezier, motion } from 'framer-motion';
 import { useCallback, useRef, useState } from 'react';
 import { useOutsideClick } from './hooks/useOutsideClick.js';
-import { interpolateString } from './utils/interpolation.js';
 
 const dropdownEasing = cubicBezier(0.4, 0, 0.2, 1);
 

packages/components/react/src/Nav.tsx

@@ -6,4 +6,3 @@ export * from './Panels/TerminalPanel.js';
 export * from './Panels/WorkspacePanel.js';
 export type * from './core/types.js';
 export * from './utils/classnames.js';
-export * from './utils/interpolation.js';

packages/components/react/src/index.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

@@ -1,3 +1,4 @@
 export type * from './entities/index.js';
 export * from './schemas/index.js';
 export * from './files-ref.js';
+export { interpolateString } from './utils/interpolation.js';

packages/types/src/index.ts

@@ -151,6 +151,15 @@ export const webcontainerSchema = commandsSchema.extend({
     }),
   ]),
   i18n: i18nSchema.optional(),
+  editPageLink: z
+    .union([
+      // pattern for creating the URL
+      z.string(),
+
+      // `false` for disabling the edit link
+      z.boolean(),
+    ])
+    .optional(),
 });
 
 export const baseSchema = webcontainerSchema.extend({

packages/types/src/schemas/common.ts

@@ -8,6 +8,13 @@ export const i18nSchema = z.object({
    */
   partTemplate: z.string().optional(),
 
+  /**
+   * Text of the edit page link.
+   *
+   * @default 'Edit this page'
+   */
+  editPageText: z.string().optional(),
+
   /**
    * Text shown when there are no previews or steps to show in the prepare environment section.
    *

packages/types/src/schemas/i18n.ts

@@ -9,6 +9,16 @@ describe('interpolateString', () => {
     expect(interpolateString(template, variables)).toBe('Hello, world!');
   });
 
+  it('should interpolate variables inside URL', () => {
+    const template =
+      'https://github.com/stackblitz/tutorialkit/blob/main/packages/template/src/content/tutorial/${path}?plain=1';
+    const variables = { path: '1-basics/2-foo/1-welcome/content.md' };
+
+    expect(interpolateString(template, variables)).toBe(
+      'https://github.com/stackblitz/tutorialkit/blob/main/packages/template/src/content/tutorial/1-basics/2-foo/1-welcome/content.md?plain=1',
+    );
+  });
+
   it('should interpolate multiple variables', () => {
     const template = 'Part ${index}: ${title}';
     const variables = { index: 5, title: 'Welcome to foo bar' };