feat: enhance documentation and configuration options for EC-Twoslash

.vscode/settings.json

@@ -51,7 +51,9 @@
 		"twocustom",
 		"twoerror",
 		"twoslash",
+		"Twoslash",
 		"Twoslasher",
+		"Twoslashers",
 		"UIDOM",
 		"withstudiocms"
 	]

biome.json

@@ -34,5 +34,22 @@
 				"organizeImports": "on"
 			}
 		}
-	}
+	},
+	"overrides": [
+		{
+			"includes": ["**/*.astro"],
+			"linter": {
+				"rules": {
+					"correctness": {
+						"noUnusedImports": "off",
+						"noUnusedVariables": "off"
+					},
+					"style": {
+						"useConst": "off",
+						"useImportType": "off"
+					}
+				}
+			}
+		}
+	]
 }

docs/astro.config.mts

@@ -23,6 +23,9 @@ export default defineConfig({
 				alt: "EC Twoslash Logo",
 			},
 			credits: true,
+			components: {
+				PageTitle: "./src/components/starlight/PageTitle.astro",
+			},
 			social: [
 				{
 					label: "GitHub",
@@ -161,6 +164,10 @@ export default defineConfig({
 					label: "Getting Started",
 					autogenerate: { directory: "getting-started" },
 				},
+				{
+					label: "Available Twoslashers",
+					autogenerate: { directory: "twoslashers" },
+				},
 				{
 					label: "Usage",
 					items: [
@@ -190,6 +197,10 @@ export default defineConfig({
 						},
 					],
 				},
+				{
+					label: "Reference",
+					autogenerate: { directory: "reference" },
+				},
 			],
 		}),
 	],

docs/src/components/PropertySignature.astro

@@ -0,0 +1,31 @@
+---
+const body = (await Astro.slots.render("default")).trim();
+const signature = body.match(/^<ul>\s*<li>\s*([\s\S]*?)\s*<\/li>\s*<\/ul>/)?.[1] ?? "";
+const signatureParts = signature.split(/<\/li>\s*<li>/);
+const extractSignaturePart = (name: string) => {
+	name = `${name}: `;
+	const idx = signatureParts.findIndex((part) => part.startsWith(name));
+	if (idx === -1) return;
+	const part = (signatureParts[idx] ?? "").replace(name, "").trim();
+	signatureParts.splice(idx, 1);
+	return part;
+};
+const propertyType = extractSignaturePart("Type");
+const defaultValue = extractSignaturePart("Default");
+const availability = extractSignaturePart("Availability");
+---
+
+<div class="property-signature not-content">
+	{propertyType && (
+		<span class="name">Type:</span>
+		<span class="value" set:html={propertyType} />
+	)}
+	{defaultValue && (
+		<span class="name">Default:</span>
+		<span class="value" set:html={defaultValue} />
+	)}
+	{availability && (
+		<span class="name">Availability:</span>
+		<span set:html={availability} />
+	)}
+</div>

docs/src/components/starlight/PageTitle.astro

@@ -0,0 +1,15 @@
+---
+import { Badge } from "@astrojs/starlight/components";
+import Default from "@astrojs/starlight/components/PageTitle.astro";
+
+const {
+	entry: { data },
+} = Astro.locals.starlightRoute;
+---
+{
+    (data.template === 'splash' && data.title === "404") 
+		? <slot/> 
+		: data.addedIn 
+            ? <Default><slot/></Default><Badge text={`Added in ${data.addedIn}`} variant="success" />
+            : <Default><slot/></Default>
+}

docs/src/content.config.ts

@@ -1,7 +1,17 @@
 import { defineCollection } from "astro:content";
 import { docsLoader } from "@astrojs/starlight/loaders";
 import { docsSchema } from "@astrojs/starlight/schema";
+import { z } from "astro/zod";
+
+const extendedDocsSchema = z.object({
+	addedIn: z.string().optional(),
+});
 
 export const collections = {
-	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+	docs: defineCollection({
+		loader: docsLoader(),
+		schema: docsSchema({
+			extend: extendedDocsSchema,
+		}),
+	}),
 };

docs/src/content/docs/getting-started/basic.mdx

@@ -21,7 +21,7 @@ Using the homepage as an example, here is a simple code sample:
 ```ts twoslash
 // @errors: 2540
 
-console.log((1 + 2 + 3 + 4).toFixed(2))
+console.log((1 + 2 + 3 + 4).toFixed(2));
 //                            ^|
 
 /** A Basic Todo interface*/
@@ -34,7 +34,7 @@ const todo: Readonly<Todo> = {
 //  ^?
 }
 
-todo.title = 'Hello'
+todo.title = 'Hello';
 ```
 
 ``````
@@ -46,7 +46,7 @@ todo.title = 'Hello'
 ```ts twoslash
 // @errors: 2540
 
-console.log((1 + 2 + 3 + 4).toFixed(2))
+console.log((1 + 2 + 3 + 4).toFixed(2));
 //                            ^|
 
 /** A Basic Todo interface*/
@@ -59,7 +59,7 @@ const todo: Readonly<Todo> = {
 //  ^?
 }
 
-todo.title = 'Hello'
+todo.title = 'Hello';
 ```
 
 </TabItem>

docs/src/content/docs/getting-started/installation.mdx

@@ -60,7 +60,7 @@ export default defineConfig({
 <TabItem label='ec.config.mjs'>
 
 ```ts twoslash ins={2, 5}
-import { defineEcConfig } from 'astro-expressive-code'
+import { defineEcConfig } from 'astro-expressive-code';
 import ecTwoSlash from "expressive-code-twoslash";
 
 export default defineEcConfig({
@@ -121,7 +121,7 @@ export default defineEcConfig({
 <TabItem label='Next.js'>
 
 ```ts twoslash title="next.config.mjs" ins={2, 6}
-import rehypeExpressiveCode from 'rehype-expressive-code'
+import rehypeExpressiveCode from 'rehype-expressive-code';
 import ecTwoSlash from "expressive-code-twoslash";
 
 /** @type {import('rehype-expressive-code').RehypeExpressiveCodeOptions} */
@@ -143,7 +143,7 @@ For more information on how to add to your Next.js config, see the [Expressive C
 Default config options shown.
 
 ```ts twoslash
-import { defineEcConfig } from 'astro-expressive-code'
+import { defineEcConfig } from 'astro-expressive-code';
 import ecTwoSlash from "expressive-code-twoslash";
 import ts from "typescript";
 

docs/src/content/docs/index.mdx

@@ -22,7 +22,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
 ```ts twoslash
 // @errors: 2540
 
-console.log((1 + 2 + 3 + 4).toFixed(2))
+console.log((1 + 2 + 3 + 4).toFixed(2));
 //                            ^|
 
 /** A Basic Todo interface*/
@@ -35,5 +35,5 @@ const todo: Readonly<Todo> = {
 //  ^?
 }
 
-todo.title = 'Hello'
+todo.title = 'Hello';
 ```

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

@@ -0,0 +1,156 @@
+---
+title: Configuring EC-Twoslash
+description: Learn how to configure Twoslash with Expressive Code.
+sidebar:
+  order: 1
+  label: Configuration
+---
+
+import { Aside } from '@astrojs/starlight/components';
+import PropertySignature from '../../../components/PropertySignature.astro';
+
+Expressive Code Twoslash (EC-Twoslash) is highly configurable, allowing you to tailor its behavior to fit your specific needs. This section provides an overview of the various configuration options available, including how to customize the appearance of code blocks, enable or disable specific features, and integrate with other tools.
+
+**Example Configuration:**
+
+```ts twoslash title="ec.config.mjs"
+import { defineEcConfig } from 'astro-expressive-code';
+import ecTwoSlash from "expressive-code-twoslash";
+
+export default defineEcConfig({
+  plugins: [ecTwoSlash()],
+});
+```
+
+<Aside>
+For all examples in this section, we will be using the `ec.config.mjs` file to demonstrate how to configure EC-Twoslash. For more information about this configuration file, see the [Expressive Code documentation](https://expressive-code.com/reference/configuration/).
+</Aside>
+
+## Configuration Options
+
+### explicitTrigger
+
+<PropertySignature>
+- Type: boolean | RegExp
+- Default: `true`
+</PropertySignature>
+
+The `explicitTrigger` option determines whether EC-Twoslash should only process code blocks that explicitly indicate they want to use Twoslash features. When set to `true`, EC-Twoslash will only apply its transformations to code blocks that include the `twoslash` directive in their metadata. If set to a `RegExp`, EC-Twoslash will apply its transformations to code blocks that match the provided regular expression in their metadata. If set to `false`, EC-Twoslash will apply its transformations to all code blocks that match the specified languages, regardless of their metadata. It is generally recommended to keep this option set to `true` to avoid unnecessary processing of code blocks that do not require Twoslash features.
+
+`````md /twoslash/
+```ts twoslash
+// This code block will only be processed if `explicitTrigger` 
+// is `true` or matches the provided RegExp.
+```
+`````
+
+#### Example
+
+```ts twoslash title="ec.config.mjs" {7}
+import { defineEcConfig } from 'astro-expressive-code';
+import ecTwoSlash from "expressive-code-twoslash";
+
+export default defineEcConfig({
+  plugins: [
+    ecTwoSlash({
+      explicitTrigger: /\btwoslash\b/, // Default trigger value
+    }),
+  ],
+});
+```
+
+### includeJsDoc
+
+<PropertySignature>
+- Type: boolean
+- Default: `true`
+</PropertySignature>
+
+The `includeJsDoc` option determines whether JSDoc comments should be included in the hover information provided by EC-Twoslash. When set to `true`, EC-Twoslash will include JSDoc comments in the hover popup, providing additional context and documentation for the code being hovered over. If set to `false`, JSDoc comments will be excluded from the hover information, resulting in a more concise hover popup that only includes type information and other relevant details.
+
+#### Example
+
+```ts twoslash title="ec.config.mjs" {7}
+import { defineEcConfig } from 'astro-expressive-code';
+import ecTwoSlash from "expressive-code-twoslash";
+
+export default defineEcConfig({
+  plugins: [
+    ecTwoSlash({
+      includeJsDoc: false, // Exclude JSDoc comments from hover information
+    }),
+  ],
+});
+```
+
+### allowNonStandardJsDocTags
+
+<PropertySignature>
+- Type: boolean
+- Default: `true`
+</PropertySignature>
+
+The `allowNonStandardJsDocTags` option determines whether non-standard JSDoc tags should be included in the hover information provided by EC-Twoslash. When set to `true`, EC-Twoslash will include non-standard JSDoc tags in the hover popup, allowing you to see custom documentation that may not be part of the standard JSDoc specification. If set to `false`, only standard JSDoc tags will be included in the hover information, resulting in a more streamlined hover popup that focuses on commonly used documentation tags.
+
+#### Example
+
+```ts twoslash title="ec.config.mjs" {7}
+import { defineEcConfig } from 'astro-expressive-code';
+import ecTwoSlash from "expressive-code-twoslash";
+
+export default defineEcConfig({
+  plugins: [
+    ecTwoSlash({
+      allowNonStandardJsDocTags: false, // Exclude non-standard JSDoc tags from hover information
+    }),
+  ],
+});
+```
+
+### languages
+
+<PropertySignature>
+- Type: `ReadonlyArray<string>`
+- Default: `["ts", "tsx", "vue"]`
+</PropertySignature>
+
+The `languages` option specifies the programming languages that EC-Twoslash should process. By default, EC-Twoslash is configured to process TypeScript (`ts`), TSX (`tsx`), and Vue (`vue`) code blocks. You can customize this list to include any languages that are supported by Twoslash, such as JavaScript (`js`), JavaScript React (`jsx`), or even custom languages that you have set up with Twoslash.
+
+#### Example
+
+```ts twoslash title="ec.config.mjs" {7}
+import { defineEcConfig } from 'astro-expressive-code';
+import ecTwoSlash from "expressive-code-twoslash";
+
+export default defineEcConfig({
+  plugins: [
+    ecTwoSlash({
+      languages: ["ts", "vue"], // Process TypeScript and Vue code blocks
+    }),
+  ],
+});
+```
+
+### twoslashOptions
+
+<PropertySignature>
+- Type: TwoslashOptions
+- Default: `{}`
+</PropertySignature>
+
+The `twoslashOptions` option allows you to forward additional options directly to the `twoslash` preprocessor. This is useful for customizing the behavior of Twoslash itself, such as enabling specific features, configuring how code is processed, or adjusting the output of Twoslash transformations. For a full list of available options that can be forwarded to Twoslash, see the [Twoslash documentation](https://twoslash.netlify.app/refs/options).
+
+```ts twoslash title="ec.config.mjs" {7-9}
+import { defineEcConfig } from 'astro-expressive-code';
+import ecTwoSlash from "expressive-code-twoslash";
+
+export default defineEcConfig({
+  plugins: [
+    ecTwoSlash({
+      twoslashOptions: {
+        // Twoslash options go here
+      },
+    }),
+  ],
+});
+```