Microsoft Word and deep linking?(Available in script version 281 and up)

In a PDF app the Hook “deep linking” works like this: When you click the link, Hook opens the file and jumps to the specific section of the PDF.

But this kind of deep linking does not seem to support Microsoft Word? When I link to a comment and/or a section of body text in MS Word, the Hook link only opens the MS Word document, but does no go to the specific section of the document.

Am I doing something wrong? And if Microsoft Word doesn’t support deep linking, is that something that will be implemented in the future? :crossed_fingers:t3:

Interesting question. You’re right that Hook does not support deep linking in MS Word. I don’t know MS Word well enough to provide much guidance on this right now. But I suppose this would require setting bookmarks in Word documents. Looking quickly I notice MS Word’s AppleScript dictionary supports setting bookmarks. there may be a way to go to Word bookmarks via automation.

It would be unusual for a Copy Link (or Copy Deep Link) command to modify a document, so we’ll need to think about this before we can comment more precisely. Maybe others will have suggestions.

1 Like

Incidentally, as a use case for Hook: I exported MS Office’s AppleScript dictionary to PDF and hooked it to this post, and to a related web page, and our internal ticket regarding this.

1 Like

Thanks for looking into this, LucB.

I’ve tried numerous times to create Deep Links in MS Word through Bookmarks and Headline sections, but in vain.

Do you think this could be implemented in a future update of Hook, since - as you wrote - “MS Word’s AppleScript dictionary supports setting bookmarks. there may be a way to go to Word bookmarks via automation”?

We haven’t looked into it yet. Hook is scriptable so anyone in the Hook Pro community can dig into it and if it is possible can propose a modification to Hook’s Get Address script for MS Word. I imagine people who do automation tend to avoid MS Word , but some people have to use MS Word regardless of their preferences.

These are the scripts I use, but they could doubtless be improved (in particularly using a random number as a unique id is obviously bad, but for purely personal use the risk of collisions is too low to justify the time investment in writing something better).

Open Item

This text will be hidden

use framework "Foundation"

use AppleScript version "2.4" -- Yosemite (10.10) or later
use scripting additions

on urlDecode(input)
	tell current application's NSString to set urlString to stringWithString_(input)
	set theDecodedURL to urlString's stringByRemovingPercentEncoding -- 4 is NSUTF8StringEncoding
	return theDecodedURL as Unicode text
end urlDecode

set fullURL to "$0"
set bkName to ""

set AppleScript's text item delimiters to "#"
set urlPath to text item 1 of fullURL
if (count of text items of fullURL) is greater than 1 then
	set fragment to text item 2 of fullURL
	set AppleScript's text item delimiters to "&"
	set kvs to text items of fragment
	repeat with kv in kvs
		set AppleScript's text item delimiters to "="
		set k to text item 1 of kv
		set v to text item 2 of kv
		if k = "bkName" then
			set bkName to v as string
		end if
	end repeat
end if

set fpath to urlDecode(urlPath)
set text item delimiters to "/"
set fn to text item -1 of fpath
set len to length of fpath
set fpath to text 8 through len of fpath

tell application "Microsoft Word"
	open fpath
delay 0.1
	set bkMark to bookmarks of active document whose name is bkName
		select (item 1 of bkMark)
	end try
end tell
Get Name
tell application "Microsoft Word" to get name of active document
Get Address
use framework "Foundation"

use AppleScript version "2.4" -- Yosemite (10.10) or later
use scripting additions

property NSMutableCharacterSet : a reference to current application's NSMutableCharacterSet

on urlEncode(input)
	tell current application's NSString to set rawUrl to stringWithString_(input)
	set charset to NSMutableCharacterSet's URLQueryAllowedCharacterSet's mutableCopy
	charset's removeCharactersInString:"?"
	set theEncodedURL to rawUrl's stringByAddingPercentEncodingWithAllowedCharacters:charset
	return theEncodedURL as Unicode text
end urlEncode

tell application "Microsoft Word"
	set n to name of active document
	set f to full name of active document
	set ppf to POSIX path of f
	set selectedText to selection
	set bkName to "AS" & ((random number from 0 to 1.0E+8) as integer)
	make new bookmark at active document with properties {name:bkName, text object:text object of selectedText}
end tell

set x to "[" & n & " bkMark: " & bkName & "](" & "file://" & urlEncode(ppf) & "#bkName=" & bkName & ")"

@LucB Three points more generally:

  1. As with my PDF Expert script I’ve had to use a ‘Get Name’ script even though I’m returning a markdown link from the ‘Get Address’ script.
  2. Lots of the scripts end up having to roll their own URL- and key-value- coding procedures; it might be worth looking into whether it’s possible to let the scripts take/return a record with the relevant parameters, and then have Hook do the URL handling itself?
  3. One disadvantage of deep-linking is that currently you lose the context of what has been hooked to other parts of the document (or to the document as a whole). This is particularly severe here, because the granularity of the deep-link is a particular text range (not even a page, as with the PDF scripts). It might be useful if the interface could show both hooks to the link itself and other hooks with the same base URL? (I have toyed with having the ‘Get Address’ script itself create a non-deep-linked hook, and then hooking that and the new deep link together, but unsurprisingly calling Hook’s AppleScript dictionary from within a Get Address script seems unreliable!)

I have copied layerboy’s script but it doesn’t seem to work. Hook says “no linkable items found in Microsoft Word”. What am I dong wrong?

1 Like

Sorry for the delay. The recent comment by @yfs made this pop up again on my radar. Congratulations regarding this.

I wasn’t aware of that. Maybe a dev here would know. Do you recall the particular reason why you needed both.


When we introduced deep linking, we had a big debate internally about whether to show all the links and pulled back from it. I think giving users the choice with a command is probably the best way to go.

@lawyerboy : I tried to follow the instructions a few times, but in vain. But tonight I tried again and, wauw, it worked. I can now deep link to EVERY sentence in a Word Document. FANTASTIC! - THANK YOU SO MUCH! Gonna be a huge win in finishing my PhD!!

I have, however, one problem with MS Word Deep Link from two critical applications I use all the time. You see, when I link to a Word document with your code (Open Item - Get Name - Get Adress) it works perfectly fine when linking to another Word Document or linking from Apple Notes or Dynalist. When you click on the MS Word Hook link, the document pops right up at the exact line.

But when I click on the hook link to a Word document within Things 3 and Evernote Legacy, the Word Document then does not pop up, but is being activated in the background - behind Things 3 / Evernote. So I have to minimize these two applications in order to get to the Worrd Document I just clicked on with the Hook Link. Hmm … :thinking:

How can that be? I hope that just a minor fix to your otherwise wonderful code would be able to fix this problem with MS Word Deep Links being activated from within Things 3 / Evernote? :pray:t3:

Thanks - glad to know it works. I think there are still some bugs to work out, and I will try to do another version, but I don’t have time right now! I’ll have a look at what’s going on with Evernote but you could try putting tell application "Microsoft Word" to activate at the bottom of the open items script.

OMG, “tell application “Microsoft Word” to activate” DID IT. It now works 100 % perfect with . You truly are a lifesaver, @lawyerboy :+1:t3::star_struck:. I should dedicate a special thanks to “lawyerboy” in the foreword of my dissertation! :laughing:

I am a total noob on Mac. When you have the three scripts, should they each be saved separately? in fact if you want to be really kind, could you outline the steps to make this work on the Hook, Words and Things sides?
The technical details I can look up but I don’t understand how all this hangs together, and it is tantalizing (and btw - look also at LiquidText - awesome out of the box)

Welcome to the Hook Productivity Forum , @Alceste .

Hook’s scripting is explained here: Creating and Modifying Integration Scripts – Hook.

Hook’s scripts go in Hook > Preferences > Scripts Tab > App

1 Like

Can you give some detail about how did you get the deep link?
Thanks a lot

Can you perhaps post the script here so it can be copied/pasted? I have no idea what I need to write to make this happen…and it’d be huge for my workflow if I can get this to work.


1 Like

Hello again lawyerboy,

I have a follow-up question if I may:

When I deeplink to a MS Word document from other applications – let’s say Things 3, Apple Notes, Evernote, you name it – it works perfectly fine with your script. Thank you!

However, if I put the same Hookmark deeplink into a MS Word document then it doesn’t work. In other words: let’s say I want to link to another section of a MS Word Document or another MS Word document and I therefore put a Hookmark link in a MS Word Comment. When I click on that link, it opens up the other document, but does not go to the deep link location. But if I copy the very same link to say Apple Notes, Things 3, etc. then the deep link works perfectly fine.

How can that be? Do I have to add something in →Open item | → Get Name | → Get Address in order to make sure that the deep links also work in-between MS Word documents? :thinking:

All the best,

Folks, Is there an update on the best way to achieve deep linking into specific text in a Microsoft Word document using Hookmark please? I’d like to use Hookmark to generate a hyperlink that enables a jump from an application outside MS Word, to a specific destination inside the Word document. If the default Microsoft Word-related scripts in the Hookmark preferences do that (ie the ones in the “Get Name” and “Get Address” areas of the Hookmark scripts setting), might someone be kind enough to explain please how to initiate those scripts. It would be amazing to get the specific steps to set them up initially, and then the keyboard command to routinely invoke the scripts to obtain links into MS Word. Thanks!

@lawyerboy Thank you very much for your contribution! I have integrated your scripts into Hookmark. It is available for anyone who is interested in MS Word deep linking.

One minor change is the script checks if there is any text selection. If no text is selected, Hookmark will just create a regular link. If people prefer getting a deep linking regardless of text selection, I can take out this change.

@jasonromney Please update your script and see if it works ok. The latest version is 281.

Thank you

Thanks bchend. Can you describe how to actually initiate the script from Hookmark please? What I’d appreciate your guidance on please is: What action needs to be taken by a Hookmark user to create a link that can be pasted into some/any application outside of Microsoft Word that will enable a hyperlink jump back to a specific location within a Microsoft Word document please?

If you want to create the link that’s for a specific location, please select some text at that location before you invoke Hookmark.

Thank you

1 Like