Attachments
An attachment is a file that hangs under a reference; it can also exist on its own, without a parent reference.
Stored files and linked files
- Stored files are copied into the library's
storagedirectory and managed by the library; they move along with the data directory when you move or back it up, see Data Directory and Backups. - Linked files only record where the file is on your computer; the file itself stays where it was. If the file is moved, renamed or deleted, the attachment can no longer be found. Keeping linked files under the Linked Attachment Base Directory makes them easy to find again when the whole folder moves.
- Links to a web address have no file; they are opened in the system browser.
To bring linked files into the library, select the attachments or their parent references and use Tools > Manage Attachments > Convert Linked Files to Stored Files…. The title, note, tags, annotations and relations of each attachment stay as they are; only the file is copied into storage. With "Delete original files after storing" checked the file is moved instead, and no copy is left where it was. Attachments whose original file cannot be found are not converted.
The attachment file cannot be found
When you open an attachment whose file is not there, a File Not Found window shows the path the application looked for. The usual reasons are:
- a linked file was moved, renamed or deleted, or the disk it is on is not connected. Put the file back where it was, or click Locate… and point to where it is now;
- a linked file is in iCloud Drive and the system moved it to the cloud to save space. No window appears in this case: opening the attachment asks the system to download it, and if it arrives within a few seconds it opens as usual; otherwise it is shown in the Finder, and you can open it again once it has downloaded. Meanwhile the reference table shows it as missing;
- the data directory of the stored files was changed, or the
storagefolder inside it was moved or cleaned up by hand. Check that the corresponding folder is still in the data directory; - the library was restored from a backup, and backups do not contain attachment files.
Choosing a file with Locate… relinks the attachment to it; its annotations, note and tags stay on the same attachment. For a stored file the chosen file is copied into storage; for a linked file only the recorded location changes. With a Linked Attachment Base Directory set, the application first looks inside it for a file with the same name, dropping the leading folders of the old path one at a time, and asks whether to relink it; if other linked attachments from the same folder are found there as well, it also offers to relink them all.
In the reference table the Attachments column is dimmed when the file cannot be found. Once the file is back, opening the attachment again checks it afresh. CiteDesk deletes only the files of attachments that it deleted itself; it does not clean up your other files because of one error.
Linked Attachment Base Directory
Choose a folder under Linked Attachment Base Directory on the Advanced page of the settings (for example the folder that holds your PDFs), and linked attachments inside it are saved with paths relative to it. If you later move the whole folder, choose it again in the settings and, as long as the structure inside the folder is the same, every attachment is found again without relinking them one by one.
When you choose a new base directory, the application first tells you how many attachments were found within it and how many within the old one will go back to absolute paths, and changes nothing until you confirm. Revert to Absolute Paths… converts all linked attachments that use relative paths back to absolute paths and then clears the base directory. The base directory cannot be inside the data directory.
Attachment title and file name
The title of an attachment and its file name are two different things: the title is the name shown in the reference table and the right pane and can be changed freely without affecting the file on disk; the file name is the name on disk, managed by File Renaming according to a template. For example, when you add a file under a reference and it is the only file of its kind in that reference, the title becomes a default one such as "PDF" instead of the file name. You can edit the title directly whenever you need to.
With Show attachment filenames in the reference list turned on (Attachment Titles on the General page of the settings), attachment rows in the reference table show the file name instead of the title (web snapshots whose title contains "snapshot" keep their title). Attachments brought over from Zotero sometimes have titles that were changed to match their file names; select them or their parent references and use Tools > Manage Attachments > Normalize Attachment Titles… to give attachments whose title matches the file name a simple title again: the primary attachment of a reference gets a default title such as "PDF", the others the file name without its extension. This can be undone.
The reader
Double-click a PDF, EPUB or web snapshot attachment to open it in the built-in reader, where you can highlight, underline, add notes, draw shapes and ink; annotations are stored in the library and the original file is not modified. Attachments in the library's trash, or whose parent reference is in the trash, open read-only.
Annotations embedded in a PDF attachment can be imported into the library, and the library's annotations can be written into an exported PDF (File > Export PDF(s)…). A web snapshot is a single HTML file saved as a whole page.
Full-text indexing
The full text of PDFs, EPUBs, web snapshots and text-like attachments is indexed in the background for searching in the Everything mode. The Full-Text Cache section of the Advanced page of the settings limits how many characters and pages are indexed per file, and Index Statistics shows the progress. Encrypted PDFs, or files from which no text can be extracted, are recorded as not indexed; their body text cannot be searched, but nothing else is affected.