feat: provide a description for every property.

Author: Nemikolh

extensions/vscode/src/language-server/index.ts

@@ -10,8 +10,6 @@ const server = createServer(connection);
 connection.listen();
 
 connection.onInitialize((params) => {
-  connection.console.debug('CONNECTED' + params.capabilities);
-
   const yamlService = createYamlService({
     getLanguageSettings(_context) {
       const schema = readSchema();
@@ -25,7 +23,7 @@ connection.onInitialize((params) => {
         isKubernetes: false,
         schemas: [
           {
-            uri: 'https://tutorialkit.dev/schema.json',
+            uri: 'https://tutorialkit.dev/reference/configuration/',
             schema,
             fileMatch: [
               '**/*',

packages/types/src/schemas/chapter.ts

@@ -3,7 +3,12 @@ import { baseSchema } from './common.js';
 
 export const chapterSchema = baseSchema.extend({
   type: z.literal('chapter'),
-  lessons: z.array(z.string()).optional(),
+  lessons: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'The list of lessons in this chapter. The order in this array defines the order of the lessons. If not specified a folder-based numbering system is used instead.',
+    ),
 });
 
 export type ChapterSchema = z.infer<typeof chapterSchema>;

packages/types/src/schemas/common.ts

@@ -9,16 +9,21 @@ export const commandSchema = z.union([
   z.tuple([z.string(), z.string()]),
 
   z.strictObject({
-    command: z.string(),
-    title: z.string(),
+    command: z.string().describe('Command to execute in WebContainer.'),
+    title: z.string().describe('Title to show for this step in the Prepare Environment section.'),
   }),
 ]);
 
 export type CommandSchema = z.infer<typeof commandSchema>;
 
 export const commandsSchema = z.object({
-  mainCommand: commandSchema.optional(),
-  prepareCommands: commandSchema.array().optional(),
+  mainCommand: commandSchema.optional().describe('The last command to be executed. Typically a dev server.'),
+  prepareCommands: commandSchema
+    .array()
+    .optional()
+    .describe(
+      'List of commands to be executed to prepare the environment in WebContainer. Each command executed and its status will be shown in the Prepare Environment section.',
+    ),
 });
 
 export type CommandsSchema = z.infer<typeof commandsSchema>;
@@ -36,16 +41,28 @@ export const previewSchema = z.union([
       z.tuple([z.number(), z.string()]),
 
       z.strictObject({
-        port: z.number(),
-        title: z.string(),
+        port: z.number().describe('Port number of the preview.'),
+        title: z.string().describe('Title of the preview.'),
       }),
     ])
     .array(),
 ]);
 
 export type PreviewSchema = z.infer<typeof previewSchema>;
 
-const panelType = z.union([z.literal('output'), z.literal('terminal')]);
+const panelTypeSchema = z
+  .union([z.literal('output'), z.literal('terminal')])
+  .describe(`The type of the terminal which can either be 'output' or 'terminal'.`);
+
+const allowRedirectsSchema = z
+  .boolean()
+  .optional()
+  .describe('`true` if you want to enable output redirects in the terminal, disabled by default.');
+
+const allowCommandsSchema = z
+  .array(z.string())
+  .optional()
+  .describe('List of command that are allowed in the terminal, if not provided, all commands are allowed.');
 
 export const terminalSchema = z.union([
   // `false` if you want to disable the terminal entirely
@@ -67,12 +84,12 @@ export const terminalSchema = z.union([
         .array(
           z.union([
             // the type of the panel
-            panelType,
+            panelTypeSchema,
 
             // or a tuple with the type and the title of the panel
             z.tuple([
               // the type of the panel
-              panelType,
+              panelTypeSchema,
 
               // the title of the panel which is shown in the tab
               z.string(),
@@ -81,19 +98,24 @@ export const terminalSchema = z.union([
             // or an object defining the panel
             z.strictObject({
               // the type of the panel
-              type: panelType,
+              type: panelTypeSchema,
 
               // an id linking the terminal of multiple lessons together
-              id: z.string().optional(),
+              id: z
+                .string()
+                .optional()
+                .describe(
+                  'An id linking the terminal of multiple lessons together so that its state is preserved between lessons.',
+                ),
 
               // the title of the panel which is shown in the tab
-              title: z.string().optional(),
+              title: z.string().optional().describe('The title of the panel which is shown in the tab.'),
 
               // `true` if you want to enable output redirects in the terminal, disabled by default
-              allowRedirects: z.boolean().optional(),
+              allowRedirects: allowRedirectsSchema,
 
               // list of command that are allowed in the terminal, if not provided, all commands are allowed
-              allowCommands: z.array(z.string()).optional(),
+              allowCommands: allowCommandsSchema,
             }),
           ]),
         )
@@ -122,35 +144,62 @@ export const terminalSchema = z.union([
           },
         ),
     ]),
-    activePanel: z.number().gte(0).optional(),
+    activePanel: z.number().gte(0).optional().describe('Defines which panel should be visible by default.'),
 
     // `true` if you want to enable output redirects in the terminal, disabled by default
-    allowRedirects: z.boolean().optional(),
+    allowRedirects: allowRedirectsSchema,
 
     // list of command that are allowed in the terminal, if not provided, all commands are allowed
-    allowCommands: z.array(z.string()).optional(),
+    allowCommands: allowCommandsSchema,
   }),
 ]);
 
-export type TerminalPanelType = z.infer<typeof panelType>;
+export type TerminalPanelType = z.infer<typeof panelTypeSchema>;
 export type TerminalSchema = z.infer<typeof terminalSchema>;
 
 export const webcontainerSchema = commandsSchema.extend({
-  previews: previewSchema.optional(),
-  autoReload: z.boolean().optional(),
-  template: z.string().optional(),
-  terminal: terminalSchema.optional(),
-  focus: z.string().optional(),
-  editor: z.union([
-    // can either be completely removed by setting it to `false`
-    z.boolean().optional(),
-
-    // or you can only remove the file tree
-    z.strictObject({
-      fileTree: z.boolean().optional(),
-    }),
-  ]),
-  i18n: i18nSchema.optional(),
+  previews: previewSchema
+    .optional()
+    .describe(
+      '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.',
+    ),
+  autoReload: z
+    .boolean()
+    .optional()
+    .describe(
+      'Navigating to a lesson that specifies autoReload will always reload the preview. This is typically only needed if your server does not support HMR.',
+    ),
+  template: z
+    .string()
+    .optional()
+    .describe(
+      'Specified which folder from the src/templates/ directory should be used as the basis for the code. See the “Code templates” guide for a detailed explainer.',
+    ),
+  terminal: terminalSchema
+    .optional()
+    .describe(
+      'Configures one or more terminals. TutorialKit provides two types of terminals: read-only, called output, and interactive, called terminal.',
+    ),
+  focus: z
+    .string()
+    .optional()
+    .describe('Defines which file should be opened in the code editor by default when lesson loads.'),
+  editor: z
+    .union([
+      // can either be completely removed by setting it to `false`
+      z.boolean().optional(),
+
+      // or you can only remove the file tree
+      z.strictObject({
+        fileTree: z.boolean().optional(),
+      }),
+    ])
+    .describe(
+      'Configure whether or not the editor should be rendered. If an object is provided with fileTree: false, only the file tree is hidden.',
+    ),
+  i18n: i18nSchema
+    .optional()
+    .describe('Lets you define alternative texts used in the UI. This is useful for localization.'),
   editPageLink: z
     .union([
       // pattern for creating the URL
@@ -159,12 +208,20 @@ export const webcontainerSchema = commandsSchema.extend({
       // `false` for disabling the edit link
       z.boolean(),
     ])
-    .optional(),
+    .optional()
+    .describe(
+      'Display a link in lesson for editing the page content. The value is a URL pattern where ${path} is replaced with the lesson’s location relative to src/content/tutorial.',
+    ),
 });
 
 export const baseSchema = webcontainerSchema.extend({
-  title: z.string(),
-  slug: z.string().optional(),
+  title: z.string().describe('The title of the part, chapter, or lesson.'),
+  slug: z
+    .string()
+    .optional()
+    .describe(
+      'Customize the URL segment of this part / chapter or lesson. The full URL path is /:partSlug/:chapterSlug/:lessonSlug.',
+    ),
 });
 
 export type BaseSchema = z.infer<typeof baseSchema>;

packages/types/src/schemas/i18n.ts

@@ -6,64 +6,69 @@ export const i18nSchema = z.object({
    *
    * @default 'Part ${index}: ${title}'
    */
-  partTemplate: z.string().optional(),
+  partTemplate: z.string().optional().describe('Template on how to format a part. Variables: ${index} and ${title}.'),
 
   /**
    * Text of the edit page link.
    *
    * @default 'Edit this page'
    */
-  editPageText: z.string().optional(),
+  editPageText: z.string().optional().describe('Text of the edit page link.'),
 
   /**
    * Text shown when there are no previews or steps to show in the prepare environment section.
    *
    * @default 'Start WebContainer'
    */
-  startWebContainerText: z.string().optional(),
+  startWebContainerText: z
+    .string()
+    .optional()
+    .describe('Text shown when there are no previews or steps to show in the prepare environment section.'),
 
   /**
-   * Text shown on the call to action button to start webcontainer when boot was blocked
-   * due to memory restrictions.
+   * Text shown in the preview section when there are no steps to run and no preview to show.
    *
    * @default 'No preview to run nor steps to show'
    */
-  noPreviewNorStepsText: z.string().optional(),
+  noPreviewNorStepsText: z
+    .string()
+    .optional()
+    .describe('Text shown in the preview section when there are no steps to run and no preview to show.'),
 
   /**
    * Text shown on top of the file tree.
    *
    * @default 'Files'
    */
-  filesTitleText: z.string().optional(),
+  filesTitleText: z.string().optional().describe('Text shown on top of the file tree.'),
 
   /**
    * Text shown on top of the steps section.
    *
    * @default 'Preparing Environment'
    */
-  prepareEnvironmentTitleText: z.string().optional(),
+  prepareEnvironmentTitleText: z.string().optional().describe('Text shown on top of the steps section.'),
 
   /**
    * Text shown for the toggle terminal button.
    *
    * @default 'Toggle Terminal'
    */
-  toggleTerminalButtonText: z.string().optional(),
+  toggleTerminalButtonText: z.string().optional().describe('Text shown for the toggle terminal button.'),
 
   /**
    * Text shown for the solve button.
    *
    * @default 'Solve'
    */
-  solveButtonText: z.string().optional(),
+  solveButtonText: z.string().optional().describe('Text shown for the solve button.'),
 
   /**
    * Text shown for the reset button.
    *
    * @default 'Reset'
    */
-  resetButtonText: z.string().optional(),
+  resetButtonText: z.string().optional().describe('Text shown for the reset button.'),
 });
 
 export type I18nSchema = z.infer<typeof i18nSchema>;

packages/types/src/schemas/lesson.ts

@@ -3,8 +3,11 @@ import { baseSchema } from './common.js';
 
 export const lessonSchema = baseSchema.extend({
   type: z.literal('lesson'),
-  scope: z.string().optional(),
-  hideRoot: z.boolean().optional(),
+  scope: z.string().optional().describe('A prefix that all file paths must match to be visible in the file tree.'),
+  hideRoot: z
+    .boolean()
+    .optional()
+    .describe('If set to false, `/` is shown at the top of the file tree. Defaults to true.'),
 });
 
 export type LessonSchema = z.infer<typeof lessonSchema>;

packages/types/src/schemas/part.ts

@@ -3,7 +3,12 @@ import { baseSchema } from './common.js';
 
 export const partSchema = baseSchema.extend({
   type: z.literal('part'),
-  chapters: z.array(z.string()).optional(),
+  chapters: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'The list of chapters in this part. The order in this array defines the order of the chapters. If not specified a folder-based numbering system is used instead.',
+    ),
 });
 
 export type PartSchema = z.infer<typeof partSchema>;

packages/types/src/schemas/tutorial.ts

@@ -4,7 +4,12 @@ import { webcontainerSchema } from './common.js';
 export const tutorialSchema = webcontainerSchema.extend({
   type: z.literal('tutorial'),
   logoLink: z.string().optional(),
-  parts: z.array(z.string()).optional(),
+  parts: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'The list of parts in this tutorial. The order in this array defines the order of the parts. If not specified a folder-based numbering system is used instead.',
+    ),
 });
 
 export type TutorialSchema = z.infer<typeof tutorialSchema>;