feat(astro): support lessons without parts or chapters

docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx

@@ -3,6 +3,7 @@ title: Content creation
 description: 'Creating content in TutorialKit.'
 ---
 import { FileTree } from '@astrojs/starlight/components';
+import { Tabs, TabItem } from '@astrojs/starlight/components';
 
 From an information architecture perspective, tutorial content is divided into **parts**, which are further divided into **chapters**, each consisting of **lessons**.
 
@@ -36,6 +37,64 @@ This structure is reflected in the directory structure of your TutorialKit proje
 
 Navigate into one of these folders to see another folder that represents a **chapter**. Inside the chapter folder, you will find one or more **lesson** folders.
 
+You can also omit parts or chapters such that you only have lessons or only lessons and parts. Here are a few examples:
+
+<Tabs>
+  <TabItem label="Structure">
+    ```plaintext
+    - Lesson 1: Getting started
+    - Lesson 2: Adding pages
+    ```
+  </TabItem>
+
+  <TabItem label="File tree">
+    <FileTree>
+      - src
+        - content
+          - tutorial
+            - getting-started
+              - _files/
+              - _solution/
+              - content.md
+            - adding-pages/
+            - meta.md
+        - config.ts
+        - templates/
+    </FileTree>
+  </TabItem>
+</Tabs>
+
+<Tabs>
+  <TabItem label="Structure">
+    ```plaintext
+    - Part 1: Introduction
+      - Lesson 1: What is Vite?
+      - Lesson 2: Installing
+        - …
+    - Part 2: Project structure
+        - …
+    ```
+  </TabItem>
+
+  <TabItem label="File tree">
+    <FileTree>
+      - src
+        - content
+          - tutorial
+            - introduction/
+              - what-is-vite/
+                - _files/
+                - _solution/
+                - content.md
+              - installing/
+            - project-structure/
+            - meta.md
+        - config.ts
+        - templates/
+    </FileTree>
+  </TabItem>
+</Tabs>
+
 ## A lesson content file
 
 Navigate to the `src/content/tutorial/1-basics/1-introduction/1-welcome` folder and open the `content.md` in your editor. You will see a file structured like this:

e2e/configs/lessons-in-part.ts

@@ -0,0 +1,10 @@
+import tutorialkit from '@tutorialkit/astro';
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  devToolbar: { enabled: false },
+  server: { port: 4332 },
+  outDir: './dist-lessons-in-part',
+  integrations: [tutorialkit()],
+  srcDir: './src-custom/lessons-in-part',
+});

e2e/configs/lessons-in-root.ts

@@ -0,0 +1,10 @@
+import tutorialkit from '@tutorialkit/astro';
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  devToolbar: { enabled: false },
+  server: { port: 4331 },
+  outDir: './dist-lessons-in-root',
+  integrations: [tutorialkit()],
+  srcDir: './src-custom/lessons-in-root',
+});

e2e/package.json

@@ -7,6 +7,10 @@
     "preview": "astro build && astro preview",
     "dev:override-components": "astro dev --config ./configs/override-components.ts",
     "preview:override-components": "astro build --config ./configs/override-components.ts && astro preview --config ./configs/override-components.ts",
+    "dev:lessons-in-root": "astro dev --config ./configs/lessons-in-root.ts",
+    "preview:lessons-in-root": "astro build --config ./configs/lessons-in-root.ts && astro preview --config ./configs/lessons-in-root.ts",
+    "dev:lessons-in-part": "astro dev --config ./configs/lessons-in-part.ts",
+    "preview:lessons-in-part": "astro build --config ./configs/lessons-in-part.ts && astro preview --config ./configs/lessons-in-part.ts",
     "test": "playwright test",
     "test:ui": "pnpm run test --ui"
   },

e2e/playwright.config.ts

@@ -1,33 +1,59 @@
 import { defineConfig } from '@playwright/test';
 
+const serverOptions = {
+  reuseExistingServer: !process.env.CI,
+  stdout: 'ignore',
+  stderr: 'pipe',
+} as const;
+
 export default defineConfig({
   projects: [
     {
       name: 'Default',
       testMatch: 'test/*.test.ts',
-      testIgnore: 'test/*.override-components.test.ts',
+      testIgnore: [
+        'test/*.override-components.test.ts',
+        'test/*.lessons-in-part.test.ts',
+        'test/*.lessons-in-root.test.ts',
+      ],
       use: { baseURL: 'http://localhost:4329' },
     },
     {
       name: 'Override Components',
       testMatch: 'test/*.override-components.test.ts',
       use: { baseURL: 'http://localhost:4330' },
     },
+    {
+      name: 'Lessons in root',
+      testMatch: 'test/*.lessons-in-root.test.ts',
+      use: { baseURL: 'http://localhost:4331' },
+    },
+    {
+      name: 'Lessons in part',
+      testMatch: 'test/*.lessons-in-part.test.ts',
+      use: { baseURL: 'http://localhost:4332' },
+    },
   ],
   webServer: [
     {
       command: 'pnpm preview',
       url: 'http://localhost:4329',
-      reuseExistingServer: !process.env.CI,
-      stdout: 'ignore',
-      stderr: 'pipe',
+      ...serverOptions,
     },
     {
       command: 'pnpm preview:override-components',
       url: 'http://localhost:4330',
-      reuseExistingServer: !process.env.CI,
-      stdout: 'ignore',
-      stderr: 'pipe',
+      ...serverOptions,
+    },
+    {
+      command: 'pnpm preview:lessons-in-root',
+      url: 'http://localhost:4331',
+      ...serverOptions,
+    },
+    {
+      command: 'pnpm preview:lessons-in-part',
+      url: 'http://localhost:4332',
+      ...serverOptions,
     },
   ],
   expect: {

e2e/src-custom/lessons-in-part/content/config.ts

@@ -0,0 +1,9 @@
+import { contentSchema } from '@tutorialkit/types';
+import { defineCollection } from 'astro:content';
+
+const tutorial = defineCollection({
+  type: 'content',
+  schema: contentSchema,
+});
+
+export const collections = { tutorial };

e2e/src-custom/lessons-in-part/content/tutorial/meta.md

@@ -0,0 +1,5 @@
+---
+type: tutorial
+mainCommand: ''
+prepareCommands: []
+---

e2e/src-custom/lessons-in-part/content/tutorial/part-one/lesson-1/content.md

@@ -0,0 +1,8 @@
+---
+type: lesson
+title: Lesson one
+---
+
+# Lessons in part test - Lesson one
+
+Lesson in part without chapter

e2e/src-custom/lessons-in-part/content/tutorial/part-one/lesson-2/content.md

@@ -0,0 +1,8 @@
+---
+type: lesson
+title: Lesson two
+---
+
+# Lessons in part test - Lesson two
+
+Lesson in part without chapter

e2e/src-custom/lessons-in-part/content/tutorial/part-one/meta.md

@@ -0,0 +1,4 @@
+---
+type: part
+title: 'Part one'
+---

e2e/src-custom/lessons-in-part/content/tutorial/part-two/chapter-one/lesson-3/content.md

@@ -0,0 +1,8 @@
+---
+type: lesson
+title: Lesson three
+---
+
+# Lessons in part test - Lesson three
+
+Lesson in chapter

e2e/src-custom/lessons-in-part/content/tutorial/part-two/chapter-one/lesson-4/content.md

@@ -0,0 +1,8 @@
+---
+type: lesson
+title: Lesson four
+---
+
+# Lessons in part test - Lesson four
+
+Lesson in chapter

e2e/src-custom/lessons-in-part/content/tutorial/part-two/chapter-one/meta.md

@@ -0,0 +1,4 @@
+---
+type: chapter
+title: 'Chapter one'
+---

e2e/src-custom/lessons-in-part/content/tutorial/part-two/meta.md

@@ -0,0 +1,4 @@
+---
+type: part
+title: 'Part two'
+---

e2e/src-custom/lessons-in-part/env.d.ts

@@ -0,0 +1,3 @@
+/// <reference path="../../.astro/types.d.ts" />
+/// <reference types="@tutorialkit/astro/types" />
+/// <reference types="astro/client" />

e2e/src-custom/lessons-in-root/content/config.ts

@@ -0,0 +1,9 @@
+import { contentSchema } from '@tutorialkit/types';
+import { defineCollection } from 'astro:content';
+
+const tutorial = defineCollection({
+  type: 'content',
+  schema: contentSchema,
+});
+
+export const collections = { tutorial };

e2e/src-custom/lessons-in-root/content/tutorial/lesson-one/content.md

@@ -0,0 +1,8 @@
+---
+type: lesson
+title: Lesson one
+---
+
+# Lessons in root test - Lesson one
+
+Lesson in root without part

e2e/src-custom/lessons-in-root/content/tutorial/lesson-two/content.md

@@ -0,0 +1,8 @@
+---
+type: lesson
+title: Lesson two
+---
+
+# Lessons in root test - Lesson two
+
+Lesson in root without part

e2e/src-custom/lessons-in-root/content/tutorial/meta.md

@@ -0,0 +1,5 @@
+---
+type: tutorial
+mainCommand: ''
+prepareCommands: []
+---

e2e/src-custom/lessons-in-root/env.d.ts

@@ -0,0 +1,3 @@
+/// <reference path="../../.astro/types.d.ts" />
+/// <reference types="@tutorialkit/astro/types" />
+/// <reference types="astro/client" />

e2e/test/navigation.lessons-in-part.test.ts

@@ -0,0 +1,62 @@
+import { test, expect } from '@playwright/test';
+
+test('user can navigate between lessons using breadcrumbs', async ({ page }) => {
+  await page.goto('/');
+
+  await expect(page.getByRole('heading', { level: 1, name: 'Lessons in part test - Lesson one' })).toBeVisible();
+  await expect(page.getByText('Lesson in part without chapter')).toBeVisible();
+
+  // navigation select can take a while to hydrate on page load, click until responsive
+  await expect(async () => {
+    const button = page.getByRole('button', { name: 'Part one / Lesson one' });
+    await button.click();
+    await expect(page.locator('[data-state="open"]', { has: button })).toBeVisible({ timeout: 50 });
+  }).toPass();
+
+  const navigation = page.getByRole('navigation');
+  await navigation.getByRole('region', { name: 'Part 1: Part one' }).getByRole('link', { name: 'Lesson two' }).click();
+
+  await expect(page.getByRole('heading', { level: 1, name: 'Lessons in part test - Lesson two' })).toBeVisible();
+  await expect(page.getByText('Lesson in part without chapter')).toBeVisible();
+
+  await expect(async () => {
+    const button = page.getByRole('button', { name: 'Part one / Lesson two' });
+    await button.click();
+    await expect(page.locator('[data-state="open"]', { has: button })).toBeVisible({ timeout: 50 });
+  }).toPass();
+
+  // expand part
+  await navigation.getByRole('button', { name: 'Part 2: Part two' }).click();
+
+  // expand chapter
+  await navigation
+    .getByRole('region', { name: 'Part 2: Part two' })
+    .getByRole('button', { name: 'Chapter one' })
+    .click();
+
+  // select lesson
+  await navigation.getByRole('region', { name: 'Chapter one' }).getByRole('link', { name: 'Lesson three' }).click();
+
+  await expect(page.getByRole('heading', { level: 1, name: 'Lessons in part test - Lesson three' })).toBeVisible();
+  await expect(page.getByText('Lesson in chapter')).toBeVisible();
+});
+
+test('user can navigate between lessons using nav bar links', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.getByRole('heading', { level: 1, name: 'Lessons in part test - Lesson one' })).toBeVisible();
+  await expect(page.getByText('Lesson in part without chapter')).toBeVisible();
+
+  await navigateToPage('Lesson two');
+  await expect(page.getByText('Lesson in part without chapter')).toBeVisible();
+
+  await navigateToPage('Lesson three');
+  await expect(page.getByText('Lesson in chapter')).toBeVisible();
+
+  await navigateToPage('Lesson four');
+  await expect(page.getByText('Lesson in chapter')).toBeVisible();
+
+  async function navigateToPage(title: string) {
+    await page.getByRole('link', { name: title }).click();
+    await expect(page.getByRole('heading', { level: 1, name: `Lessons in part test - ${title}` })).toBeVisible();
+  }
+});

e2e/test/navigation.lessons-in-root.test.ts

@@ -0,0 +1,19 @@
+import { test, expect } from '@playwright/test';
+
+test('user can navigate between lessons using breadcrumbs', async ({ page }) => {
+  await page.goto('/lesson-one');
+
+  await expect(page.getByRole('heading', { level: 1, name: 'Lessons in root test - Lesson one' })).toBeVisible();
+  await expect(page.getByText('Lesson in root without part')).toBeVisible();
+
+  // navigation select can take a while to hydrate on page load, click until responsive
+  await expect(async () => {
+    const button = page.getByRole('button', { name: 'Lesson one' });
+    await button.click();
+    await expect(page.locator('[data-state="open"]', { has: button })).toBeVisible({ timeout: 50 });
+  }).toPass();
+
+  await page.getByRole('navigation').getByRole('link', { name: 'Lesson two' }).click();
+
+  await expect(page.getByRole('heading', { level: 1, name: 'Lessons in root test - Lesson two' })).toBeVisible();
+});

packages/astro/src/default/pages/index.astro

@@ -4,11 +4,13 @@ import { joinPaths } from '../utils/url';
 
 const tutorial = await getTutorial();
 
-const part = tutorial.parts[tutorial.firstPartId!];
-const chapter = part.chapters[part?.firstChapterId!];
-const lesson = chapter.lessons[chapter?.firstLessonId!];
+const lesson = tutorial.lessons[0];
+const part = lesson.part && tutorial.parts[lesson.part.id];
+const chapter = lesson.chapter && part?.chapters[lesson.chapter.id];
 
-const redirect = joinPaths(import.meta.env.BASE_URL, `/${part.slug}/${chapter.slug}/${lesson.slug}`);
+const slug = [part?.slug, chapter?.slug, lesson.slug].filter(Boolean).join('/');
+
+const redirect = joinPaths(import.meta.env.BASE_URL, `/${slug}`);
 ---
 
 <!doctype html>