Sublime Forum

Clickable hyperlinks within projects

#1

I’m writing prose with ST3. For my use case, it would be handy if I could throw in hyperlinks to other project files now and then as I’m drafting–“see this note about blah blah in chapter 7,” etc. It’s been my understanding (perhaps mistaken, I’m no programmer) that ST does not provide a means of adding hyperlinks within files.

However, I just learned how to do project-wide text searches and in the “search results” page that pops up, the paths appearing at the head of each resulting “hit” are indeed clickable links that open the file in question.

I think I’ve either misunderstood all along, and ST really can accomodate hyperlinks between files, or whatever mechanism makes these clickable paths in “search results” work will not work for the use case I described above.

I’d appreciate any thoughts on this. I’d love to be able to use hyperlinking within my writing projects.

0 Likes

#2

The system you’re referring to there for file results is also used in build systems to allow you to navigate to errors by double clicking.

They’re controlled by three settings that you can apply to any given file that allows it to know that some text should allow you to “jump” somewhere, result_file_regex, result_line_regex and result_base_dir.

Generally speaking, the first two settings are used as regular expressions to match something that is the name of the file that you want to to jump to, the line and column inside of that file, and some sort of associated error message (which is used for things like compiler errors). The third one is used to determine for any relative filename found, what the file should be relative to (though you may have noticed that Find in Files displays an absolute file name for everything).

For anything that matches, that text becomes navigable via a click and Sublime will jump to that file at the given location, opening it if it’s not already present.

Downsides here are that the “link” needs to contain the name of the file and the location within it, so less like a web page link. So in your case, the link might look like ../chapters/7.txt:1:check out this note from chapter 7 or similar, which is perhaps less interesting.

It’s also possible via custom plugin code to do similar things as well, though that’s a bit more of an involved topic. An example of that in action is my SnAPI package that used my HyperHelp help system directly in Sublime (demo video below if you’re interested in seeing how something like this might look).

There may be existing packages that use something like this to link between documents and/or TODO items and similar, though I’m not aware of any offhand as I never really had a use for that. Possibly such a package might only work in certain types of files though, which might be problematic for you and your custom prose syntax.

3 Likes

#3

Thanks for the explanation, the pointers, and the link. This may be above my pay grade, but I’ll take a closer look. I appreciate it.

0 Likes

#4

OdatNurd,

Sorry to revive this old question. I didn’t pursue it after your helpful response here–it just seemed beyond me. But now I’m back to looking at it again and wonder if you could give me just a bit more info.

Again, I’m trying to put some rudimentary clickable links to file paths within my txt files. I don’t really care if they’re ugly, just functional. So, for instance, within a chapter_one file, I might want to place a clickable link to this path (I’m on Linux):

/home/dutch/writing/book/chapter_two.txt

You say, above, that the clickable function found in search results files (and build systems) is controlled by three settings–result_file_regex, result_line_regex and result_base_dir.

I don’t know, and can’t fathom, how to implement those settings, which I would want to make available within all my txt files. Is that possible, or is this functionality exclusively for file results and build systems?

Any further instrux on how to implement those settings for my txt file use would be very much appreciated!

0 Likes

#5

The settings will work anywhere; the “issue” (and whether or not it really is an issue is up to interpretation) is that in order to use them, the thing that is the link needs to be the name of the file. That is to say, you can make chapter_two.txt a link, or book/chapter_two.txt a link, but you can’t make it arbitrary text like chapter two without some sophisticated plugin magic.

If that’s not a problem, then it’s pretty easy to get them doing what you want with no plugin code at all, and you can take it to varying degrees as well.

I’ll also preface this by saying that there are quite likely packages that are available that will allow you to follow links in files. I don’t use any personally and they may or may not be entirely the province of jumping between source files and not plain text though, I’m not sure.

Here’s a simple thing you can do right now; open a text file and use Preferences > Settings - Syntax Specific to open the settings file for plain text, then add these settings:

    "result_base_dir": "/home/dutch/writing/book/",
    "result_file_regex": "(\\w+\\.txt)()()()"

The result_file_regex is used to match text represents some file that can be navigated to. The regex is expected to have 4 capture groups (the () bits) that capture from the matched text, in order, the file name, the line in the file, the column in the file, and an error message/info text/etc.

The only group that’s important is the one that captures the filename, since that is how Sublime knows where to go; the other information can be used to open the file on a specific line or to a specific line and column as well.

The result_base_dir setting is used to determine where files that result_file_regex matches live, if it’s not an absolute, fully qualified filename.

With these in place, any .txt file with something that appears to be a text file name (e.g. chapter_two.txt) will make that filename something that will open the file; you can double click on it and the file will open (or a tab is created if the file doesn’t exist; possibly handy way to generate new chapter files since you can type and save into them directly).

As written here, the regex is very simple; you could make it more complex to allow things like path parts as a part of the matched text, etc. The thing to keep in mind is that whatever matches will be double clickable, even if it accidentally matches something that’s not an actual filename.

You’ll notice that although you can double click the filename to open it, there’s no indication that such is actually possible. With a bit of extra tweaking, you can make that more obvious (and if you use ST4, you can take it to an extra level, see below).

I’m mentioning this here because I know from past question you’ve asked that you were working your own custom syntax for your prose, so this might also appeal for that reason.

Imagine a syntax definition that looks like this:

%YAML 1.2
---
# See http://www.sublimetext.com/docs/syntax.html
scope: text.plain.prose
contexts:
  main:
    - match: '\w+\.txt'
      scope: markup.underline.link

This is a very small constrained example, but the takeaway here is that there is a match rule that matches the same pattern for filenames as the setting is using, and it applies a specific scope that scopes the text as an underlined markup link.

Good color schemes should have a predefined rule for that scope to make links more visible. If you apply this syntax to a file, anything that appears to be a filename will be visibly called out, pointing out that you can double click them (remember that if you do this, you need to re-apply the settings, as they’re syntax specific and now the syntax is different).

For the specific case of ST4, along with the font styles of bold and italic that ST3 supports, you can also apply font styles for underlines; the following is how the sample here looks in ST4 using the stock Mariana color scheme:

image

2 Likes

#6

OdatNurd, you are the best. Many thanks for this detailed explanation. I’m going to implement it later today and do some experimenting. I have no doubt it’ll do the trick for me. And yes, I’m on ST4 and I do use a custom syntax for my txt files, so I should be able to style the links as you suggest.

Again, thanks for your time and expertise.

0 Likes

#7

A quick question as I’m working my way through this: If my link text is always going to be a full, absolute path, can I set a less-specific result_base_dir?

In the example I gave you, I mentioned one specific “book” folder–"/home/dutch/writing/book/"–and if I set that as the result_base_dir, as in your sample, all is well for linking to (or creating new) txt files within that folder. But if I want the flexibility to link to any file in any folder, and I’m willing to use full path names in my documents, what should the setting look like for result_base_dir? I’ve been experimenting and I’m not getting there…

0 Likes

#8

result_base_dir is only used to locate files that don’t have full path information; any file that’s absolute would bypass it.

So generally speaking, if your result_file_regex can match something with path components in it (my naive example above does not), then it would automatically allow you to link to any file anywhere on the filesystem if you want.

In such a case, you don’t need that setting at all, but it would be at the cost of every link needing to be to an absolute file.

For your purposes here, you probably want to set it to something like /home/dutch, and then all of your files are relative to your home directory as a whole, but you still have the ability to link to any file if need be.

The impetus there is that if most of your files are going to be based in your home directory, that level of path information on links is redundant. Similarly if you mostly always link to book chapters or your writing, you could adjust the default to that and still use absolute paths as needed.

1 Like

#9

OK, I see. Thanks very much for the clarification. Very helpful. Just one thing–it looks like the last line of your response was snapped off, and I’m curious to hear the rest of that sentence!

0 Likes

#10

Hah, sorry; I changed how I was going to say the thing and didn’t notice that hanger on was still there. :slight_smile:

0 Likes

#11

Got it! Thank you once again.

0 Likes

#12

Hi,

I knew those regex were used in build systems, but didn’t realise they could also be used in the settings. I used the info here to make links in source files too. Thanks.

It works well, but I have to hard-code the result_base_dir.
In different projects, the files are relative to different locations.

Can the $project build variable be used in .sublime-settings?
I tried it but couldn’t get it to work. Maybe I’m missing something. Maybe it is not supported.

"result_base_dir": "$project\\Folder\\Nested\\",
"result_file_regex": "#include [<\"]([^\">]*)[\">]()()()"

Build Systems (sublimetext.com)

Edit:
Of course immediately after posting I thought of a solution…
I removed result_base_dir from .sublime-settings and added is separately to my various *.sublime-project" files under a “settings” key. It works fine that way

0 Likes