Constructing Didact Links

Didact Link formatting for opening Didact files inside VS Code

Didact now has the ability to open Didact files themselves, which enables us to leverage files that are at public URLs, such as those put into Github repositories as well as those provided in extension source files or even in scaffolded projects. This capability comes in handy if you want to mix and match tutorials and commands, breaking up lengthy processes into smaller chunks.

• You supply https or http links in the format vscode://redhat.vscode-didact?https=urltofile/file.didact.md or vscode://redhat.vscode-didact?http=urltofile/file.didact.md
• You supply extension links in the format vscode://redhat.vscode-didact?extension=folder/file.didact.md
• You supply workspace links in the format vscode://redhat.vscode-didact?workspace=folder/file.didact.md

Within a given Didact tutorial Markdown file, you can then mix and match link styles, opening other tutorials or launching commands with Didact link formatting

Didact Link formatting for calling Commands

The Didact webview is listening for link events and responds if a link starts with didact.

Examples:

• didact://?commandId=vscode.didact.scaffoldProject&srcFilePath='example/project.json'
• didact://?commandId='vscode.openFolder'&projectFilePath='simpleGroovyProject/src/simple.groovy'&completion='Opened the simple.groovy file'
• didact//?commandId='camelk.startintegration'&projectFilePath='simpleGroovyProject/src/simple.groovy'

All Didact links have the following qualities:

• Starts with didact:
• Then works in pairs
  • commandId=your.vscode.command.id
  • (optional) projectFilePath=my/file/path (assumes it's in the user's workspace, so has the workspace root prepended)
  • (optional) srcFilePath=my/src/file/path (assumes it's in the extension source, so prepends the extension __dirname)
  • (optional) extFilePath=extensionId/my/src/file/path (assumes the file is exposed by another extension and retrieves it from the installed extension path)
  • (optional) completion='my%20notification%20message' (to provide a human readable message to the user upon task completion - note that spaces must be replaced with %20)
  • (optional) error='my%20error%20message' (to provide a human readable message to the user upon task error - note that spaces must be replaced with %20)
  • (optional) text=one$$two$$three (to provide straight text input to the command, with each argument separated by $$) (currently only works out to three arguments, but can likely be expanded further if needed)
  • (optional) user=one$$two$$three (to provide user-provided text input to the command, with each argument separated by $$ -- each string is used as the prompt for the user) (currently only works out to three arguments, but can likely be expanded further if needed)
  • Note: projectFilePath and srcFilePath should be mutually exclusive, but that distinction is not made at present