Advanced image management approaches

I’m using linked PDF images in a project. I would like to be able to control their size, but I see this is not possible to do.

Is there an alternative vector graphic format to be used instead of PDF, and that can be resized in Scrivener? This should be as good for compiled eBooks and PDF files.

Also: is there a way to have images resized in different ways, depending on the Compile format? For example, I have linked screenshots in TIFF that look good at 100% in ePubs, while they are too big in PDFs.


The recommended solution is to create appropriately sized images using a tool other than Scrivener, and link them at Compile time. This approach allows you to have multiple sets of images as appropriate to different formats. See Section 15.7.4 in the Mac Scrivener manual for more information.

I see. This would however force to keep and manage more sets of images, with a great waste of space and time.

I’m currently working on a project featuring a bit less than 1,000 images. Having to consider PDF, HTML and ePub as outputs, it would mean 3,000 images to be kept up-to-date.

So, I think some alternative solution would work better for me. I don’t know, maybe some way of injecting markdown code in a styled page.


With that many images, I would think you’d be using an image editor already.

In any case, the section I referenced (15.7) also includes information about using images in Markdown workflows.

Yes, but this wouldn’t make having to deal with three times the data size and editing time less troubling. If possible, I would like to avoid having to do it, and let the editing/publishing programs choose the right size.

Also, I would have to replace the images in Scrivener depending on the type of output. I don’t see this as feasible.

I think I know the answer, having tried it: it is not possible to insert some markdown blocks into a document based on rich text styles? Or, maybe I’ve missed how to do it?


Another guess on this topic: maybe PDFs, like all other images, should be added as placeholder tags. A change of perspective for someone, like me, accustomed to work visually in InDesign.

By using placeholder tags, I can use alternative sizes right in the tag, or use replacements in the Compile format to replace. The integrated system is already dealing with this, allowing to enter a fixed-size value in points for most compile formats, and a percentage value for ebooks (therefore, for multipage HTML).

This is the example syntax shown in the manual:

<$img:Portait of Dickens.jpg;w=468;ebook=50%>


Pandoc, at least, allows you to pass attributes incuding width and/or height to images. Scrivener outputs a picture visually embedded in its editor (using the caption style next to the image to define a caption automagically) to markdown like this:

![Figure X: This is a caption][ref]


[ref]: image.png {width=400 height=300}

Indeed when you use Scrivener’s “Scale Image…” tool this information makes it to the compiled markdown.

With this therefore you can also modify the markdown before you translate to PDF and EPub. Whether you want to use image placeholders or markdown attributes depends on your workflow. The benefits of placeholder and replacements is everything stays in Scrivener. The benefit of markdown is more flexibility; e.g. you could use a script to calculate aspect ratios to size by width and calculate correct height automatically etc.


Something nice that I would like to see in Scrivener 4?

Insert a placeholder tag.
As an option that can be quickly turned on or off, preview the image next to the placeholder.


Just to reiterate a sentiment above, I can think of no reason to use Scrivener’s placeholder tag if you’re using Markdown. Scrivener’s placeholder gives rich text users a small amount of the capability we get. If you want to stipulate the size up front instead of in post, then use the method described in the user manual, in §21.4.2, under subheading Referencing Images with Document Links. But given how Scrivener compiles images in the Markdown workflow, you can handle sizes in post-compile automation as well! I do. There is currently a bug in the Windows version that causes the engine to believe a typesetting point is much smaller than it really is. I have to compensate by increasing the image sizes in the .md file by a set amount. When the bug goes away I can remove that line from my script. If I had switched to using Scrivener placeholders, or even Markdown image syntax, I’d have a lot more work ahead of me. So that’s something to consider, if your image scale problem can be applied evenly to large quantities of images (no wider than 450pts, say).

Myself, I mainly use images linked to the disk or the binder. The latter is better if there aren’t too many of them, as it’s a lot more convenient to have Scrivener manage the pool of illustrations than the file system. I use the former if there are more than 100mb of images, as I don’t want backup bloat.

With linked images generating Markdown syntax, I can, as part of the automated compile process:

  • Automatically swap out images for scalable PDF.
  • Swap out platform-specific varients.
  • Fall back to compressed production-ready JPGs.
  • Discard the thumbnail copy Scrivener compiled.

The Markdown-based workflow gives one a number of options that are difficult to achieve otherwise. Rich text users do have to juggle more files, I would say, and struggle around limitations such as using formats that don’t support scalable vector graphics. That alone can mitigate much of why you’d need to have multiple versions of a file. But having automation, with a tiered system that can adjust image sizes on the fly based on filenaming conventions, etc., is all stuff we can do.

That said, if you need to use a placeholder in the main text editor for some reason, just throw a hyperlink on it to the original in the binder, click on it if you forget what it is.

While I’ve been considering switching to pure markdown, I understand I probably can’t. So, I’m exploring a hybrid solution. And wondering if it is really possible.

My job mostly consists in describing images. Having them side by side is handy. I can’t exclude I could work with two programs side by side – the text editor (with images as placeholders), and the image editor (with the real images). Maybe it can even be easier, with the image not scrolling when scrolling text.

Coming from page layout applications means having to radically change my mindset. The advantage of programs like FrameMaker in the past, InDesign today, possibly Publisher tomorrow, is that one has total control on the final look of the page. If the manual’s appearance is to be considered part of the product design, this can’t be overlooked.

At the same time, developing huge technical books with InDesign is a torture. And a way for loss of control on the content, despite the nice look. That’s the reason for tools like MadCap Flare, and the modern attempts at refreshing FrameMaker. But they are clumsier than an agile glorified text editor like Scrivener, and not at the level of InDesign for visual flexibility and control.

The hybrid approach of Scrivener is what is tempting me. You outline, draft, write in an inviting environment. Yet you get a lot of power. As of now, all my technical works have started in Scrivener, and continued elsewhere when having to start mixing text and images. I would like to move all the work inside this light, nice, smart, creative tool, conceived for writers and not for visual artists (on one side) or engineers (on the other side). Making creation, editing and revision easier. And only leave the very latest adjustments to a page layout program, where to care about the finest details by editing the visual styles.

What I seem to lack is a way to – at the same time – deal with the images I’m describing, set them to the correct size for the various outputs, apply them a style that can be then recognized by a page layout program, and processed there. All while still working in a visually meaningful environment, instead of a set of control codes. It would be great to see an image, while still being able pass it some parameters that are now only reserved to placeholders.

But am I wrong to say that one either chooses markdown, or rich text? I seem to understand that, despite spaces for some hybrid elements, one has to go one way or the other. Want the full power of markdown? That’s the way. Want the visual clarity of rich text? You have to renounce to the most advanced features.

Am I wrong?


Yes, you are at least partially wrong. You can apply attributes including captions, styles and IDs to images and work visually in the Scrivener editor. You can see my Scrivener + Quarto Template for my solution to this:

The images are Binder-linked not embedded — therefore you can right-click to open them in an external tool and you can then refresh to see the updated image directly in the Scrivener editor. The caption is added visually underneath and in this case I’ve added an #ID and a .class to the image. In this workflow a post-processing script will move this to the correct place in the markdown. One could also split the image into a separate document in the Binder then use custom metadata to add the ID, class and any attributes, you could specify width and height there and then use the placeholders for the custom metadata at compile time.

1 Like

Thank you for the examples, but I still can’t see it fit in the workflow I’ve in mind.

Having to load the images in a Binder > [non-Draft] folder seems to me one step more that what I had in mind. It might become messy. At the same time, maybe I can consider this folder sort of a “Resource Manager” or “Links” pane in Publisher or InDesign. A way to have all the linked images listed a in a single place.

Then, can images added to the Binder be linked to external files? This is very important, both to make the Scrivener project much smaller, and to be able to quickly updated the linked images when they are updated in the referring product. Having to deal with hundreds images (that may become many more when thinking to the extracted details) this is of particular importance.

Another thing that makes me not totally convinced with this solution is the need for a script. Not being a software engineer, I can fear that when something is not working as expected I should solve it by editing the script. I doubt I would be able to do it when on a rush to come out with a manual.

I just noticed another thing that I might miss from this workflow: preflighting. It may happen that some images or links are missing. I fear the only way to check it in a long work is to compile for a page layout software, to use its preflighting features. I don’t know: maybe you can output both for Quarto and ICML starting from the same project? [EDIT: Missing images can be found in Scrivener, by searching for ‘MISSING_IMAGE:’. I don’t know if this can be done with missing links (xrefs, web links…).


The images in the Research section of the Binder are usually part of the Scrivener Project. BUT Scrivener does allow aliases to documents that live outside the project (§9.2 of the user manual):

In this case a macOS Alias is added to the Project, not the image itself. You can still use Binder-linking in the editor and see the image, but now Scrivener uses the Alias to retrieve the data that is outside the Project folder. You can still use the Binder to rename, organise and open the images. The two main downsides are (1) there is no preflighting, if an alias is broken there is no UI to help you fix it like. You must ensure the Aliases are valid, I’m not sure what Scrivener will do with a broken Alias (2) macOS aliases are pretty robust against moving around the filesystem, but will break if moving across computers (the manual give the details)…

1 Like

I’m not a software engineer either, but a biologist who had to learn to code to make his research easier, but yes if you don’t know how to program, a script will be unintelligible. The script is very simple, mostly just using regexes to move the attributes around and nothing more. But yes, this is a factor you have to integrate in you workflow decision.

If Scrivener had a mechanism to specify attributes for image blocks at compile this would remove the need for the script, another potential wish for Scrivener 4…

1 Like

I just tested the document + custom metadata method. I used ⌘+⌥+drag (macOS method to create an alias using a mouse drag) of an image from my Dropbox into the Binder research folder, then dragged from the Binder to the editor (make sure Preferences > Behaviours > Drag & Drop > Link to images dragged from binder into editor is turned on), to create an editor-linked image from the alias in the Binder. I added a caption, and edited custom attributes to identify the width and height. The caption contains ««AB»» at the start which is a tag that the compiler replaces with {<$custom:ID> <$custom:Class> <$custom:Attributes> width=<$custom:Width> height=<$custom:Height>} Placeholders add the values from the inspector metadata. So you can use aliased images and manage them using the Binder (tag them, view them, arrange them etc.), you specify the metadata for each image document using the inspector, and this all gets compiled to image attributes that get passed to EPub / HTML / LaTeX PDF etc.

So for example, this document with linked image and caption:

gets compiled to this PDF output (aligned right and 3cmx2cm in size):

You could use different metadata (i.e. widthPDF and widthHTML) entries for different compile targets if you wished (as HTML and LaTeX deal with image sizes differently), then select which compile replacement to use…


Just a note about image size, even if not vector but raster:

I’ve tried with assigning to the original screenshots a higher DPI/PPI resolution than the original. For example, maybe the original resolution is 72 dpi, and I had to resize it to something like 33% in InDesign.

I changed the image resolution to something meaningful, like 200 dpi, without changing its size in InDesign – or in Scrivener. If going for PDF output, this would allow decent-resolution printing, and no need for resizing in Scrivener as well.

However, this image may become too small for ebooks. If it is a linked image, it couldn’t be resized to be a bit larger. Again, the only common solution seems to be using the <$img:ImgName;w=400;ebook=50%> formula for placeholder tags.

Any change to use Styles or CSS in the Compile format page for ebooks, to selectively resize particular classes of images? Can classes be applied to selected images (without passing through the Binder workaround)?


Assigning a higher resolution will necessarily make the image smaller. The number of pixels available doesn’t change.

I know. My issue remains that the blanket remains too short: either it is of the right size for PDF and too small for ebook, or too big for PDF and fine for ebooks.

And the image resizing formula assigning two different resizing values for PDF and ebook works with placeholder tags, but not for linked images.


I assume you are talking about the native PDF and EPub outputs, and if so then indeed there isn’t much you can do except place a wishlist item for a way for the [Scale Image…] requester to specify the desitnation format.

If you were aiming to use a markdown workflow then as I mentioned, you could use custom metadata applied to images and get either a replacement or custom layout to swap widthPDF with widthEPUB depending on your compile target.

But I suppose the other point is that, for EPub and HTML shouldn’t you just remove any sizing information and use CSS to specify viewport-relative sizes? The idea of cm or px or pt is less clear in an EPub, so just specify like width = 75vw to make it 75% of the viewport width. Then different viewers with different viewports all get the same relative size compared to the page…


I keep all images external (except a couple I use as info while writing), with a simple Replacement rule scheme for compiling them as needed. I size them in Affinity Photo so Scrivener doesn’t have to. Replacement rules make it easy for Compile to retrieve files from any of several folders if need be: one dedicated to docx compiles, another for PDF compiles, another for eBooks, etc. I think it’s best not to let Scrivener take charge of resizing, and I don’t want the project to grow to gigabit size. Affinity Photo can do a much better job and let me supervise the process, perhaps converting them to B&W at the same time (with corrections if the default conversion is not very good).

managing images in Scrivener