FoldingText URL schemes

Continuing the discussion from Details of x-foldingtext:// and x-taskpaper:// url schemes:

Right now the URLs that FoldingText handles are:

Open SDK window:


Open user guide:


Open user node path guide:


Set node path in current document:


To automatically link the selected text as a node path to the current document:

  1. Select the node path text in your document.

  2. Choose Edit > Run Command > link node path

How do I define a link that points to a particular location in an arbitrary FoldingText document? For example, if I have a document stored in iCloud called “mystuff.ft”, how would I create a link that would open to a specific location in that document?

I don’t think that the url scheme yet supports links to particular documents or locations within them, but in the meanwhile you can, of course, call an applescript (for example from the command line, directly or indirectly) passing a filename and a line number to it.

To open test.ft and automatically select line 12, I just ran this from a shell script:

osascript OpenFTFileAtLineN.scpt ~/Desktop/FT_DIFF/Query_test/FT\ CLI/test.ft 12

Using an Applescript like:

property pjsSelectLine : "
	function(editor, options) {
			var tree=editor.tree(),
				rngSeln=tree.createRangeFromLocation(oNode.lineTextStart(), oNode.line().length);
			return true;

on run argv
	if class of argv = list then
		OpenFile(item 1 of argv)
		GotoLine(item 2 of argv)
	end if
end run

on OpenFile(strUnixPath)
	tell application "FoldingText"
		set varOpened to open strUnixPath
	end tell
end OpenFile

on GotoLine(varLine)
	tell application "FoldingText"
		tell front document
			return evaluate script pjsSelectLine with options {linenum:varLine as integer}
		end tell
	end tell
end GotoLine

In the interim, one approach is to use the custom ftdoc:// url scheme with an applescript which copies the current FoldingText selection as a link.

ftdoc:// links can open FoldingText documents at particular lines, optionally restoring the details of selection and nodePath filtering.

They can be used inside or between FT text documents, as well as from browsers, etc.

How does the ftdoc:// scheme react to changed documents? E.g., can I link to a h2 header and always return to that header, even if the line number of the header has changed?


FoldingText lines don’t have ids that persist between sessions, but you could use an ftdoc:// link with just a filepath and a ?nodepath= switch to focus down to a particular heading. (dropping the ?line= switch)

(e.g. with a nodepath like /*/name of header

or perhaps: //headername and @type=heading)

Alternatively, and this might be more helpful, I could add a feature which selected lines by nodepath match, rather than by line number, (as an alternative to using the nodepath for filtering).

I’ll need to find a moment to sit down with pencil and paper to decide what the new switch should be. Perhaps something like ?=selectnodepath

ver 0.2 of ftdoc:// and FTCopyAsURL.scpt

Added switches:

?selnpath= restores selection by path
?find= by text search

FTCopyAsURL now:

  1. Copies a minimum unique nodepath for the selected line to ?selnpath=
  2. copies the text of the line to ?find=
  3. still records any ?line=N (with any selection offsets)

ftdoc:// now:

  1. Opens the specified document, and
  2. applies any ?nodepath= switch as a filter
  3. tries to restore the selection from ?selnpath=, ?find= and ?line= in that order

The ?selnpath= minimal nodepath should be more resilient to text edits than a line number - it will continue to find a line as long as the broad nesting and heading titles are preserved.

?find= should be a useful fall-back

All of these switches are optional, and can be used on their own.

(the offset switches are ignored unless there is a ?line= switch )

The ?line= switch may, at first sight, seem a puzzling inclusion, given the short shelf-life of line numbers, but it turns out to be useful when generating quick overview perspectives across several files (with the FT Command line interface), and using them to click straight back to particular files and lines before further editing.

(the most solid plain text link target would, of course, be a non-printing HTML comment containing a fine-grained date-stamp or UUID)

(easily created with something like textexpander)

Wow, this is amazing. Jesse should put you on payroll! I can’t wait to try this out. Thanks so much for sharing your work here. I’m not sure my technical skills would be up to the task of figuring this out on my own–I’m still not sure how to work with the command line / node path interface.

Jesse: I’m hoping this same approach will work for the next update to Taskpaper, since it is still presumably built from similar internals?

The magic is entirely Jesse’s. ( Not least the very clever piece of code with which he derives the minimum unique nodepath to a selected line).

Just posted drafts of tp3doc:// and CopyTP3AsURL

Simply amazing. Thanks again for sharing your work! Your plugins, and Jamie’s Filter plugins, have made FoldingText one of my most used, and useful, apps.

I added this to my Alfred Workflow for FoldingText. It is great. Now, I have full bookmarking in Alfred for FoldingText!! Really neat. Thanks for the ideas!!!

In Alfred Forums:
In Packal:

Good !

I find this works well for me as a non-printing bookmark (expanded from an abbreviation as a TextExpander shell script entry)

echo -n "<!-- $(date +%FT%T%Z)  %| -->"

(The %| is where TextExpander places the cursor after expansion)

This ftdoc:// url scheme doesn’t work if the FT file’s name contains East Asian characters ( I’m running Chinese version of Maverick on my mac).

Thanks – url decoding seems to be fixed for utf-8 characters in file names (I’ve only tested for 国标简体), in ver 0.4 of Copy As URL and OpenFTDocAtLine

txtQuery-tools repository zip


Thanks! It works perfectly now.

Not sure about that at all… I’ve created some nice foundation for some things, but thanks from me (and everyone else) for all the scripts and tips.

A privilege to labour in the vineyard – hard to imagine a more fertile confluence of outlining, plain text, and very deep scriptability.

Many thanks for all the work that has gone into it.

I also made this into a LaunchBar 6 action: