set metadata in a lesson

eric-burel · eric-burel · commit 8520db2b80ed · 2024-09-28T10:37:40.000+02:00
diff --git a/docs/tutorialkit.dev/src/content/docs/guides/deployment.mdx b/docs/tutorialkit.dev/src/content/docs/guides/deployment.mdx
@@ -36,7 +36,7 @@ You can learn more about the build process in the [Astro documentation](https://
 
 ## Environment variables
 
-The `BASE_URL` environment variable should point to your website's absolute URL.
+The [`BASE_URL`](https://docs.astro.build/en/guides/environment-variables/#default-environment-variables) environment variable should point to your website's absolute URL.
 This will allow to compute absolute URLs for SEO metadata.
 
 Example:
diff --git a/packages/astro/src/default/components/MetaTags.astro b/packages/astro/src/default/components/MetaTags.astro
@@ -0,0 +1,35 @@
+---
+import type { MetaTagsConfig } from '@tutorialkit/types';
+import { readFaviconFile } from '../utils/favicon';
+import { readLogoFile } from '../utils/logo';
+import { readPublicImage } from '../utils/publicImage';
+
+interface Props {
+  meta?: MetaTagsConfig;
+}
+const { meta = {} } = Astro.props;
+let imageUrl;
+if (meta.image) {
+  imageUrl = readPublicImage(meta.image);
+  if (!imageUrl) {
+    console.warn(`Image ${meta.image} not found in "/public" folder`);
+  }
+}
+imageUrl ??= readLogoFile();
+const faviconUrl = readFaviconFile();
+---
+
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width" />
+<meta name="generator" content={Astro.generator} />
+{meta.description ? <meta name="description" content={meta.description} /> : null}
+{meta.title ? <title>{meta.title}</title> : null}
+{faviconUrl ? <link rel="icon" type="image/svg+xml" href={faviconUrl} /> : null}
+{/* open graph */}
+{meta.title ? <meta name="og:title" content={meta.title} /> : null}
+{meta.description ? <meta name="og:description" content={meta.description} /> : null}
+{imageUrl ? <meta name="og:image" content={imageUrl} /> : null}
+{/* twitter */}
+{meta.title ? <meta name="twitter:title" content={meta.title} /> : null}
+{meta.description ? <meta name="twitter:description" content={meta.description} /> : null}
+{imageUrl ? <meta name="twitter:image" content={imageUrl} /> : null}
diff --git a/packages/astro/src/default/layouts/Layout.astro b/packages/astro/src/default/layouts/Layout.astro
@@ -1,33 +1,18 @@
 ---
 import { ViewTransitions } from 'astro:transitions';
-import { readFaviconFile } from '../utils/favicon';
-import { readLogoFile } from '../utils/logo';
+import type { MetaTagsConfig } from '@tutorialkit/types';
+import MetaTags from '../components/MetaTags.astro';
 
 interface Props {
-  title: string;
-  description?: string;
+  meta?: MetaTagsConfig;
 }
-
-const { title, description = 'TutorialKit' } = Astro.props;
-const logoUrl = readLogoFile();
-const faviconUrl = readFaviconFile();
+const { meta } = Astro.props;
 ---
 
 <!doctype html>
 <html lang="en" transition:animate="none" class="h-full overflow-hidden">
   <head>
-    <meta charset="UTF-8" />
-    <meta name="description" content={description} />
-    <meta name="viewport" content="width=device-width" />
-    <meta name="generator" content={Astro.generator} />
-    <meta name="og:title" content={title} />
-    <meta name="og:description" content={description} />
-    {logoUrl ? <meta name="og:image" content={logoUrl} /> : null}
-    <meta name="twitter:title" content={title} />
-    <meta name="twitter:description" content={description} />
-    {logoUrl ? <meta name="twitter:image" content={logoUrl} /> : null}
-    <title>{title}</title>
-    {faviconUrl ? <link rel="icon" type="image/svg+xml" href={faviconUrl} /> : null}
+    <MetaTags meta={meta} />
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
diff --git a/packages/astro/src/default/pages/[...slug].astro b/packages/astro/src/default/pages/[...slug].astro
@@ -15,9 +15,13 @@ export async function getStaticPaths() {
 type Props = InferGetStaticPropsType<typeof getStaticPaths>;
 
 const { lesson, logoLink, navList, title } = Astro.props as Props;
+const meta = lesson.data?.meta || {};
+// Use lesson default title and a default description for SEO metadata
+meta.title ??= title;
+meta.description ??= 'A TutorialKit interactive lesson';
 ---
 
-<Layout title={title} description="A TutorialKit interactive lesson">
+<Layout meta={meta}>
   <PageLoadingIndicator />
   <div id="previews-container"></div>
   <main class="max-w-full flex flex-col h-full overflow-hidden" data-swap-root>
diff --git a/packages/astro/src/default/utils/content.ts b/packages/astro/src/default/utils/content.ts
@@ -245,6 +245,7 @@ export async function getTutorial(): Promise<Tutorial> {
           'editor',
           'focus',
           'i18n',
+          'meta',
           'editPageLink',
           'openInStackBlitz',
           'filesystem',
diff --git a/packages/astro/src/default/utils/favicon.ts b/packages/astro/src/default/utils/favicon.ts
@@ -1,16 +1,6 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { joinPaths } from './url';
+import { readPublicImage } from './publicImage';
 
 export function readFaviconFile(faviconPrefix: string = 'favicon') {
-  let favicon;
-
   const faviconFilename = `${faviconPrefix}.svg`;
-  const exists = fs.existsSync(path.join('public', faviconFilename));
-
-  if (exists) {
-    favicon = joinPaths(import.meta.env.BASE_URL, faviconFilename);
-  }
-
-  return favicon;
+  return readPublicImage(faviconFilename);
 }
diff --git a/packages/astro/src/default/utils/logo.ts b/packages/astro/src/default/utils/logo.ts
@@ -1,17 +1,14 @@
-import fs from 'node:fs';
-import path from 'node:path';
 import { LOGO_EXTENSIONS } from './constants';
-import { joinPaths } from './url';
+import { readPublicImage } from './publicImage';
 
 export function readLogoFile(logoPrefix: string = 'logo') {
   let logo;
 
   for (const logoExt of LOGO_EXTENSIONS) {
     const logoFilename = `${logoPrefix}.${logoExt}`;
-    const exists = fs.existsSync(path.join('public', logoFilename));
+    logo = readPublicImage(logoFilename);
 
-    if (exists) {
-      logo = joinPaths(import.meta.env.BASE_URL, logoFilename);
+    if (logo) {
       break;
     }
   }
diff --git a/packages/astro/src/default/utils/publicImage.ts b/packages/astro/src/default/utils/publicImage.ts
@@ -0,0 +1,14 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { joinPaths } from './url';
+
+export function readPublicImage(filename: string) {
+  let image;
+  const exists = fs.existsSync(path.join('public', filename));
+
+  if (exists) {
+    image = joinPaths(import.meta.env.BASE_URL, filename);
+  }
+
+  return image;
+}
diff --git a/packages/astro/src/default/utils/routes.ts b/packages/astro/src/default/utils/routes.ts
@@ -26,6 +26,7 @@ export async function generateStaticRoutes() {
             logoLink: tutorial.logoLink,
             navList: generateNavigationList(tutorial, import.meta.env.BASE_URL),
             title: `${part.data.title} / ${chapter.data.title} / ${lesson.data.title}`,
+            meta: lesson.data.meta,
             lesson: lesson as Lesson<AstroComponentFactory>,
           },
         } satisfies GetStaticPathsItem);
diff --git a/packages/template/src/content/tutorial/1-basics/1-introduction/1-welcome/content.md b/packages/template/src/content/tutorial/1-basics/1-introduction/1-welcome/content.md
@@ -11,6 +11,9 @@ prepareCommands:
   - ['node -e setTimeout(()=>{process.exit(1)},5000)', 'This is going to fail']
 terminal:
   panels: ['terminal', 'output']
+meta: 
+    description: "This is lesson 1"
+    image: "/logo.svg"
 ---
 
 # Kitchen Sink [Heading 1]
diff --git a/packages/types/src/entities/index.ts b/packages/types/src/entities/index.ts
@@ -1,5 +1,6 @@
 import type { I18nSchema } from '../schemas/i18n.js';
 import type { ChapterSchema, LessonSchema, PartSchema } from '../schemas/index.js';
+import type { MetaTagsSchema } from '../schemas/metatags.js';
 
 export type * from './nav.js';
 
@@ -57,6 +58,8 @@ export interface Lesson<T = unknown> {
 
 export type I18n = Required<NonNullable<I18nSchema>>;
 
+export type MetaTagsConfig = MetaTagsSchema;
+
 export interface Tutorial {
   logoLink?: string;
   firstPartId?: string;
diff --git a/packages/types/src/schemas/common.ts b/packages/types/src/schemas/common.ts
@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { i18nSchema } from './i18n.js';
+import { metaTagsSchema } from './metatags.js';
 
 export const commandSchema = z.union([
   // a single string, the command to run
@@ -286,6 +287,7 @@ export const webcontainerSchema = commandsSchema.extend({
 
 export const baseSchema = webcontainerSchema.extend({
   title: z.string().describe('The title of the part, chapter, or lesson.'),
+  meta: metaTagsSchema.optional(),
   slug: z
     .string()
     .optional()
diff --git a/packages/types/src/schemas/metatags.ts b/packages/types/src/schemas/metatags.ts
@@ -0,0 +1,16 @@
+import { z } from 'zod';
+
+export const metaTagsSchema = z.object({
+  image: z
+    .string()
+    .optional()
+    /**
+     * Ideally we would have want to use image from:
+     * https://docs.astro.build/en/guides/images/#images-in-content-collections .
+     */
+    .describe('An image to show on social previews, should point to the public folder: "/foobar.png"'),
+  description: z.string().optional().describe('A description for metadata'),
+  title: z.string().optional().describe('A title to use specifically for metadata'),
+});
+
+export type MetaTagsSchema = z.infer<typeof metaTagsSchema>;
