feat(docs): add multi-file code samples documentation (#93)

* chore(deps): update pnpm workspace dependencies to ^0.41.7

* feat(docs): add multi-file code samples documentation and improve code block examples

---------

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

Author: Adammatthiesen

docs/astro.config.mts

@@ -187,6 +187,10 @@ export default defineConfig({
 							label: "Code Cutting",
 							link: "usage/code-cutting",
 						},
+						{
+							label: "Multi-file Code Samples",
+							link: "usage/multi-file",
+						},
 						{
 							label: "Overriding Compiler Options",
 							link: "usage/ts-compiler-flags",

docs/src/content/docs/usage/multi-file.mdx

@@ -0,0 +1,77 @@
+---
+title: Multi-file code samples
+sidebar:
+  order: 2
+---
+
+import { TabItem, Tabs } from "@astrojs/starlight/components";
+
+Twoslash supports multi-file code samples. This is done by using the `@filename` directive which tells Twoslash to create a new file with the given name and put the following code in that file until the next `@filename` directive or the end of the code sample.
+
+## Simple multi-file code sample
+
+<Tabs>
+<TabItem label="Rendered Output">
+
+```ts twoslash
+// @filename: a.ts
+export const helloWorld: string = 'Hi';
+
+// @filename: b.ts
+import { helloWorld } from './a';
+
+console.log(helloWorld);
+```
+
+</TabItem>
+<TabItem label="Markdown">
+
+``````md
+```ts twoslash
+// @filename: a.ts
+export const helloWorld: string = 'Hi';
+
+// @filename: b.ts
+import { helloWorld } from './a';
+
+console.log(helloWorld);
+```
+``````
+
+</TabItem>
+</Tabs>
+
+## Multi-file code sample with hidden files
+
+Taking the above example, we can hide the contents of `a.ts` by using the `---cut---` directive. This is useful for showing only the relevant code to the reader while still having the full code sample available for Twoslash to compile and run.
+
+<Tabs>
+<TabItem label="Rendered Output">
+
+```ts twoslash
+// @filename: a.ts
+export const helloWorld: string = 'Hi'
+// ---cut---
+// @filename: b.ts
+import { helloWorld } from './a'
+
+console.log(helloWorld)
+```
+
+</TabItem>
+<TabItem label="Markdown">
+
+``````md
+```ts twoslash
+// @filename: a.ts
+export const helloWorld: string = 'Hi'
+// ---cut---
+// @filename: b.ts
+import { helloWorld } from './a'
+
+console.log(helloWorld)
+```
+``````
+
+</TabItem>
+</Tabs>

docs/src/content/docs/usage/show-emitted-files.mdx

@@ -43,7 +43,7 @@ While the `.js` file is probably the most useful file out of the box, TypeScript
 <Tabs>
 <TabItem label="Rendered Output">
 
-```ts twoslash title="index.d.ts"
+```ts twoslash
 // @declaration
 // @showEmit
 // @showEmittedFile: index.d.ts
@@ -54,7 +54,7 @@ export const hello = 'world'
 <TabItem label="Markdown">
 
 ``````md
-```ts twoslash title="index.d.ts"
+```ts twoslash
 // @declaration
 // @showEmit
 // @showEmittedFile: index.d.ts
@@ -70,7 +70,7 @@ export const hello = 'world'
 <Tabs>
 <TabItem label="Rendered Output">
 
-```ts twoslash title="index.js.map"
+```ts twoslash
 // @sourceMap
 // @showEmit
 // @showEmittedFile: index.js.map
@@ -81,7 +81,7 @@ export const hello = 'world'
 <TabItem label="Markdown">
 
 ``````md
-```ts twoslash title="index.js.map"
+```ts twoslash
 // @sourceMap
 // @showEmit
 // @showEmittedFile: index.js.map
@@ -97,7 +97,7 @@ export const hello = 'world'
 <Tabs>
 <TabItem label="Rendered Output">
 
-```ts twoslash title="index.d.ts.map"
+```ts twoslash
 // @declaration
 // @declarationMap
 // @showEmit
@@ -109,7 +109,7 @@ export const hello: string = 'world'
 <TabItem label="Markdown">
 
 ``````md
-```ts twoslash title="index.d.ts.map"
+```ts twoslash
 // @declaration
 // @declarationMap
 // @showEmit
@@ -123,19 +123,23 @@ export const hello: string = 'world'
 
 ### Multi-file code samples
 
+<Aside variant="warning">
+When using `@showEmittedFile` in a multi-file code sample, you need to make sure that you also add a title to your code block. This is due to a limitation in the way Twoslash handles multi-file code samples. Without a title, the emitted code will be incorrectly displayed.
+</Aside>
+
 <Tabs>
 <TabItem label="Rendered Output">
 
 ```ts twoslash title="b.js"
 // @showEmit
 // @showEmittedFile: b.js
 // @filename: a.ts
-export const helloWorld: string = 'Hi';
+export const helloWorld: string = 'Hi'
 
 // @filename: b.ts
-import { helloWorld } from './a';
+import { helloWorld } from './a.js'
 
-console.log(helloWorld);
+console.log(helloWorld)
 ```
 
 </TabItem>
@@ -146,12 +150,12 @@ console.log(helloWorld);
 // @showEmit
 // @showEmittedFile: b.js
 // @filename: a.ts
-export const helloWorld: string = 'Hi';
+export const helloWorld: string = 'Hi'
 
 // @filename: b.ts
-import { helloWorld } from './a';
+import { helloWorld } from './a.js'
 
-console.log(helloWorld);
+console.log(helloWorld)
 ```
 ``````
 

pnpm-lock.yaml

@@ -15,8 +15,8 @@ catalogs:
     mdast-util-gfm: ^3.1.0
     mdast-util-to-hast: ^13.2.1
   min:
-    "@expressive-code/core": ^0.41.6
-    expressive-code: ^0.41.6
+    "@expressive-code/core": ^0.41.7
+    expressive-code: ^0.41.7
     typescript: ^5.5.0
   twoslash:
     "@vue/language-core": ^3.2.5