Run shell command when link is clicked

[hakonhagland]

Hi, I am new to obsidian. Thanks for writing this nice plugin. What I would like to do is to create a note which references a pdf file. So for example, if I have a note "PDF object streams.md" :

PDF 1.5 introduces a new kind of stream, an object stream, which contains a se-
quence of PDF objects. The purpose of object streams is to allow a greater num-
ber of PDF objects to be compressed, thereby substantially reducing the size of
PDF files. The objects in the stream are referred to as compressed objects. (This
term is used regardless of whether the stream is actually encoded with a compres-
sion filter.)

See page 77 in the PDF reference manual.

So now instead of just having the last sentence "See page 77 in the PDF reference manual." it would be great if we could click on that as a link and it would open the PDF viewer with the correct document at page 77.

I am on Linux, so I think the following shell command should do okular -p 77 /path/to/pdf_reference.pdf, where okular is my PDF viewer of choice. Is it possible to do with this plugin?

So in general: How to run a shell command when a link (or button, or something else that is clickable) is clicked? I also saw this plugin which can create buttons, but I think it cannot run external commands.

[Taitava]

Summary of plans

(Added 2022-04-09).
The following new features can be planned. The first one is quite clear and can be developed. Others can be though after implementing the first one, but I haven't yet decided, will they be implemented.

1. • Execute shell commands via Obsidian URI #195: Probably the easiest to implement and suits this case well. Edit 2022-07-17: Released some time ago.
2. Custom buttons like discussed below in this message. (Will this be needed if Execute shell commands via Obsidian URI #195 works well?)
3. A click event for any link in a note.

My original post

Hi, thank you for your message! 🙂

The idea of a link or button to execute shell commands is nice, and it's been actually suggested before, but it took some time for me to find where it was suggested.

• Events: Execute shell commands automatically when something happens #60 (comment)
• My mention about the After switching the active pane in the linked message is maybe not so good, so you can just ignore it.
• As the message is in a discussion that is really long and a bit messy, let's continue discussing this idea here in this discussion you created. 🙂
• I'll move this discussion from Q & A to Ideas.

---

Thank you for the tip about the Buttons plugin. I tested it quickly just to see the syntax it uses to create buttons. Here's an example (as a note to myself):

```button
name Hi
type command
action Edit file title
color blue
```
^button-lovh

If SC would add a similar feature, then I guess a block code syntax would be a good choice for SC, too. I'll update this discussion when I get better plans for how to implement this. I can see two different types of features here:

1. The button style like mentioned above.
2. Hooking into Obsidian's links to execute shell commands when a link is clicked. This would allow any links to execute shell commands, no need to use a custom syntax to create links/buttons. I'm really not sure if Obsidian's API has a method for this, I guess no. At least I can keep this idea on my mind and maybe make a feature request for Obsidian to add this kind of possibility to the API.

A possible quick and dirty workaround

The only quick and dirty workaround I can figure out now is that you could add a shell command to a context menu that appears when you right click a link in the editor.

1. A requirement for this is that your PDF file needs to reside somewhere in your Obsidian vault. Unfortunately this won't work otherwise.
2. Create a shell command like this: okular -p 77 {{event_file_path:absolute}}.
3. Next to the shell command field, click an icon with tooltip Events. Enable File menu event.
4. Now when you right click a link to a file, you should see your shell command appearing in the context menu. The File menu event is normally used for the side bar's file navigation context menus, but Obsidian includes the menu items also when right clicking a link to a file in the vault.

Another possible quick and dirty workaround

Well, another idea just came to my mind. This is really different than what you were looking for, but let's see.

1. You can define YAML values in your Obsidian notes. If you don't know what that is, please ask me and I'll describe it to you or find a link for more information.
2. Your note file can contain the following content at the very top of the file:

   ---
   my_pdf_file: "/path/to/pdf_reference.pdf"
   ---
   
   # My normal note content...
   ... is located below the YAML block.

3. You can define a shell command like this: okular -p 77 {{yaml_value:my_pdf_file}}. No events are needed.
4. Now you can assign a custom hotkey for the shell command (e.g. Ctrl/Cmd + Shift + P, stands for PDF) so you are able to open the PDF using a keyboard.

If you have multiple note files with a different PDF file for each of them, each of the note files can have their own YAML section, containing path to that note file's related PDF. Whenever you use that shell command, you just need to have a file open that contains a YAML section that contains a my_pdf_file property. You can change the property name to something more descriptive, if needed. Just remember to change it in the shell command, too. 👍

[FelipeRearden]

Hello @Taitava !!!!!!!

If you don't mind, I think I have a suggestion ... let's see :)

If I understood correctly, our Obsidian friend wants to execute an SC command from a link that is inside a note.

To do this, you need to install an plugin called Obsidian Advanced URI

• This plug-in have a feature that let you create URI to commands form the command palette.

This way you can create a URI for you SC command. Following the instruction of the plugin you will see that is easy.

This is the looks like URI for your SC command:

obsidian://advanced-uri?vault=name&commandid=obsidian-shellcommands%253Ashell-command-99

Just add this URI to text like this ....

[See page 77 in the PDF reference manual](obsidian://advanced-uri?vault=name&commandid=obsidian-shellcommands%253Ashell-command-99)

Go to Reading view and click on the link and you SC will be executed :)

I hope it helps. I'm not 100% sure if I understood your workflow but I hope it is what you want.

Have a great day 🌞

[Taitava]

Hello @Taitava !!!!!!!

If you don't mind, I think I have a suggestion ... let's see :)

If I understood correctly, our Obsidian friend wants to execute an SC command from a link that is inside a note.

To do this, you need to install an plugin called Obsidian Advanced URI

Thank you, @FelipeRearden! Very nice that you are helping here! ❤️

This is a nice way of creating links to shell commands in situations where the link does not need to customise the shell command. In my first answer I was thinking that the PDF file might be different from link to link. If multiple PDF files are needed to be supported, then the PDF file path cannot be hardcoded in the shell command, it needs to come from some variable (but this might be something @hakonhagland does not actually need?). Anyway, as @hakonhagland stated below, at least the page of the PDF might change (something I didn't notice in my first answer). So the page needs another variable, too.

The Buttons plugin which @hakonhagland mentioned, has an ability to assign Obsidian commands to buttons, too. So, that would be one option, but only if we wouldn't need the variables. All methods to execute Obsidian commands lack the ability to define additional arguments to the commands, and that's understandable as that's something Obsidian's commands are not designed for.

So, for now, it seems to me that we do not have a solution, not even a workaround. But these workaround examples are still nice, maybe they can be useful in some other situation. 👍

Let's keep planning the button/link feature. 🙂

[FelipeRearden]

Hello @Taitava !!!!!!!

I'm glad that you liked my suggestion !!!!!!!!

I was pretty confident that an URI would be enough for this workflow from our comunitty friend.

But I 100% agree that since it's an dynamic link, we need new approach in SC to cover this :)

---

Sorry for the late reply, I almost lost this one 😅

Have a great day 🌞 🌞 🌞

[hakonhagland]

Hi @Taitava and @FelipeRearden!

Thanks for the quick replies! Let's start with the suggestion of @FelipeRearden. I was not able make this work: When I click the link nothing happens. I created an alias okular77 for the comand in the shell commands settings, so I tried with this link format:

[See page 77 in the PDF reference manual](obsidian://advanced-uri?vault=main&commandid=obsidian-shellcommands%253Aokular77)

where main is my current vault. I am not sure about the commandid. I was not able find the documentation for the correct form, so it is probably not correct.

Both the two methods suggested by @Taitava, seems to work fine here.. but here is my opinion (maybe I am missing something though)

All three suggestions have the drawback of having to create a new command for each page number I reference in the PDF. I am thinking that I will have many reference to different pages in that PDF file. So this will be awkward to do. For each page I will have to create a new shell command.

The first suggestion of @Taitava additionally has the drawback of having to copy the pdf file into the vault. I would like to avoid this to only keep one copy of the PDF file on the computer. I might be able to use a symbolic link in the vault though..

The second suggestion of @Taitava has the drawback of not being a clickable link but a keyboard shortcut instead. I think this will get confusing if there many references to different pages in the same file. In addition to having to define all the shell commands (one for each page reference)

Summary: none of the suggestions seems very promising to me.

Hooking into Obsidian's links to execute shell commands when a link is clicked. This would allow any links to execute shell commands, no need to use a custom syntax to create links/buttons. I'm really not sure if Obsidian's API has a method for this, I guess no. At least I can keep this idea on my mind and maybe make a feature request for Obsidian to add this kind of possibility to the API.

I am new to javascript and plugin writing but I can try to investigate this also. Wouldn't investigating the source code of the plugin obsidian-advanced-uri suggested by @FelipeRearden be a starting point? It must somehow parse the URL when we click it, right? I also found this plugin which might reveal something about hooking into the URL link parsing when user clicks a link. What do you think?

[FelipeRearden]

I was not able make this work: When I click the link nothing happens. I created an alias okular77 for the comand in the shell commands settings, so I tried with this link format:

Follow these steps to create a URI for the SC command:

Step 1: Open the URI Command

Step 2: Don't specify a file

Step 3: select your SC command from the list (I'm on mobile, that why I cant send a picture from this step

Step 4: the URI is copied in your clipboard

Step 5: Create de URL link

---

[See page 77 in the PDF reference manual](obsidian://advanced-uri?vault=main&commandid=obsidian-shellcommands%253Aokular77)

where main is my current vault. I am not sure about the commandid. I was not able find the documentation for the correct form, so it is probably not correct.

When you generate the URL following my steps above you will see that the URI generate in the end a number instead of ocular77 in the URI. That's the right syntax. This number is the number of f SC command that you see in the SC setting for the ocular SC command.

I hope you can get this working :) I tested this before my first reply and I can confirm that we can create SC from URI links.

Good luck 🍀
I'm here if you need more help 🛟

[FelipeRearden]

All three suggestions have the drawback of having to create a new command for each page number I reference in the PDF. I am thinking that I will have many reference to different pages in that PDF file. So this will be awkward to do. For each page I will have to create a new shell command.

Question? Every new page (77, 78, 79 , 300 ...) will have a different note in Obsidian or you will cumulate See page [page_number=77] .... in on note?

Based on your answer I might have a solution 🤔

[Taitava]

All three suggestions have the drawback of having to create a new command for each page number I reference in the PDF.

Damn, sorry I overlooked this! I didn't notice you had the page defined as well. This will need the links to support custom variables. They are something that are in development at the moment. The custom button/link solution could include an ability to define values for custom variables. It might be harder to implement for other links.

The first suggestion of @Taitava additionally has the drawback of having to copy the pdf file into the vault.

Yea, those were only workarounds, so meant to be temporary until the link thing gets implemented (can take some time as there's quite a lot of other stuff already in planning), so they are not the best possible solutions.

I am new to javascript and plugin writing but I can try to investigate this also. Wouldn't investigating the source code of the plugin obsidian-advanced-uri suggested by @FelipeRearden be a starting point? It must somehow parse the URL when we click it, right?

The problem is not the URL, we don't actually need any URL's to implement this link feature. I.e. we could have links or buttons that use JavaScript's onclick event instead of URLs. Edit 2022-04-05: Now that I've thought about this more, a URI handler can be implemented, and I wrote a separate discussion for it: #195

I also found this plugin which might reveal something about hooking into the URL link parsing when user clicks a link. What do you think?

Thank you for the plugin reference! I looked at it, and yes, it can provide some information. At a quick glance, I found this click event registration. It's almost universal JavaScript, not so specific to Obsidian. It means we need to identify the clicked element ourselves: is it a link or some other element? If it's a link, identify where the link is located: is it located in a note file (= in the editor) or in some other part of the application. We don't want to interfere with the latter types of links. This identification process might involve digging into Obsidian's private API (e.g. relying on HTML elements' class names that are not documented anywhere), which is something I try to avoid (haven't completely avoided so far, though), as it might change with newer Obsidian versions without prior notice.

When we know it's a link in a note file, then we might have some ruleset to determine whether a shell command should be executed or not. E.g. make it possible for a user to define that links to PDF files should be handled by a shell command, but all other links should be left alone so that Obsidian can handle them the normal way. I really need to think about how to develop a flexible way of defining a custom ruleset for this.

All of the above is only related to the plan of hooking into normal, existing links. The plan about creating custom buttons/links is not affected by that, it might be easier to do. I think we could start with custom buttons, and see how well they perform. If still needed, hooking into other links could be implemented afterwards.

[Taitava]

I am not sure about the commandid. I was not able find the documentation for the correct form, so it is probably not correct.

You are correct, that there is no documentation where the shell command id would be mentioned. I know you found the id already, but I'll just mention that there are currently two places where the id can be found: If you don't define an alias text for a shell command, then the id number is shown in the settings:

Here the id number is visible after the # character, so the id is obsidian-shellcommands:shell-command-71 in this example.

The other place where to find the id number is .obsidian/plugins/obsidian-shellcommands/data.json. Open it and locate your shell command:

"shell_commands": {
    "0": {
      "alias": "Git GUI (No need to test)",
      "confirm_execution": false,
      "ignore_error_codes": [
        259
      ],
      "output_channels": {
        "stdout": "ignore",
        "stderr": "notification"
      },
      "output_channel_order": "stdout-first",
      "platform_specific_commands": {
        "default": "",
        "win32": "git-gui"
      },
      "shells": {},
      "events": {},
      "command_palette_availability": "unlisted",
      "preactions": [],
      "variable_default_values": {}
    },
    ...

Here the id number is 0, so the Obsidian command palette id is obsidian-shellcommands:shell-command-0.

(In the future, shell commands will have ids that consist of letters and numbers, so they will be more random. But already created shell commands will still keep their numeric ids.)

I started a new feature discussion for adding the id in an easier place to find.

[hakonhagland]

@FelipeRearden Yes this worked for me know. Cool! Anyway, we still have the issue with having to specify a shell command for each page number..

Every new page (77, 78, 79 , 300 ...) will have a different note in Obsidian or you will cumulate See page [page_number=77] .... in one note?

I think mostly the first case: every page have a different note. But some notes might have references to different pages though..

[FelipeRearden]

@FelipeRearden Yes this worked for me know. Cool!

Great!!!!

Anyway, we still have the issue with having to specify a shell command for each page number..

Every new page (77, 78, 79 , 300 ...) will have a different note in Obsidian or you will cumulate See page [page_number=77] .... in one note?

I think mostly the first case: every page have a different note. But some notes might have references to different pages though..

If I were you I would go for this strategy ...

1- Use a plugin like Apply Patterns or Advanced Cursors or another plugin that deals with regex to select the page number .

2- SC has a variable {{selection}} that let you use the selection in the active note as a term (argument) of your SC command.

Following your example would be something like this:

okular -p {{selection}} /path/to/pdf_reference.pdf

This way you could have a single SC for every page BUT you have to test the right regex query to select the page_number of the note.

---

This is everything that I can think about this workflow. I let you know if I found any other idea.

Have a great day!!!!!

[hakonhagland]

okular -p {{selection}} /path/to/pdf_reference.pdf

@FelipeRearden Neat trick.. Thanks. However, as I understand this will be a workaround that might work provided I only have a single page reference in a given note. If I have more references in a note, it will not be optimal solution.

Hooking into Obsidian's links to execute shell commands when a link is clicked. This would allow any links to execute shell commands, no need to use a custom syntax to create links/buttons. I'm really not sure if Obsidian's API has a method for this

@Taitava I think I found the method, see this line:

this.registerObsidianProtocolHandler("advanced-uri", async (e) => {

The method is defined in the API at line 2418. It looks like it should be possible to use this method like they do in obsidian-advanced-uri plugin? What do you think?

I do not know javascript yet, so I cannot create a PR yet but I will try learning some javascript to be able to contribute in the future if necessary.

[Taitava]

Thank you. I'll write more about this later. It's something that deserves a new discussion, as it can be considered as a separate feature, too. 🙂

[Taitava]

I do not know javascript yet, so I cannot create a PR yet but I will try learning some javascript to be able to contribute in the future if necessary.

Contributions are welcome, but at the same time I acknowldge that is plugin's codebase is not small, so it might take some time for new developers to understand the code and know which files to modify in order to implement a certain feature. Another thing is that currently there is multiple new features in development that will be released in 0.12.0, and those features contain so drastic changes all over the codebase (especially in the shell command execution part), that the main branch is currently very outdated. So, at least this particular time is not the best moment for others to fork and do changes to this plugin. But anyway, you mentioned you would not start immediately, and that suits the current situation very well. That being said, contributions are welcome in the future. 🙂👍

[hakonhagland]

registerObsidianProtocolHandler()

I got two ideas of how this could work. Let's use the obsidian protocol name shell-command as an example. First, by passing a parameter to the shell command like this:

[See page 77 in PDF rererence manual](obsidian://shell-command?commandid=okular?param1=77)

where in this example I would have created an alias called okular for the shell command. Then the shell command could look like this: okular -p {{uri_param:param1}} /home/hakon/pdf_reference.pdf

Or, alternatively as the second idea: to avoid repetition of the number 77 in both the link text and in the protocol parameter, allow for defining javascript parser functions (let's say these parser functions can be defined in the shell command settings page). Then the link could look like this instead:

[See page 77 in PDF reference manual](obsidian://shell-command?commandid=okular?link-text-parserid=okular_parser)

here link-text-parserid gives the id of the javascript parser (I created an alias for the parser called okular_parser in this example). The javascript parser is given the link text See page 77 in PDF rererence manual as input argument (it is assumed that this text could somehow be determined from the caret or mouse position when the link is clicked. Is this possible?). The parser is then responsible for returning commandid and the param1 such that we later can call the correct shell command id with the correct parameter (param1=77) as in the first example..

What do you think?

[Taitava]

Thank you for your suggestions! 🙂 I answered them here: #195

[FelipeRearden]

One more attempt to help ...

Since you know how to code code, maybe you could create an Templater script to select the page in the link while click with the mouse.

Resources that I found that could corroborate my idea.

There is a Templater script that uses the mouse click on a link (internal)

✉️ This is the post on Discord

📽 This is the Video:
https://www.loom.com/share/53b2c6b599ff4d6492b90833a1797d70

👨‍💻 This is the Code:
https://gist.github.com/GitMurf/5ba341b8dba7ccd7e24129f4469ca920

---

Maybe triggers something :)

Have a great day!

[Taitava]

To sum this all up

I just wrote a quick summary of the development plans in my first message above. The first thing to go ahead with is #195.

[Taitava]

Just a heads up here too, #195 is now in a beta test: #228

[Taitava]

#195 is now released in version 0.13.0.