Relative paths to images

I have images imported using ‘insert image linked to file…’ rather than the regular ‘insert image…’. The problem is that these images disappear when I go from one machine to another, due to the use of absolute paths rather than relative paths. The images are in the same relative location with respect to my .scriv file (…/images/*), but the absolute paths are slightly different across machine because of different user account names.

So I’m wondering if it’s possible to specify the use of relative paths instead of absolute paths when inserting images.

This is not possible, all paths are absolute, and for that reason we recommend choosing a single computer to operate as your main compile station. Nothing is harmed by opening and editing a project with unresolved links, while away from it. When you get back they will resolve and be available for compilation again, so it’s only a display matter while on the go.

No worries. I do indeed have a single machine for compiling. What I might do is create a softlink directory in /Users/ of the correct username to make the paths resolve properly.

Symbolic links are what I used as well, when I could completely match the path name between machines. For a while I had two different primary user names (one at work and on at home) and I would use a symbolic link to mimic my user folder so that various scripts and absolute links could continue to function.

I love a good workaround!

What exactly do you mean by that AmberV?
Maybe you have an example? :slight_smile:

A symbolic link is a slightly lower level feature of your Mac (it is a feature of its UNIX core). You are probably familiar with aliases, which are similar in theory, but technically they are very different. In how they are similar, a symbolic link is a way of putting a “mirror” on your disk to another location. So for example if your user name is ‘fred’ on one computer, but it is ‘fredinchina’ on another computer, you could put a symbolic link called ‘fred’ that points to ‘fredinchina’, and now anything that is expecting ‘/Users/fred/Documents/something’ will be instead rerouted to ‘/Users/fredinchina/Documents/something’. The main difference between an alias and a symlink is that the former tracks the resource “beneath” the path. If the resource moves or has its named changed, the alias continues to point to that resource in its new location. A symbolic link on the other hand is nearly the opposite, it merely points to a location and it doesn’t care if anything is there or not. It will work if something is there, and it will patiently sit there and wait if something isn’t. So in that way it is similar to image links in Scrivener. If a picture is there, Scrivener will create a placeholder and use it. If there is no picture there, it just passively puts up a thumbnail and waits.

So, the geeky way to make a symbolic link is to fire up a command line (/Applications/Utilities/Terminal), and type in ln -s <original> <mirror>, substituting the two latter values appropriately. For example:

$ cd /Users
$ ln -s fredinchina fred

This would create a link such as described above from ‘fred’ to the real location ‘fredinchina’. But there are front-end tools that you can download that will make symbolic links for you so you do not have to mess with the command line, if you wish.

Thank you AmberV, very helpful :slight_smile:
What are these tools you are using to create virtual links?

I was vague on that because I don’t use any myself. I’m an old Linux hack so I’m comfortable using the command line on my Mac. :slight_smile: Try searching MacUpdate for “symbolic link”. If I remember right this one comes recommend by other forum users.

hehehe, I thought so; thanks :slight_smile:

I must weigh in on this subject.

I haven’t tried inserting pictures into my manuscript. However I have experimented with links in the Binder and links in Document References under the Inspector. Both are less than ideal. The Binder seems to use Apple’s mega-massive full-featured links (which can be significantly larger than the target file), and being Apple’s creation I wonder if they even work with Scrivener for Windows. The Document References links are tiny, human readable (if you dig into the XML), portable between platforms, and would be perfect if they weren’t absolute. Okay, “http://…” links need to be absolute since the target is a different machine, but “file://…” links do not (when the target is the same machine).

Absolute links destroy portability. They make it impossible to share .scriv files with other users. They make it impossible to share .scriv files across platforms. And unless one pays attention (or is lucky) when setting up an new account on a fresh machine, they generate a huge amount of work when moving between machines.

Symbolic links work, but they have their own issues. First, Scrivener needs to find the link. Which means you need to duplicate the directory structure from one machine to the other just so you have a place to put the links. Second, you have to manually maintain those links. Not too bad, unless you have hundreds of them.

When used properly file-relative links are dead simple. And they are portable between accounts, machines, and platforms. By file-relative I mean relative to the .scriv file. This is the “.” of both Unix and Windows. You might have a project directory named “Great America Novel” and in that you would have “Great American Novel.scriv” along with a few folders such as “pictures”, “maps”, “sounds”, etc. A successful relative link would be something like “./pictures/Betsy Ross.jpg”. By treating the “Great American Novel” directory as a unit, and moving it whole between machines, all file-relative links would work 100% of the time.

Of course the .scriv file is a directory that’s treated as a unit. So perhaps the coolest feature of all would be to get Scrivener to suck files into itself and store them there. Currently it seems as if all files inside the .scriv are relative to the .scriv. It’s been awhile since I explored Scriveners’ linkages. Perhaps I missed something the first time. I bet I did.

Ramble mode off.

Let me give a positive suggestion: I wish Scrivener did file-relative links whenever possible–or I that it sucked files into itself and treated them like any other file living inside of .scriv.

I’m not quite sure if I follow the overall thrust of your argument, but it sounds like you conclude that Scrivener’s ability to import items into the project by dropping them into the Binder is superior to creating an elaborate network of relatively linked resources via folders, meticulous kept identical between multiple machines?

If so, we agree. :slight_smile:

The whole point of the project format is to make for a portable singular resource that you can carry around from machine to machine, or send to a collaborator with everything intact. You don’t have to be a computer expert to set up a research system.

There are some good reasons for using links, both for binder resources and as inline images (the latter of which do not use Mac technology, that would not be possible, they are just text strings that are paths pointing to the picture file), but very few good arguments for why these links need to be something you can access everywhere. In cases where they must, I think putting in a few symbolic links to folders here and there to create a mimic system is fine enough. It’s a niche desire and trying to come up with a safe relative linking system that works cross-platform is going to be more trouble than it is worth. If you need that, import the stuff you need to have portable in to the project.

More or less. We do. That would be ideal.

I’ve been a Scrivener user for a little less than a year. I must admit I haven’t read every page of that 528-page PDF manual, but have only read sections as I think I need to know something. If I don’t think of it, I don’t learn about it. :frowning:

When I first picked up Scrivener I’d been using FreeMind on both Windows an Mac. It had taken me several years to work out how to organize my research, manuscript, character sketches, synopses, etc. FreeMind is almost exactly like the Binder–except it must be manually maintained (bad), and it makes no assumptions about file types (good).

Right away I tried moving all my stuff from my current project into Scrivener. The manuscript went well, the research did not–or at least it appeared to not transfer well. At that time I didn’t realize the .scriv “file” was really a directory. For example if I added a picture, the .scriv file grew by more than the picture file’s size, and .jpg flies seemed to have a fixed minimum size. Maybe it was copying the file to the .scriv directory. That would be perfect, despite the often times disproportionate growth in size.

I need to revisit how Scrivener “imports” files.

Relative Links Versus Absolute Links

For my current project I have the path: “system-specific-path-to-user-files/creative_writing/my_stories/little_red_feather/”. The “system-specific…” part of the path is different between my Windows desktop, my old Windows notebook (retired) and my new Mac notebook, but “creative_writing” and everything in it is identical. I even have an identical copy on my file server and on a thumbnail drive. I use the file synchronizer Unison (open source Win/Mac/Linux) to make it so.

In my “little_red_feather” directory I have “” (FreeMind) and now “little_red_feather.scriv”. All other files associated with that project also live inside that directory, and they never move relative to either the .scriv or the .mm file.

Under these constraints file-relative links always work 100% of the time, and absolute links only work on a single machine. Yes, there are other times when absolute links work and file-relative links fail. For example if I kept a single copy of my research files on my server (but then going to the cabin for a weekend of writing would be painful).

Which is why Scrivener needs to support both.

Bottom Line

If Scrivener works the way I’d like it to work, the way you imply it works, oh yeah! I’d love my project path to be: system-specific-path-to-user-files/creative_writing/my_stories/little_red_feather.scriv" with all project files inside the .scriv directory. Of course that would mean I abandon FreeMind. Which would mean I’d probably want a copy of Scrivener for Windows too. :smiley:

Despite that, if we need file links at all, we need both relative and absolute links.


What you might have done is dropped the JPEG file into a text editor, which is done for a different purpose than dropping it directly into the Binder. Any type of file can be dropped into the Binder at all. You can put Excel spreadsheets in there, PDF files, interviews and whatever else you have on your computer. It will even display a fair number of formats. Dropping a graphic file into a text editor, on the other hand, will convert it to PNG (which prioritises quality, so yes will be larger than a JPEG file in most cases) and embed it into the RTF file itself. This would in most cases not be a research move, but a production move. You want that file printed somewhere with some text.

So really, we can say there are four ways to bring an image into Scrivener (one of which is only available on the Mac right now):

  1. The JPEG is dropped directly into the Binder. When you click on it, you see the picture in the editor. It has all of the meta-data and notes that a text file does, off in the Inspector. The file itself will be copied or mirrored into the project filesystem. No bytes will be altered!
  2. The file is brought in via [b]File/Import/Research Files as Aliases...[/b]. In this case an HFS+ “Alias” is created, pointing back to the original resource, and the Alias is imported into the project in its stead. It otherwise acts just like case #1 above. You click on it in the Binder and it loads in the editor, you can open it in external editing software, add keywords and labels to it and so on. Yes, in some cases the alias might be larger than the original resource, but if the resource is that small then you probably aren’t linking it for reasons of avoiding project bulk.
  3. The picture is dropped into a text editor. As described above, the image is converted to the Portable Network Graphics format and embedded directly into the RTF file that is used to hold the data for that section of the binder. Since PNG is a higher quality format than JPEG, they will sometimes be larger, but you can be sure they will never degrade in quality. Meanwhile PNG is still compressed, and so while it is suitable for print, it doesn’t take up as much space as a typical print-ready graphic format. (True, TIFF is capable of compression via an add-on style system, but this is not nearly as cross-platform compatible as PNG, and probably not as future proof.)
  4. The picture is referenced in a text document with [b]Edit/Insert/Image Linked to File...[/b]. In this case a plain-text URI is printed as invisible syntax in the RTF file. When Scrivener encounters this code, it requests that the operating system grab the bytes from that URI and print them in the editor as the original picture. These bytes are cached during the session, but otherwise are not stored in the project and are refreshed whenever the project is reloaded.

So, those are your choices. Options #1 & #3 are ideal when the resource in question must be portable. If it must be seen by multiple parties on different computers, or if it must be accessible to you no matter where you go, then it makes sense to copy and import the full resource into your project. Since everything is contained inside the project, the act of copying the project to another computer will bring along all of the resources automatically. There is no need to maintain relative links and mirror folder structures between computers. This is one of the reasons, in fact, that Scrivener was designed at all in the first place: to make a central working space for the writer rather than having all of these hundreds of satellite files strewn about the operating system without any binding meta-data or central navigation between them.

For the two other options, these primarily allow one to continue having full access to the resources from software outside of Scrivener. While it is easy to open a resource in the Binder and hit [b]Ctrl-Opt-O[/b] to open it in its default editor (all changes being of course saved directly back into the project), sometimes you need direct access to those resources externally. Perhaps a script comes through every night and updates the files. Perhaps the files are on a company file server and multiple people access. Perhaps you only need placeholder illustrations in place until your graphic designer gets back with you. Replacing several hundred placeholder graphics with the final versions is a few seconds of work, whereas replacing several hundred embedded graphics scattered throughout hundreds of binder text files is a job that is going to take you many hours.

Finally in some less common cases there may be a desire to use file links where a bulk of resources is so massive that would be a burden to keep it all in the project. Someone might have several hundred gigabytes of research data for their thesis, and putting all of that into the project format is unwise as it means it will never be properly backed up. This particular use case is not compatible with what you are describing a need for, with relative links, anyway. That is the type of resource you have at your home workstation, not scattered all over the place.

The above options address, in my humble opinion, everything the average writer is going to need. Those that need to have one copy of a file shared by multiple computers, that absolutely cannot have that file imported fully into the project, are going to be a small minority. We’re really talking about unusual situations here, not common working practices. For most things, Scrivener’s curated system where links are implicit and all resources travel together in a singular package or folder is, for nearly everyone, not only adequate but a novel and elegant way to solve the problem of having your writing research and WIP scattered across multiple computers.

It also, incidentally, resolves the much less common desire to have a cross-platform solution to linking (something that is otherwise fairly problematic). Since Scrivener handles the data and the linkages seamlessly, using the Binder metaphor, it doesn’t matter what computer you load the project on. On every single one if you click on a JPEG file in the Binder it will pop up in the editor.

So I think your fundamental question is: why use absolute links at all for the things that do require links? Well as already mentioned, for one of the link types it’s not even a distinction between absolute or relative. Aliases are a feature of the filesystem itself that allow resource to be permanently linked even if the file is moved or renamed. That’s better than both absolute and relative links, for most users. Yes, since it is a function of the filesystem that does mean it cannot leave the filesystem—it cannot be brought to another HFS+ based computer, let alone NTFS or EXT4. But again, given its design purpose that’s not a huge deal. There aren’t many people that need the scenario you are describing, in our experience.

Let me be clear, in most cases I do agree with you. In most cases where one needs a link to something, relative works better. In other types of programs there are other use cases, and quite often relative links are the best answer to the problem. My contention is that Scrivener doesn’t fit into that type of role, and does not have those common use cases. It isn’t the file you give your publisher. It’s not the file you give to your readers. And in most cases where two or more people do need to use the project, putting the material into the Binder is more than good enough. Keep in mind that putting this project on a Dropbox (or similar) folder and sharing it with others is just as resource efficient as sending them a project with a separate “research files” archive, but more efficient for them as they don’t have to read your instructions on where and how to set up the folder to make sure all of the relative links work. Once Dropbox has the content uploaded and downloaded, so long as that content doesn’t change it won’t be constantly travelling back and forth. Since a project is a folder format, it’s not like these resources really bloat its transmission costs, so long as the transmission agent isn’t thoroughly stupid in how it moves data around. :slight_smile:

Maybe, but remember you can keep your FreeMind files in the Scrivener Binder, too. :slight_smile: But in short, it sounds like you are accustomed to a file format that must use links to handle research material. Scrivener is fairly unique in that it is a writing format that allows you to store 5 gigabytes of PDFs in it. The practices that may have evolved as a result of working with nexus formats that link outward are not necessarily applicable to Scrivener.

Thank you so much, Amber. Super helpful.

It’s been awhile since I tried putting resources into my project, but I suspect I tried the “File/Import/Research Files as Aliases…” technique. I know I didn’t do drag and drop. For the sort of work I do, 99.9% of the time I want resource files for the current project to be stored together with the current project. I really don’t care if the project directory contents are easily visible to other programs or not. BUT I may very well need to open the file in some other application and whatever is handling the file (Scrivener or FreeMind or whatever) needs to let the OS connect the file with the application.

Last year I tried putting several small FreeMind files inside of Scrivener. All worked at first, but then a couple of them stopped working after a few days. I think I used that “File/Import…” thing. I vaguely remember Scrivener tried to suck the text out of a PDF, which is why I don’t have any PDFs in my binder. Being a Scrivener newbie at the time I was probably doing it wrong.

I have a lot of things to try. I discovered snapshots a couple of days ago, so at the moment I’m going bonkers over that feature.

Thanks again.


It will indeed scan the PDF for usable text and add it to its internal search index if possible. This way you can search for terms in the PDF using the general project search. It will not alter the PDF though, or “suck the text out”. So I’m not sure what happened there. It could be the PDF itself was atypical and had display issues once you imported it. The file was fine, but wasn’t displaying correctly. If that is the case it likely wouldn’t display correctly in Apple’s Preview, either (we just use the same engine). At any rate we’ve made fixes to the PDF importer over the past year, so if you experienced problems a year ago, I’d give it another shot.

This is no problem. As an experiment, try dropping a JPEG into the Binder and click on it. As described before, you’ll see it loaded in the text editor. If you click on the folder you dropped it into, you’ll see it as a “Polaroid” on the Corkboard. While viewing the picture itself, check the footer bar. You’ll find an “Application” button in the footer bar. If you just click that, it will do the same as Documents/Open/in External Editor. It will just pass the file through to the OS and it will open in whatever is the default editor for that file. However if you click on the down-arrow beside the application button, you can choose from available alternatives (and Scrivener will even ask if you’d rather use that alternative indefinitely). So you have pretty much all of the utility that you would, having the file in Finder, in that regard.

Thanks AmberV, I just found your very clear explanation, (It is so good it should be in the manual!). :smiley:

I just converted all my images into links and see that in the epub (and hence mobi) all the images (except the cover) have been converted to PNGs.
Now I knew that was the case for GIFs but somehow foolishly assumed jpgs werent touched.
So I now realise that time spent choosing whether to create an jpg or a gif in Photoshop is a waste of energy and probably I should only create PNGs (apart from the cover).
Do you know if PNGs pass through untouched (if not resized)? Or are they changed in some way? I ask as I don’t know if it’s worth optimising the PNGs in Photoshop?

Somehelpful person on this forum (probably you or MimeticMouton) has already explained that GIFs are converted to PNGs and that I could subsequently change the file types and links in Sigil, but without doing this, am I right in saying that Scrivener itself can only create ebooks with PNGs?

Scrivener on Windows