Merge remote-tracking branch 'upstream/main' into ronith/overriding-footer

Author: AriPerkkio

.github/workflows/publish-docs.yaml

@@ -0,0 +1,30 @@
+# This is for publishing documentation manually.
+# During release `publish-release.yaml` publishes docs automatically.
+name: Publish Documentation
+
+on:
+  workflow_dispatch:
+
+jobs:
+  publish_docs:
+    name: Publish documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/setup-and-build
+
+      - name: Build docs
+        run: pnpm run docs:build
+
+      - name: Deploy documentation
+        uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: tutorialkit-docs-page
+          workingDirectory: 'docs/tutorialkit.dev'
+          directory: dist

CHANGELOG.md

@@ -1,3 +1,50 @@
+# [1.3.0](https://github.com/stackblitz/tutorialkit/compare/1.2.2...1.3.0) (2024-11-15)
+
+
+### Bug Fixes
+
+* remove `downloadAsZip` from template for now ([#416](https://github.com/stackblitz/tutorialkit/issues/416)) ([705fead](https://github.com/stackblitz/tutorialkit/commit/705fead006988a4ae865c9171062bd7d3afb3206))
+
+
+### Features
+
+* **astro:** add "Download lesson as zip" button ([#415](https://github.com/stackblitz/tutorialkit/issues/415)) ([9c6e534](https://github.com/stackblitz/tutorialkit/commit/9c6e5349b6ab7e7399437839f6fc4cf11bd6c5c3))
+* **astro:** support lessons without parts or chapters ([#374](https://github.com/stackblitz/tutorialkit/issues/374)) ([8c44cbe](https://github.com/stackblitz/tutorialkit/commit/8c44cbec3f276a4f788b5d1652f67e4cf8cf7948))
+
+
+
+## [1.2.2](https://github.com/stackblitz/tutorialkit/compare/1.2.1...1.2.2) (2024-11-12)
+
+
+### Bug Fixes
+
+* hide preview container when `previews: false` ([#412](https://github.com/stackblitz/tutorialkit/issues/412)) ([b35de43](https://github.com/stackblitz/tutorialkit/commit/b35de43d437492d124af232adddd2a30ec70ec0e))
+
+
+
+## [1.2.1](https://github.com/stackblitz/tutorialkit/compare/1.2.0...1.2.1) (2024-11-05)
+
+
+### Bug Fixes
+
+* **astro:** optimize CJS dependency `picomatch` ([#406](https://github.com/stackblitz/tutorialkit/issues/406)) ([17a48a6](https://github.com/stackblitz/tutorialkit/commit/17a48a6858912277942d87b8af28a601adfad8da))
+
+
+
+# [1.2.0](https://github.com/stackblitz/tutorialkit/compare/1.1.1...1.2.0) (2024-11-05)
+
+
+### Bug Fixes
+
+* **react:** file tree scroll visibility ([#399](https://github.com/stackblitz/tutorialkit/issues/399)) ([e1e9160](https://github.com/stackblitz/tutorialkit/commit/e1e916044cc225dab925bd846d9208181f2080e1))
+
+
+### Features
+
+* **runtime:** `fs.watch` to support syncing new files from webcontainer ([#394](https://github.com/stackblitz/tutorialkit/issues/394)) ([3beda90](https://github.com/stackblitz/tutorialkit/commit/3beda905df20ed9c7d286fc02007cf5b2e74835a))
+
+
+
 ## [1.1.1](https://github.com/stackblitz/tutorialkit/compare/1.1.0...1.1.1) (2024-10-20)
 
 

docs/tutorialkit.dev/package.json

@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@tutorialkit/react": "workspace:*",
-    "@webcontainer/api": "1.2.4",
+    "@webcontainer/api": "1.5.1",
     "classnames": "^2.5.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"

docs/tutorialkit.dev/public/tutorialkit-opengraph.png

@@ -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:
@@ -211,15 +270,15 @@ const highlighted = 'This line is highlighted';
 
 You can highlight text using strings or regular expressions. For example:
 
-````md
-```jsx "hello" /ye[sp]/ add=/add[12]/ del=/remove[12]/
+````md title="content.md"
+```jsx title="code.js" "hello" /ye[sp]/ add=/add[12]/ del=/remove[12]/
 console.log(
   'Hello, the words yes and yep will be marked. Also add1, add2, remove1, remove2',
 )
 ```
 ````
 
-```jsx "hello" /ye[sp]/ add=/add[12]/ del=/remove[12]/
+```jsx title="code.js" "hello" /ye[sp]/ add=/add[12]/ del=/remove[12]/
 console.log(
   'Hello, the words yes and yep will be marked. Also add1, add2, remove1, remove2',
 )

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

@@ -46,6 +46,7 @@ When overriding `TopBar` you can place TutorialKit's default components using fo
 
 - `logo`: Logo of the application
 - `open-in-stackblitz-link`: Link for opening current lesson in StackBlitz
+- `download-button`: Button for downloading current lesson as `.zip` file
 - `theme-switch`:  Switch for changing the theme
 - `login-button`: For StackBlitz Enterprise user, the login button
 
@@ -61,6 +62,8 @@ When overriding `TopBar` you can place TutorialKit's default components using fo
 
   <LanguageSelect />
 
+  <slot name="download-button" />
+
   <slot name="open-in-stackblitz-link" />
 
   <slot name="login-button" />

docs/tutorialkit.dev/src/content/docs/guides/overriding-components.mdx

@@ -284,13 +284,15 @@ An example use case is when a user runs a command that modifies a file. For inst
 
 This property is by default set to `false` as it can impact performance. If you are creating a lesson where the user is expected to modify files outside the editor, you may want to keep this to `false`.
 
+If you would like files to be added or removed from the editor automatically, you need to specify an array of globs that will determine which folders and files to watch for changes.
+
 <PropertyTable inherited type={'FileSystem'} />
 
 The `FileSystem` type has the following shape:
 
 ```ts
 type FileSystem = {
-  watch: boolean
+  watch: boolean | string[]
 }
 
 ```
@@ -299,10 +301,13 @@ Example values:
 
 ```yaml
 filesystem:
-  watch: true  # Filesystem changes are reflected in the editor
+  watch: true  # Filesystem changes to files already in the editor are reflected in the editor
 
 filesystem:
   watch: false # Or if it's omitted, the default value is false
+
+filesystem:
+  watch: ['/*.json', '/src/**/*'] # Files changed, added or deleted that match one of the globs are updated in the editor
 ```
 
 
@@ -407,6 +412,20 @@ type TemplateType = "html" | "node" | "angular-cli" | "create-react-app" | "java
 
 ```
 
+### `downloadAsZip`
+Display a button for downloading the current lesson as `.zip` file. Defaults to `false`.
+The default filename is constructed by concatenating folder names of part,  chapter and lesson.
+<PropertyTable inherited type="DownloadAsZip" />
+
+The `DownloadAsZip` type has the following shape:
+
+```ts
+type DownloadAsZip =
+    | boolean
+    | { filename?: string }
+
+```
+
 ##### `meta`
 
 Configures `<meta>` tags for Open Graph protocole and Twitter.

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

@@ -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-part.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/configs/lessons-in-root.ts

@@ -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"
   },
@@ -30,6 +34,7 @@
     "playwright": "^1.46.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "unocss": "^0.59.4"
+    "unocss": "^0.59.4",
+    "unzipper": "^0.12.3"
   }
 }

e2e/package.json

@@ -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/playwright.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/config.ts

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

e2e/src-custom/lessons-in-part/content/tutorial/meta.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-1/content.md

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