Creating your own Obsidian iOS Widget

I have become very fond of iOS widgets both on my iPad and iPhone. On the iPad, it functions as a dashboard into all my important apps and activities.

As an Obsidian user I have been wanting for some time to have an iOS Widget to show information from my Obsidian vault. Imagine something like this:

Do you see the special widget?

Yes its a normal iPad screen with a few widgets. But if you look closer you might se something new, it has an Obsidian iOS Widget. That’s right, I decided to make one and that is what you see on this screen.

In this article, I am going to show you how to create you own Obsidian Widget for iOS.

Feature Overview

First, lets outline what this widget can do. The widget can be configured to display information from your Obsidian vault for one of the following types of information:

• List of all starred files (my personal favorite)
• List of recently edited files
• List of files from a specific folder
• Display the text of a file from your vault.

The files listed in each of the aforementioned widget types can be clicked to quickly open the file in Obsidian. So the widget doesn’t just remind you of what files you have in your Obsidian Vault, but it helps you to open those files quickly from your iOS screen.

In addition to these informational options, you can choose from all possible sizes of screen widgets from small to large.

All widget types and sizes

In the remainder of the article, I am going to explain how to install and how to configure them.

I have to be honest, the installation is complex, so follow the steps closely. But I know you can do it and you can always reach out to me on Twitter if you need help.

Installation

First you need to install on your iOS device a free program called Scriptable from the App Store. You can do this either on an iPad or iPhone, your choice!

Scriptable application from the Apple App Store

Scriptable allows us to make useful scripts for our device with Javascript. It also lets us create widgets. Don’t be worried if you don’t know Javascript, that isn’t needed to install or use this solution.

After installing Scriptable, open the Scriptable application. The next step is to create a new script. Do this by clicking the circular blue button in the upper right hand corner.

Click the + button to create a new script

This created for me a new script called “Untitled Script 2” as shown here:

Tap the title to rename the script

Tap the header “Untitled Script 2”. This will popup a window for you to rename the the script. Name it Obsidian Widget.

Now that we have created an empty script and named it, we need to copy in the code for this script. This is a part that gets tricky!

The source code for this script is stored on a website called Github. Click on this link to open the page to the code for this widget:

obisidian-iOS-integrations/ObsidianWidget.js at main · TfTHacker/obisidian-iOS-integrations
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below…github.com

This will open a page in Github that looks something like this:

The code we need for our Obsidian Widget is in the file presented on this web page.

The easist way to get the code is to click on the button that is named “Raw”. The Raw buton will open this script and fill your browser window with the text of the script. This is what you should see after clicking the “Raw” button:

So now for the really tricky part. You need to select all the text in this browser tab and then copy it into the clipboard.

Once you have done that, return to Scriptable and paste the code you just copied from Github into the empty script we previously created.

If you succeeded, you will see something like this:

You are going to see a bunch of code, and perhaps you know what it means or perhaps you don’t. The good news is that you don’t need to understand the code. No programming is required!

Let us summarize what we have done up until this point:

1. We installed the free app Scriptable from the Apple App Store
2. We created a new script in Scriptable
3. We renamed the script to Obsidian Widget
4. We pasted into this script the code we copied from the GitHub page

Now we can click on Done in the upper left-hand corner of Scriptable to save our script. We have finished the installation of the script.

There is one more step to getting Scriptable configured for working with your vault, let us see how to do that.

Bookmark your Obsidian vault folder in Scriptable

Scriptable needs to know where your vault is located on the file system of your device.

Scriptable calls this a File Bookmark. To add a bookmark, click on the settings icon in the upper left hand corner of scriptable.

In Settings, tap on File Bookmarks. Here you can define multiple File Bookmarks. A File Bookmark is a link to a file or folder on your device. This bookmark is needed later when configuring a widget.

Let us click on plus to add a new File Bookmark.

It will ask you to pick a folder or a file. You want to pick a folder, and the folder is the folder where your vault is stored. For example, I have a vault called TestVault and it is stored in my iCloud Drive under Obisidan. So the path is /iCloud Drive/Obsidian/TestVault, as shown in here:

Now you will be prompted for the name of the File Bookmark. I recommend making it the same name as your vault.

The end result will be a new File Bookmark and should look something like:

So in review, we created a File Bookmark, which is a bookmark to the folder where our vault is on the file system of your device. Now we move onto to the fun part, creating widgets on our iOS device.

Creating Your First Widget

Let us now place the Obsidian iOS widget on the screen.

• Start by adding a widget to your screen as you normally would and select the Scriptable widget from the list of widgets.
• Choose the size of widget you want, in this example we will choose the middle sized widget.

You should see this on your screen:

With the widget you just placed on your screen, go ahead and edit the widget settings. To get to the settings of this widget, long-tap the widget until the settings for the widget are displayed.

Now you need to provide the necessary values to the fields in settings. For the Script field, change it to Obsidian Widget. For the parameter, type in the name of the File Bookmark you previously made in Scriptable. In our sample case, we made a bookmark called TestVault and this bookmark is linked to our vault folder on the device.

The settings for this widget will look something like:

Settings for the Scriptable Widget

Go ahead and finish with settings.

Finally, this “Recent” file list requires the use of the Recent File List plugin available from the community plugin list. So if you don’t have that installed and intend to list recent files, you will need to install and enable that plugin.

The widget should now display recently edited files from your vault:

Scriptable widget displaying information from the Obsidian vault

If you click on a file name in the widget, that file will be opened in Obsidian.

As you can see, recent files are displayed in the widget. This is the default behavior for the widget and the widget can be configured to display other information from your vault.

More Ways to Configure Widgets

You notice that we typed in TestVault in the parameter of the widget. This tells the widget what vault to use. With some additional information in the parameter field, you can show different information.

Starred

To show all starred files from the vault, the parameter should look like this:

Notice that the Parameter field has additional information from the last widget we crated. TestVault is at the beginning of the Parameter, followed by two pipe characters, yes the ||. These pipes allow you to provide additional input information into the widget. In this case, the first detail is the vault name, the second detail is what data that should be presented. In this case we typed Starred for all the starred files.

The double pipes || may look confusing, but they simply separate the information we want to provide to the widget.

Also note, for the Starred feature to work, the Starred Core Plugin needs to be enabled in your Obsidian vault.

Folder

You can also display the files from a specific folder. The input parameter requires three elements:

1. Name of the vault
2. the term FOLDER — which tells the widget this will list contents of a folder
3. the folder path

Using our TestVault example, here is what this looks like:

Again, each of the values for Parameter is separated with two pipes ||.

In this example the folder is off the root of the vault and is called MC, so the last information provided in the parameter is /MC. When all put together Parameter has the following:

TestVault||Folder||/MC

Here is what the end result looks like:

File

The last display type shows the contents of a file. The input parameter requires three elements:

1. Name of the vault
2. the term FILE — which tells the widget this will display the contents of a file
3. the file path

Using our example again, the parameter would look like this: TestVault||FILE||Vacation Plans.md. Notice in this case that the file name ends with the extension.md. The end result of this configuration will display the contents of the file.

One important caveat

One issue with iOS widget is that they are not intended to be constantly updating. iOS wants to conserve battery and processing power and since widgets in general have static information they are not intended to be updating every few second or minute.

The Apple developer notes say they update on regular intervals based on the state and usage of the device. So some have concluded this can be about every 10 to 15 minutes.

The code example I present here tries to get the widget to update every 5 minutes. But there is no guarantee iOS will respect that. It updates widgets when its good and ready.

This means if you make changes to your vault, it might be a while before those changes appear in the widget. For those times when you really need to force an update, you can make a shortcut in the Shortcut app that uses the Scriptable “Refresh all widgets” command. It is not elegant, but it will work if you need.

Conclusion

We have seen that this widget can display four types of information:

• Recent files used in your vault
• Starred files in your vault
• Files from a specific folder in your vault
• The text contents of a file

The widget also supports all possible display sizes for an iOS widget.

While the initial setup takes a little work, once you have it setup it is easy to add new widgets. Also Scriptable syncs scripts between devices via iCloud. So if you get the script installed on one device, it will be available on your other devices.

If you need some help with this solution or suggestions for improvement, contact me at https://twitter.com/tfthacker.