Allow extensions to contribute getting started content

We want to allow extensions to contribute items to the welcome page's getting started section:

Using a package.json like this:

		"welcomeCategories": [
			{
				"id": "exampleProject",
				"title": "Turn Markdown into HTML",
				"description": "Use this sample project to learn how to convert Markdown to HTML!"
			}
		],
		"welcomeItems": {
			"exampleProject": [
				{
					"id": "md-to-html.openExample",
					"title": "Open an example folder",
					"description": "To start, try opening an example folder that has been preconfigured for this tutorial. This is optional, but helps for following along!",
					"button": {
						"title": "Open Example",
						"command": "md-to-html.openExample"
					},
					"media": {
						"path": "media/example-project.png",
						"altText": "example project"
					}
				},
				{
					"id": "md-to-html.showPreview",
					"title": "Preview your Markdown",
					"description": "Open a markdown file and click the \"Open Preview\" button at the top of the screen to see a preview of your file. This is technically optional, but it updates live and is helpful to check when creating your content!",
					"button": {
						"title": "Open Markdown File",
						"command": "md-to-html.openMarkdown"
					},
					"media": {
						"path": "media/preview.png",
						"altText": "preview"
					},
					"doneOn": {"command": "markdown.showPreviewToSide" } 
				},
				{
					"id": "md-to-html.convertToHTML",
					"title": "Create your .html file",
					"description": "To create the html file, run \"Convert Document to HTML\" from the editor actions context menu, behind the three dots top of the screen. This will create an .html file along side the markdown file.",
					"button": {
						"title": "Open Markdown File",
						"command": "md-to-html.openMarkdown"
					},
					"media": {
						"path": "media/convert-option.png",
						"altText": "showing editor actions context menu"
					},
					"doneOn": {"command": "md-to-html.convertToHTML" }
				},
				{
					"id": "md-to-html.openInBrowser",
					"title": "Open your .html file in the browser",
					"description": "Test that everything worked by opening the .html file in your browser. First open the html file in vscode, then right click in the editor and choose \"Open in Default Browser\".",
					"button": {
						"title": "Open HTML File",
						"command": "md-to-html.openHTML"
					},
					"media": {
						"path": "media/open-in-browser.png",
						"altText": "use editor context menu to open an .html file in your browser"
					},
					"doneOn": {"command": "extension.openInDefaultBrowser" }
				},
				{
					"id": "md-to-html.addKeybinding",
					"title": "Create a keyboard shortcut",
					"description": "That's all! You can share that single .html file with anyone without needing to bundle the images. To make this even easier in the future, consider adding a keybinding for the \"Convert Document to HTML\" command.",
					"button": {
						"title": "Add a keybinding",
						"command": "md-to-html.addKeybinding"
					},
					"media": {
						"path": "media/add-keybinding.png",
						"altText": "use the keybindings editor to add a keybinding for this command"
					}
				}
			]
		},

This is the change to the extension contributions interface:

export interface IExtensionContributions {
        .....
	welcomeItems?: { [category: string]: IWelcomeItem[] };
	welcomeCategories?: IWelcomeCategory[];
        .....
}

export interface IWelcomeItem {
	readonly id: string;
	readonly title: string;
	readonly description: string;
	readonly button: { title: string } & ({ command?: never, link: string } | { command: string, link?: never }),
	readonly media: { path: string | { hc: string, light: string, dark: string }, altText: string },
	readonly doneOn?:
	| { event: string; command?: never }
	| { event?: never; command: string };
	readonly when?: string;
}

export interface IWelcomeCategory {
	readonly id: string,
	readonly title: string;
	readonly description: string;
	readonly when?: string;
}

Update walkthrough contribution api to single object model

Updated based on feedback from API discussion:

Rather than a split categories/items contribution point, use a single large object
walkthroughs as top level contribution point (generalizable to getting started, tips&tricks, and troubleshooting), tasks for the individual items
Simplified image contribution - now just a single path
Removed eventFired doneOn mode, will add API to control programmatically in future revision

Interface:

export interface IWalkthroughTask {
	readonly id: string;
	readonly title: string;
	readonly description: string;
	readonly button:
	| { title: string, link: string, command?: never }
	| { title: string, command: string, link?: never },
	readonly media: { path: string, altText: string },
	readonly doneOn?: { command: string };
	readonly when?: string;
}

export interface IWalkthrough {
	readonly id: string,
	readonly title: string;
	readonly description: string;
	readonly tasks: IWalkthroughTask[];
	readonly primary?: boolean;
	readonly when?: string;
}

Example:

"walkthroughs": [ 
			{
				"id": "exampleProject",
				"title": "Turn Markdown into HTML",
				"description": "Use this sample project to learn how to convert Markdown to HTML!",
				"primary": true,
				"tasks": [
					{
						"id": "md-to-html.openExample",
						"title": "Open an example folder",
						"description": "To start, try opening an example folder that has been preconfigured for this tutorial. This is optional, but helps for following along!",
						"button": {
							"title": "Open Example",
							"command": "md-to-html.openExample"
						},
						"media": {
							"path": "media/example-project.png",
							"altText": "example project"
						}
					},
					{
						"id": "md-to-html.showPreview",
						"title": "Preview your Markdown",
						"description": "Open a markdown file and click the \"Open Preview\" button at the top of the screen to see a preview of your file. This is technically optional, but it updates live and is helpful to check when creating your content!",
						"button": {
							"title": "Open Markdown File",
							"command": "md-to-html.openMarkdown"
						},
						"media": {
							"path": "media/preview.png",
							"altText": "preview"
						},
						"doneOn": {"command": "markdown.showPreviewToSide" } 
					},
					{
						"id": "md-to-html.convertToHTML",
						"title": "Create your .html file",
						"description": "To create the html file, run \"Convert Document to HTML\" from the editor actions context menu, behind the three dots top of the screen. This will create an .html file along side the markdown file.",
						"button": {
							"title": "Open Markdown File",
							"command": "md-to-html.openMarkdown"
						},
						"media": {
							"path": "media/convert-option.png",
							"altText": "showing editor actions context menu"
						},
						"doneOn": {"command": "md-to-html.convertToHTML" }
					},
					{
						"id": "md-to-html.openInBrowser",
						"title": "Open your .html file in the browser",
						"description": "Test that everything worked by opening the .html file in your browser. First open the html file in vscode, then right click in the editor and choose \"Open in Default Browser\".",
						"button": {
							"title": "Open HTML File",
							"command": "md-to-html.openHTML"
						},
						"media": {
							"path": "media/open-in-browser.png",
							"altText": "use editor context menu to open an .html file in your browser"
						},
						"doneOn": {"command": "extension.openInDefaultBrowser" }
					},
					{
						"id": "md-to-html.addKeybinding",
						"title": "Create a keyboard shortcut",
						"description": "That's all! You can share that single .html file with anyone without needing to bundle the images. To make this even easier in the future, consider adding a keybinding for the \"Convert Document to HTML\" command.",
						"button": {
							"title": "Add a keybinding",
							"command": "md-to-html.addKeybinding"
						},
						"media": {
							"path": "media/add-keybinding.png",
							"altText": "use the keybindings editor to add a keybinding for this command"
						}
					}
				]
			}
		]

Edit: Added a "primary" boolean to category items indicating whether the category should be auto-opened on install.

Moving to April for continued API discussion.

Jackson Kearl (@JacksonKearl)

Jackson Kearl (@JacksonKearl) Is it option here to add images for [ light, dark, HC ] color themes from extensions?

Mohamed AbouGendy (@pixieaka)

Mohamed AbouGendy (@pixieaka) that is not currently surfaced, though we support it internally and could potentially. Is this something you would use?

Jackson Kearl (@JacksonKearl)

Jackson Kearl (@JacksonKearl) Yeah I could use this feature to unify my extension experience to mate user interface like HC or Light. Can this be optional if extension slides need to display code photos it would be better to be customizable for user UI.

That sounds reasonable, can you create a new issue for it?

Jackson Kearl (@JacksonKearl)

Jackson Kearl (@JacksonKearl) Absolutely! #120122 .

For those who want to try this new feature, I just want to mention that, setting workbench.welcomePage.experimental.extensionContributions to true (for the insiders built on 2021/04/28) is a pre-requisite. Otherwise you don't see anything.

New API:

"walkthroughs": [
  {
    "id": "exampleProject",
    "title": "Turn Markdown into HTML",
    "description": "Use this sample project to learn how to convert Markdown to HTML!",
    "primary": true,
    "steps": [
      {
        "id": "md-to-html.openExample",
        "title": "Open an example folder",
        "description": "To start, try opening an example folder that has been preconfigured for this tutorial. **This is optional**, but helps for following along!\n[Open Example](command:md-to-html.openExample)",
        "media": {
          "path": "media/openExample.md"
        },
        "completionEvents": ["extensionInstalled:tyriar.luna-paint"] 
      },
      {
        "id": "md-to-html.showPreview",
        "title": "Preview your Markdown",
        "description": "Open a markdown file and click the __\"Open Preview\"__ button at the top of the screen to see a preview of your file. **This is technically optional**, but it updates live and is helpful to check when creating your content!\n[Open Markdown File](command:toSide:workbench.action.quickOpen?%22.md%22)",
        "media": {
          "path": "media/preview.png",
          "altText": "preview"
        },
        "completionEvents": ["onCommand:markdown.showPreviewToSide"]
      },
      {
        "id": "md-to-html.convertToHTML",
        "title": "Create your .html file",
        "description": "To create the ``.html`` file, run __\"Convert Document to HTML\"__ from the editor actions context menu, behind the three dots top of the screen. This will create an ``.html`` file along side the markdown file.\n[Open Markdown File](command:toSide:workbench.action.quickOpen?%22.md%22)",
        "media": {
          "path": "media/convert-option.png",
          "altText": "showing editor actions context menu"
        },
        "completionEvents": ["onCommand:md-to-html.convertToHTML"]
      },
      {
        "id": "md-to-html.openInBrowser",
        "title": "Open your .html file in the browser",
        "description": "Test that everything worked by opening the ``.html`` file in your browser. This requires [installing the open in broswer extension](command:workbench.extensions.installExtension?%22techer.open-in-browser%22).\n First open the html file in vscode, then right click in the editor and choose \"Open in Default Browser\".\n[Open HTML File](command:toSide:workbench.action.quickOpen?%22.html%22)",
        "media": {
          "path": "media/open-in-browser.png",
          "altText": "use editor context menu to open an .html file in your browser"
        },
        "completionEvents": ["onCommand:extension.openInDefaultBrowser"]
      },
      {
        "id": "md-to-html.addKeybinding",
        "title": "Create a keyboard shortcut",
        "description": "That's all! You can share that single ``.html`` file with anyone without needing to bundle the images. To make this even easier in the future, consider adding a keybinding for the \"Convert Document to HTML\" command.\n[Add a keybinding](command:workbench.action.openGlobalKeybindings?%22md-to-html.convertToHTML%22)",
        "media": {
          "path": "media/add-keybinding.png",
          "altText": "use the keybindings editor to add a keybinding for this command"
        }
      }
    ]
  }
],

Where completionEvents follows same basic flow as avtivationEvents, and takes keys like: onCommand: onLink: onView: onSettingChanged: onContextKeyDefined: extensionInstalled: stepSelected

Notes from API review:

onContextKeyDefined => onContext
Consider supporting configuration in a separate file (see snippets)
~~Better name for "primary"~~ Removed entirely
media.path => media.image, media.markdown

Rename keys and support full context key expressions for check offs

Implemented remaining items from API review. Will consider supporting separate config files as needed by implementors

Navigation Menu

Repository navigation

Allow extensions to contribute getting started content #119097

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Allow extensions to contribute getting started content #119097

Description

Activity

JacksonKearl commented on Mar 17, 2021

JacksonKearl commented on Mar 24, 2021

pixieaka commented on Mar 27, 2021

JacksonKearl commented on Mar 29, 2021

pixieaka commented on Mar 29, 2021

JacksonKearl commented on Mar 29, 2021

pixieaka commented on Mar 29, 2021

Eskibear commented on Apr 29, 2021

JacksonKearl commented on May 25, 2021

JacksonKearl commented on May 25, 2021

JacksonKearl commented on Jun 3, 2021

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions