Merge branch 'main' into ronith/hide-toggle-terminal-button

Author: AriPerkkio

.github/workflows/integration-test-cli.yaml

@@ -3,20 +3,44 @@ name: CLI Integration Tests
 on:
   pull_request:
   workflow_dispatch:
+  push:
+    branches:
+      - main
 
 jobs:
-  cli-integration-test:
+  skip:
     name: CLI Integration Tests
-    # Note: `prepare-release.yaml` sets this commit message
-    if: ${{ contains(github.event.pull_request.title, 'release CLI') || github.event_name == 'workflow_dispatch' }}
     runs-on: ubuntu-latest
+    steps:
+      - name: skip
+        run: echo skip
+
+  cli-integration-test:
+    name: CLI Integration Test Matrix
+    # Note: `prepare-release.yaml` sets this commit message
+    if: ${{ contains(github.event.pull_request.title, 'release CLI') || github.event_name == 'workflow_dispatch' || github.event_name == 'push' }}
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        node-version: [18, 20, 22]
+        include:
+          - os: macos-latest
+            node_version: 20
+          - os: windows-latest
+            node_version: 20.13.1
+
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
       - uses: ./.github/actions/setup-and-build
+        with:
+          node-version: ${{ matrix.node-version }}
 
       - name: Update template's versions
         working-directory: ./packages/cli

CHANGELOG.md

@@ -1,3 +1,30 @@
+## [1.1.1](https://github.com/stackblitz/tutorialkit/compare/1.1.0...1.1.1) (2024-10-20)
+
+
+### Bug Fixes
+
+* **theme:** apply `fast-glob` Windows work-around for all `\@` matches ([#383](https://github.com/stackblitz/tutorialkit/issues/383)) ([9f4bd13](https://github.com/stackblitz/tutorialkit/commit/9f4bd13270f877b9f52e6b85eca5693c283ee249))
+
+
+
+# [1.1.0](https://github.com/stackblitz/tutorialkit/compare/1.0.0...1.1.0) (2024-10-18)
+
+
+### Bug Fixes
+
+* **astro:** correct error message when chapter not found ([#361](https://github.com/stackblitz/tutorialkit/issues/361)) ([0510474](https://github.com/stackblitz/tutorialkit/commit/05104741a73180dbaeb583317cd77df104d2d2c7))
+* **astro:** types of override components to optional ([#376](https://github.com/stackblitz/tutorialkit/issues/376)) ([0af3848](https://github.com/stackblitz/tutorialkit/commit/0af384889f5a3e7e46ea4803b1b1a631c15d331f))
+* **cli:** list `eject` command in `--help` ([#373](https://github.com/stackblitz/tutorialkit/issues/373)) ([bc61229](https://github.com/stackblitz/tutorialkit/commit/bc61229f156db3043b57dd3f85f09b72702a70b0))
+
+
+### Features
+
+* add file extension based icons ([#369](https://github.com/stackblitz/tutorialkit/issues/369)) ([ff39cdc](https://github.com/stackblitz/tutorialkit/commit/ff39cdc258764c8d4d1bebe2dce2795fe10e1870))
+* **astro:** add `custom` configuration option for passing custom fields ([#378](https://github.com/stackblitz/tutorialkit/issues/378)) ([7c6ede9](https://github.com/stackblitz/tutorialkit/commit/7c6ede95730150b68be763d4c87f1da1bc42503c))
+* **astro:** override components to support `HeadTags` ([#375](https://github.com/stackblitz/tutorialkit/issues/375)) ([e93d11a](https://github.com/stackblitz/tutorialkit/commit/e93d11a11b8a01dc6de859842b0dc675b01008de))
+
+
+
 # [1.0.0](https://github.com/stackblitz/tutorialkit/compare/0.2.3...1.0.0) (2024-10-01)
 
 

docs/demo/src/content/tutorial/1-forms-css/2-colors/1-accent-color/content.md

@@ -9,7 +9,7 @@ slug: accent-color
 
 <img src="/images/accent-color.png" class="h-20 m-auto">
 
-In the Preview window, we've displayed several native elements: different `input` types and a `progress` bar. Depending on your operating system settings, these will have a different defalut colors.
+In the Preview window, we've displayed several native elements: different `input` types and a `progress` bar. Depending on your operating system settings, these will have a different default colors.
 
 Such colors might not fit your brand, or the current theme of your application.
 

docs/demo/src/content/tutorial/1-forms-css/3-fieldset/6-the-end/content.md

@@ -6,6 +6,6 @@ focus: /style.css
 ---
 You've reached the end of this tutorial! We hope you've enjoyed it and learned something new about working with CSS and forms.
 
-This app was built using the TutorialKit framework and you can make a similiar learning resource for your team or open-source community yourself! TutorialKit provides all the necessary tooling, and UI out of the box, so that you can focus on the content.
+This app was built using the TutorialKit framework and you can make a similar learning resource for your team or open-source community yourself! TutorialKit provides all the necessary tooling, and UI out of the box, so that you can focus on the content.
 
 To learn more, visit <a href="https://tutorialkit.dev">tutorialkit.dev</a>.

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

@@ -144,3 +144,105 @@ src/templates
     │   # Overrides "index.js" from "shared-template"
     └── index.js
 ```
+
+## Markdown and MDX Support
+
+TutorialKit comes with built-in support for both Markdown and MDX, powered by Astro. This means you can leverage all Markdown and MDX features when creating lesson content. To explore the full capabilities, check out Astro's [Markdown support](https://docs.astro.build/en/guides/markdown-content/) and [MDX support](https://docs.astro.build/en/guides/integrations-guide/mdx/) documentation for more details.
+
+### Callouts
+
+Callouts are visual elements designed to highlight specific information or provide additional context within a document or user interface. They are ideal for drawing attention to important tips, warnings, and other key messages.
+
+You can create callouts using the following types: `tip`, `info`, `warn`, `danger` and `success`.
+
+```
+:::info
+Some info with some markdown `syntax` and a [`link`](https://tutorialkit.dev/).
+
+Here's a normal [link](https://tutorialkit.dev/).
+:::
+```
+
+![Content](../reference/images/theming-callout.png)
+
+To customize the styles of a callout, check out the [theming reference](/reference/theming/#callouts).
+
+
+### Code blocks
+
+TutorialKit offers a comprehensive set of code block features powered by Expressive Code. It includes all core features, along with optional plugins like collapsible sections and line numbers. For a full overview, check out the [Expressive Code documentation](https://expressive-code.com/).
+
+````md title="content.md"
+```js title="code.js" ins={4} del={5} {6} "greeting"
+const greeting = 'Hello, World!';
+
+// This is a comment
+const added = 'This line was added';
+const removed = 'This line was removed';
+const highlighted = 'This line is highlighted';
+```
+````
+
+```js title="code.js" ins={4} del={5} {6} "greeting"
+const greeting = 'Hello, World!';
+
+// This is a comment
+const added = 'This line was added';
+const removed = 'This line was removed';
+const highlighted = 'This line is highlighted';
+```
+
+#### Useful Expressive Code Attributes
+
+- **`title`** - Sets the title of the code block.
+- **`frame`** - Defines the frame of the code block. Options: `"code"`, `"terminal"`, `"none"`, `"auto"`.
+- **`showLineNumbers`** - Displays line numbers. You can combine this with `startLineNumber=#` to begin numbering from a specific line.
+- **`wrap`** - Controls word wrapping. Use `preserveIndent` and `preserveIndent=false` to adjust indentation handling.
+
+##### Marking Lines
+
+- **`{x}`** - Marks specific lines. For example, `{6,10-18}` will mark lines 6 and 10 through 18.
+- **`ins`** - Marks inserted lines. Example: `ins={6,10-18}`.
+- **`del`** - Marks deleted lines. Example: `del={6,10-18}`.
+- **`{"Label":x}`** - Assigns a label to a line or range of lines. Works with `mark`, `ins`, and `del`. Example: `{"Label1":5} del={"Label2":7-8} ins={"Label3":10-12}`. If the label is long, consider placing an empty line in the code for better readability.
+- **`collapse={X-Y}`** - Collapses the specified lines. Example: `collapse={1-5,12-14}`.
+
+##### Marking Text
+
+You can highlight text using strings or regular expressions. For example:
+
+````md
+```jsx "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]/
+console.log(
+  'Hello, the words yes and yep will be marked. Also add1, add2, remove1, remove2',
+)
+```
+
+#### Importing files
+
+In addition to Expressive Code features, you can import files from your code template `_files` and `_solution` folders using the file or solution shortcodes. These shortcodes insert the content of the specified file directly into your lesson content.
+
+- `file` shortcode is used to reference files from the lesson `_files` or code template folder.
+- `solution` shortcode is used to reference files from the lesson `_solution` folder.
+
+For example, the following code will insert the content of the `box.css` file from the `_files` folder:
+
+````md "file"
+```file:/box.css
+```
+````
+
+```css
+.box {
+  width: 100px;
+  height: 100px;
+  background-color: red;
+}
+```

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

@@ -89,4 +89,22 @@ interface Props {
   /** Content of the dialog */
   children: ReactNode;
 }
+```
+
+### HeadTags
+
+Component for overriding title, links and metadata in the `<head>` tag.
+
+When overriding `HeadTags` you can place TutorialKit's default components using following [Astro slots](https://docs.astro.build/en/basics/astro-components/#named-slots):
+
+- `title`: The page title
+- `links`: Links for the favicon, fonts and other assets
+- `meta`:  Metadata and Open Graph tags
+
+```jsx title="src/components/CustomHeadLinks.astro"
+<slot name="title" />
+<slot name="links" />
+<slot name="meta" />
+{/** Add your own tags */}
+<link rel="sitemap" href="/sitemap-index.xml" />
 ```

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

@@ -221,8 +221,8 @@ editor: # Editor is visible
 
 ##### `previews`
 Configure which ports should be used for the previews allowing you to align the behavior with your demo application's dev server setup. If not specified, the lowest port will be used.
-
-<PropertyTable inherited type={'Preview[]'} />
+Optionally you can hide the preview by providing `previews: false`.
+<PropertyTable inherited type={'Preview[] | false'} />
 
 The `Preview` type has the following shape:
 
@@ -246,6 +246,9 @@ previews:
   - [3003, "Dev Server", "/docs"] # Preview is on :3003/docs/. Displayed title is "Dev Server".
   - { port: 3004, title: "Dev Server" } # Preview is on :3004/. Displayed title is "Dev Server".
   - { port: 3005, title: "Dev Server", pathname: "/docs" } # Preview is on :3005/docs/. Displayed title is "Dev Server".
+
+previews: false # Do not show preview panel
+
 ```
 
 ##### `mainCommand`
@@ -403,3 +406,99 @@ type OpenInStackBlitz =
 type TemplateType = "html" | "node" | "angular-cli" | "create-react-app" | "javascript" | "polymer" | "typescript" | "vue"
 
 ```
+
+##### `meta`
+
+Configures `<meta>` tags for Open Graph protocole and Twitter.
+TutorialKit will use your logo as the default image.
+<PropertyTable inherited type="MetaTagsSchema" />
+
+The `MetaTagsSchema` type has the following shape:
+
+```ts
+type MetaTagsSchema = {
+  image?: string;
+  description?: string;
+  title?: string;
+}
+
+```
+
+Example value:
+```yaml
+meta:
+  image: /cover.png
+  title: Title shown on social media and search engines
+  description: Description shown on social media and search engines
+```
+
+:::tip
+If your logo uses the SVG format, it may not display on most social platforms.
+Use a raster format instead, such as WEBP or PNG.
+:::
+
+##### `custom`
+
+Assign custom fields to a chapter/part/lesson.
+<PropertyTable inherited type="Record<string,any>" />
+
+This is useful when you want to consume items for the default `tutorial` collection
+in order to implement custom features.
+
+```yaml
+custom:
+  publishedAt: 2024-16-10
+  tags: tutorialkit,astro,vite
+```
+
+```ts
+import { getCollection } from 'astro:content';
+const collection = await getCollection('tutorial');
+for (const entry of collection) {
+  console.log("This part was published at:", entry.data?.custom?.publishedAt)
+}
+```
+
+## Configure the Tutorialkit Astro integration
+
+`@tutorialkit/astro` is an integration for Astro. You can configure the integration in your `astro.config.ts` file.
+
+```ts "tutorialkit()" title="astro.config.ts"
+import tutorialkit from "@tutorialkit/astro";
+import { defineConfig } from "astro/config";
+
+export default defineConfig({
+  devToolbar: {
+    enabled: false,
+  },
+  integrations: [
+    tutorialkit(),
+  ],
+});
+```
+
+You can pass the following options to the `tutorialkit` integration:
+
+### `components`
+
+**type**: `OverrideComponentsOptions`
+
+Provide the path to the components you want to override.
+
+```ts
+tutorialkit({
+  components: {
+    TopBar: './src/components/CustomTopBar.astro',
+  },
+});
+```
+
+See [Overriding Components](/guides/overriding-components/) for details of all the components that you can override.
+
+### `defaultRoutes`
+
+**type**: `boolean | "tutorial-only"`<br/>
+**default**: `true`
+
+Controls whether the tutorial routes are automatically added to your project. When set to `true`, it additionally adds a redirect from `/` to the first tutorial.
+Use `"tutorial-only"` to only add the tutorial routes without the redirect.

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

@@ -77,22 +77,10 @@ The content refers to the main part of the lesson that contains the text and ima
 
 ### Callouts
 
-Callouts are visual elements used to draw attention to specific information or provide additional context within a document or user interface. They are typically used to highlight important tips, warnings, or other types of messages.
-
-For instanceof, here's an example of an info callout.
+Customize the appearance of each callout type by adjusting its specific style tokens. Each callout includes tokens for elements such as text color, title color, icon color, background, code snippet color, and border color.
 
 ![Content](./images/theming-callout.png)
 
-Callouts are created like this:
-
-```
-:::tip
-This is a tip
-:::
-```
-
-Valid callout names are `tip`, `info`, `warn` and `danger`.
-
 #### Tip
 
 | Token                                            | Description                                                 |

e2e/configs/override-components.ts

@@ -10,6 +10,7 @@ export default defineConfig({
       components: {
         Dialog: './src/components/Dialog.tsx',
         TopBar: './src/components/TopBar.astro',
+        HeadTags: './src/components/CustomHeadTags.astro',
       },
     }),
   ],

e2e/src/components/CustomHeadTags.astro

@@ -0,0 +1,5 @@
+<slot name="title" />
+<slot name="links" />
+<slot name="meta" />
+<meta name="e2e-test-custom-meta-tag" content="custom-content" />
+<link rel="sitemap" href="/sitemap-index.xml" />