View on GitHub

vscode-didact

Didact Gives Your Readme Superpowers!

Didact Commands

The VS Code environment provides many different commands that can be called, but they may require some additional work to see what needs to be passed to them. Most will take a vscode.Uri indicating the resource they are operating on, but you may have to actually look at some code in the Microsoft VS Code GitHub repo to divine those details.

What follows is a list of commands provided by the Didact extension and any details to be passed, along with one or more examples of use.

vscode.didact.scaffoldProject

Creates a folder/file structure in the user’s workspace based on the structure defined in the JSON file provided.

Default JSON

"folders": [
	{
		"name": "root",
		"folders": [
			{
				"name": "resources",
				"folders": [
					{
						"name": "text"
					},
					{
						"name": "images"
					}
				]
			},
			{
				"name": "src",
				"files": [
					{
						"name": "simple.groovy",
						"content": "from('timer:groovy?period=1s')\n\t.routeId('groovy')\n\t.setBody()\n\t.simple('Hello Camel K from ${routeId}')\n\t.to('log:info?showAll=false')\n"
					}
				]
			}
		]
	}
]

vscode.didact.openTutorial

Opens the default Didact file as specified by the preference Didact: Default Url.

vscode.didact.startDidact

Opens a Didact window with the Markdown or AsciiDoc file passed in as a vscode.Uri reference. If no Uri is provided, it will attempt to get the currently selected file and assume it is a Didact file.

Note: This can also be done by simply specifying a valid Uri to a Didact file in a vscode://redhat.vscode-didact? link. (See Constructing Didact Links for details on specifying https/http, extension, and workspace paths.

The VS Code Link Handler that is registered uses the startDidact command to handle incoming links specified in this manner.

vscode.didact.startTerminalWithName

Creates and shows a terminal with the given name in the VS Code window. The name can be omitted.

vscode.didact.sendNamedTerminalAString

Sends text to a named terminal, which is then executed in the terminal. If the named terminal doesn’t exist, it is created.

Note: In order to send multiple commands spread out across multiple links in the same terminal window, ensure that the name passed is consistent.

Note: On Windows, strings (such as for echo statements) must be enclosed in double or single quotes like echo "my long string" since the change with https://code.visualstudio.com/updates/v1_57#_native-line-wrapping-support-on-windows.

vscode.didact.sendNamedTerminalAStringNoLF

Same as sendNamedTerminalAString, but the command is not executed in the terminal by default.

vscode.didact.sendNamedTerminalCtrlC

Send a Ctrl+C key combination to a named terminal to stop a long-running process. Terminal with the given name must be accessible.

vscode.didact.closeNamedTerminal

Closes and dispooses a named terminal. Terminal with the given name must be accessible.

vscode.didact.openNamedOutputChannel

Creates and opens a named output channel. If you don’t provide a name then the Didact Activity output channel will be used instead.

Access to output channels is very limited in VS Code and you can only access output channels which were created by yourself.

vscode.didact.sendTextToNamedOutputChannel

Sends a text to the output channel with the given name. If you don’t provide a name then the Didact Activity output channel will be used instead.

Access to output channels is very limited in VS Code and you can only access output channels which were created by yourself.

vscode.didact.requirementCheck

Simple command-line check for system capabilities. Takes three parameters - the id of the HTML element to update with the results, the test command (such as mvn --version, and a string to search for in the resulting text, such as Apache Maven if the mvn command works successfully).

vscode.didact.cliCommandSuccessful

Even simpler command-line check for system capabilities. Takes two parameters - the id of the HTML element to update with the results and the test command (such as mvn --version. If command executes with no errors (return code 0), it returns true. If not, false.

vscode.didact.extensionRequirementCheck

Simple check to see if the extension Id is installed in the user workspace. Takes two parameters: the id of the HTML element to update with the results and the extension Id to check for.

vscode.didact.workspaceFolderExistsCheck

Simple check to see if the workspace has at least one root folder. Takes one parameter: the id of the HTML element to update with the results.

vscode.didact.createWorkspaceFolder

Creates a folder in the user’s temp directory and adds it to the workspace as a makeshift root directory.

vscode.didact.reload

Forces the Didact window to reload with the default Didact file specified in VS Code settings.

vscode.didact.validateAllRequirements

Gathers all requirements in the Didact file and invokes the requirement checks one at a time. Useful if you have a long list of requirements to check.

vscode.didact.gatherAllRequirements

Gathers a list of all requirements in the Didact file. Used internally as part of the vscode.didact.validateAllRequirements execution.

vscode.didact.gatherAllCommands

Gathers a list of all commands used in the Didact file. Used for testing purposes only.

vscode.didact.view.tutorial.open

Menu command used when the user right-clicks on a tutorial in the Didact Tutorials view to Start Didact Tutorial.

vscode.didact.register

Command used to register a new Didact tutorial so that it appears in the Didact Tutorials view. This command is invoked by VS Code Extension code to register tutorials they provide.

	// command ID: vscode.didact.register
	const commandId = 'vscode.didact.register';

	// then pass name, uri, and category
	const tutorialName = 'My First Tutorial';
	const tutorialPath = path.join(context.extensionPath, './path/to/tutorial.didact.md');
	const tutorialUri = vscode.Uri.parse(`file://${tutorialPath}`);
	const tutorialCategory = 'My Tutorials';

	await vscode.commands.executeCommand(commandId, tutorialName, tutorialUri,tutorialCategory);

vscode.didact.view.refresh

Toolbar command used when the user clicks the Refresh button on the toolbar of the Didact Tutorials view.

vscode.didact.copyFileTextToClipboardCommand

Command to copy text from a file onto the clipboard. Handy for longer examples or examples with formatting.

vscode.didact.copyToClipboardCommand

Command to copy text directly from the URL to the clipboard. Handy for short strings you can URL encode easily.

vscode.didact.copyTextToCLI

Command to take the currently selected text in the open editor (of a Didact Markdown or AsciiDoc file) and add a new Didact sendNamedTerminalAString or sendNamedTerminalAStringNoLF link with the selected text automatically URLencoded.

This is triggered by default using Ctrl+Alt+T or Cmd+Alt+T. Note that the key combination can be changed by going into Keyboard Shortcuts (File->Preferences->Keyboard Shortcuts) and searching for copyTextToCLI, then overwriting the Keybinding.

A couple of things to note:

vscode.didact.openUriWithLineAndOrColumn

Command that opens a file and sets the editor on a particular line number. Can also specify the column in which the editor should appear.

Commands Elsewhere

VS Code has a rich set of commands and every extension may have its own commands to mine for Didact links. Some common commands include:

New in 0.1.18! Passing JSON to commands that accept it

Some commands allow passing settings via JSON. We now support that in the Didact URL!

Note that in the vscode.open case, you must pass the enum value for the vscode.ViewColumn enum entry itself. -2 corresponds to Beside and is a useful command to keep in mind!