linkFile([fileObject], embeddedId, [filename]) Last updated: 21. Jul 2026

Creates the link to an embedded file within a document.

Available in every #JS context — display templates, .hash pages, master pages and API scripts. Which overload you can use depends on the context: only a display template rendering a .docly document has a 'current document', so only there can you pass an embedded id on its own. Everywhere else pass the file object first (see the overloads below); the string-only form fails with a message telling you so, rather than emitting a link that 404s on serving.

Two overloads exist:
linkFile(embeddedId [, filename])
linkFile(fileObject, embeddedId [, filename])
The first links a file on the current document. The second prepends fileObject.Url, so you can link a file that lives on ANOTHER document — the row object from getFiles/getFolder in a listing — instead of building #f.Url#/#f.File1#/… by hand. The file object must have a Url property; without it the call fails rather than producing a broken link. This mirrors linkImage, which takes the same two overloads.

An options object also works: linkFile(f.File1, { filename: 'annual-report-2025.pdf' }) and linkFile(f, f.File1, { filename: f.Title + '.pdf' }).

The filename argument is the last URL segment — the name the browser saves the file as. It is decorative for lookup: Docly resolves the file from the document path and the embedded id alone, so you may put any descriptive name there. Omit it and the document name plus the source extension is used. The name is passed through as you write it — hyphens or spaces, your choice — and only URL-encoded; linkFile does not rewrite it. This differs from linkImage's scaled form on purpose: there the name is an SEO string for image search, where hyphens are the convention, while here it is the filename a person ends up with on disk. Never assemble these URLs manually — see the KB article Do not build file and image URLs by hand.

Parameters

Name	Type	Description
fileObject (optional)	object	Second overload only, and then the FIRST argument: a file object (a row from getFiles/getFolder) whose Url is used as the base of the link, so you can link a file stored on another document. Must have a Url property — the call fails if it does not. Omit it to link a file on the current document.
embeddedId	string	Embedded file ID for file to create link to.
filename (optional)	string	The name the file is served and downloaded as (the last URL segment). Decorative for lookup — Docly resolves the file from the path and the embedded id — so use a descriptive name. Passed through as written — hyphens or spaces, your choice — and only URL-encoded. Defaults to the document name plus the source extension.

Returns

A string with the link to the file.

Example

Code example (#JS)

#JS is mixed HTML (or other text file) with inline JavaScript with # starting and ending each inline statement.

A file on the current document:
<a href="#docly.linkFile(File1)#">Open file</a>

Use the download attribute to force download file:
<a href="#docly.linkFile(File1)#" download>Download file</a>

Give the download a descriptive name:
<a href="#docly.linkFile(File1, 'annual-report-2025.pdf')#" download>Download file</a>

In a listing, the fileObject overload prepends item.Url — link a file that lives on another document:
#let items = docly.getFiles('~/reports');#
#for (let item of items) {#
<a href="#docly.linkFile(item, item.File1, item.Title + '.pdf')#" download>#enc(item.Title)#</a>
#}#

Options-object syntax works on both overloads:
<a href="#docly.linkFile(File1, { filename: 'annual-report-2025.pdf' })#">Open file</a>
<a href="#docly.linkFile(item, item.File1, { filename: item.Title + '.pdf' })#">Open file</a>

Output

The #JS code above produces the output shown below:

No demo available