Tiddlywiki and VS Code?

It did run some tests, if there is a chance to be implemented as a standard saver. It needs to look more like this:

title: $:/ndarilek/vscode-integration/saver.js
type: application/javascript
module-type: saver

(function () {
	"use strict";

	var VscodeSaver = function (wiki) {
		this.vscode = acquireVsCodeApi();
		this.wiki = wiki;
	};

	VscodeSaver.prototype.save = function (text, method, callback) {
		this.vscode.postMessage({ command: "save", text });
		// Errors are surfaced in VS Code.
		callback(null);
		return true;
	};

	/*
	Information about this saver
	*/
	VscodeSaver.prototype.info = {
		name: "vscode",
		priority: 4000,
		capabilities: ["save", "autosave"]
	};

	/*
	Static method that returns true if this saver is capable of working
	*/
	exports.canSave = function (wiki) {
		if (typeof acquireVsCodeApi !== "undefined") return true;
		return false;
	};

	/*
	Create an instance of this saver
	*/
	exports.create = function (wiki) {
		return new VscodeSaver(wiki);
	};
})();

In your code you forgot to rename the prototype functions to VscodeSaver so the internal functions are all missing.

The TW core uses export.canSave() to check if a saver is worth to be initialized. If this function returns false absolutely nothing of the code is executed at all.

The TW core uses the export.create() function to instantiate the saver with VscodeSaver(wiki); … When the new is executed it needs to initiate the acquireVsCodeApi() functioin. The API instance need to be saved to a “private” variable available with this … as used in the .save() function.

I think my code could work, if acquireVsCodeApi is globally available in the VSCode web-view. I’ll have to check the docs.

Can you provide some links to the VSCode development docs you are using, to get me started?

Just to be sure. I’m still interested to have TW as a VSCode panel.

But

I did read a bit about the WebView API and found something interesting. It seems WebViews are considered a “heavy” workload in VSCode. From a programmers point of view, I do understand the following info as a plea: “Only use it as a last resort”. … Which makes me think …

TiddlyWiki is a full-blown web-app, so we should expect some “blowbacks” on the way.

Should I use a webview?

Webviews are pretty amazing, but they should also be used sparingly and only when VS Code’s native API is inadequate. Webviews are resource heavy and run in a separate context from normal extensions. A poorly designed webview can also easily feel out of place within VS Code.

Before using a webview, please consider the following:

  • Does this functionality really need to live within VS Code? Would it be better as a separate application or website?

  • Is a webview the only way to implement your feature? Can you use the regular VS Code APIs instead?

  • Will your webview add enough user value to justify its high resource cost?

Remember: Just because you can do something with webviews, doesn’t mean you should. However, if you are confident that you need to use webviews, then this document is here to help. Let’s get started.

Thanks for all this feedback.

Just so we’re on the same page, I’ve read all these docs. I’ve also done this for a couple decades, so wrangling code and fixing whatever errors there certainly are isn’t the problem. I’ve got this, don’t worry, I just didn’t know how to import the JS or if there was some egregious thing I missed.

Now that I know how to import this correctly, I’ll take it from here. Also, I’m not worried about VS Code running TW being resource-heavy, and if it is for someone then this extension may just not be for them. Thus far it’s been perfectly fine to use so it’s probably NBD.

All righty. https://github.com/ndarilek/vscode-tiddlywiki-integration vsix build available in the release.

Right now you can open up a new project and press ctrl-alt-w to create an empty wiki at the configured path in the workspace, wiki.html by default. If wiki.html already exists, ctrl-alt-w opens a webview and focuses it.

If the extension creates the wiki for you then the saver is pre-installed. Otherwise you’ll need to import the tiddler linked in the README.

PRs with icons and other graphical assets welcome. Once I’m fairly confident it works, I’ll publish it to the marketplaces, update the first post in this thread, etc. I just don’t have the wherewithal to deal with Microsoft/Azure crap ATM.

Suggestions welcome. Essentially, I’ve been wanting to use TiddlyWiki as a sort of design document/issue tracker hybrid for game development work, but I didn’t really like any of the separate apps nor did I want something running in the browser that wouldn’t let me keep my documents in git. I want to see if I’m more likely to create and maintain my docs if adding issues/designs is as simple as ctrl-alt-w, work with wiki, ctrl-alt-e, edit code, repeat. I’m happy to add other functionality but I don’t want to stray too far from that initial design goal. Ideally this just lets TW do what it does best, and provides minimally-invasive interventions where helpful.

2 Likes

Which OS do you use?
I’ll post my issues at GitHub, where they can be closed when they have been resolved.

Hi @nolan great to see your progress on this. One feature I’d be interested in exploring is ways to have the TiddlyWiki instance respond to the context of the user in VSCode.

For example, if the focus is in a particular source file, the pathname of the file would be passed to TW via a magic tiddler $:/vscode/context/pathname which can be used to dynamically display documentation relating to that particular file. It may be possible to do it a the function/method level, depending on how much information one gets from VSCode.

As an option that would require some work on the TW side, I often think it would be useful to be able to scatter documentation tiddlers within the same folders as the JS/CSS/HTML modules/tiddlers that they document. As a simple example, readme.tid might be taken as the documentation tiddler for a source folder.

Taken together, those two features could make quite a nice general purpose documentation suite.

Yet another feature I’d love to see would be to able to click a button in the TW to execute a particular command in one of the terminal windows (opening it if required). That way I could use TW as a sort of dashboard for commonly used commands.

1 Like

@jeremyruston … The VSCode plugin needs an SVG icon. Which one should we use there?

May be the blue favicon as an SVG? … If it’s part of the VSCode sidebar UIs, it will be greyed out. So some experimenting will be needed.

Interesting ideas. They sound great, but my hope was that I could create something part design doc, part issue tracker, and save/manage the whole thing alongside my code. I don’t see myself using these interactive documentation features, and lots of them would require deep work in TiddlyWiki itself which I’m still learning.

I am, however, willing to figure out if or how the extension might support other extensions via some sort of API. It’s not hard to communicate to and from extension-hosted WebViews, so in theory it should be possible for this extension to manage the WebView while exposing APIs for other literate documentation extensions. I’m also willing to give commit rights to anyone who might be interested in doing this work in the context of this extension, as long as they’re willing to maintain it. I only ask that folks not lose sight of my intent to keep supporting the simper use case of just letting folks spin up wikis in their projects when they’d rather not use more complicated/less accessible project planning tools. :slight_smile:

As an aside, wouldn’t this magic tiddler approach change the wiki every time a file is visited? Seems like that’d create lots of git churn for folks like me just wanting to update the wiki when designs change or tasks are updated. Or is there some way to expose tiddlers internally without modifying the HTML document? If so, I’d consider at least adding APIs to push tiddlers into the wiki. Some sort of query API might be nice too, now that I think of it. With that I could design game entities as tiddlers, render their properties to tables to check out balance issues, then have VS Code query those tiddlers and write their properties to JSON which my game engine could load. Hmm.

TW uses the $:/core/save/all template tiddler to save the wiki. It contains a filter, which excludes every system-tiddler which is prefixed with $:/temp/ … So if this prefix will be used, there won’t be any changes to the html file itself.

hihi, … That happens once you start getting feedback. I hope I’ll have some time soon, to create a nice icon :wink:

Yes indeed, I think you’ve arrived at a solid MVP, with nicely tight scope and clear vision. I’d be hoping to use it as a base to explore the other features I mentioned. I didn’t mean to imply that I was expecting you to implement those ideas.

A plugin architecture would be terrific.

Down the road, there may also be scope to share code and protocols with TiddlyDesktop, which is also based on Chromium but was developed before WebView was available, and so currently uses a special type of iframe to host the wikis…

As @pmario points out, we have the $:/temp/ namespace for ephemeral tiddlers that shouldn’t be retained during a save. There are other approaches: the core has support for executing action tiddlers by tag, so we could define a $:/tags/VSCode/ScopeChange tag that indicates tiddlers containing actions strings that should be executed whenever the VSCode scope changes.

Great idea.

Interesting ideas.

Apparently extensions can export and access other extensions’ APIs. I’m certainly open to working with anyone wanting such an API, but for now I don’t know enough about either TiddlyWiki or VS Code extensions to figure out how such a thing should look and what would make sense.

One additional hurdle I hit today: is there some way to intercept and change how reloads are handled? I suspect the WebView doesn’t like its content asking that it be reloaded. The saver seems to be working, so what I think I need is for the wiki to request a reload so I can populate the view’s content with whatever’s on disk. I guess it can then reload and fail. Is this what I want? https://tiddlywiki.com/static/WidgetMessage%3A%20tm-browser-refresh.html If so, how would I catch it in a context where I can run JavaScript?

Also, for anyone who can see what’s going on, is the default panel size very small? I get a tiny edit area in my setup, which doesn’t make sense given my screen size. Not sure if I need to specify a different panel size or location, or if something is just odd with my setup.

Thanks everyone.

On the first start, the wik is opened in the left sidebar area, that is used by the file tree panel. So usually it is the same size as the file tree, which is small.

With my settings it uses about 20% of the screen width and 80% is the text editing area.

Since the wiki is “just” an other panel, I did split the text editor and moved the wiki panel to the right of the text editor. So I have file-tree, text editor 40% and wiki panel 40%

I think in VSCode I also use a UI zoom level of 1. So everything is a bit bigger then normal. Which in turn makes the text of the wiki bigger as the text in the text editor. – That’s strange.

That’s why I did change the font-size and line-height settings in the TW config tab. So it fits the font-sizes in the VSCode text editor.

The problem with those settings seems to be, that they are not saved. … I’ll have to investigate that. …

There are some more things that can be improved with the TW UI as a VSCode panel. eg: the TW story river has a left and a right gap, which is empty space.

With a custom theme, it would be possible to use the 40% space more efficiently. The sidebar could be hidden by default and a top menu could be implemented instead. …

I think a slimmed down UI may also be an advantage for screen readers. But I don’t have any experience with accessibility improvements.

So it’s good to have you on board!

Thanks for the feedback. V0.0.3 moves the wiki view container out of the activity bar and into a separate panel alongside where the terminal and other larger elements live. It doesn’t matter to me where it goes–I put it where it initially made sense to me–but it now seems to use more space by default. If this current location doesn’t make sense then I can revert it. I don’t seem to have control over how these containers are sized, and while I know they can be resized manually, I want them to have sensible defaults.

It took me some tweaking, till I found out how to reset to the initial location. … It’s right-click the “icon” and select the “Reset Location” option. The next time the wiki will be shown it will use the default location panel you defined. … It seems to be a sensible position. There is more space to start with and it’s easy to expand it to use full height. … So it looks good to me.

If you manually change the location, VSCode remembers it.

I think that’s the case now. If a user ever used a terminal and did resize the height, VSCode will remember that setting anyway. So if the terminal was OK, the wiki should be OK too.

Oooh, nice work. Can’t wait to try it.

There Release v0.0.3+5.1.22 · ndarilek/vscode-tiddlywiki-integration · GitHub is a packaged version of the extension. If you download it, you can install it with

code --install-extension <file-name>

CTRL-ALT-W should start it in VSCode