I can think of a few different ways of doing, though it does require one to do a small edit to the eBook file after compiling. Take a look at the example project while following along with these notes.
image_accessibility_samples.zip (224.9 KB)
Composition and formatting notes
-
We start with the most straight-forward example, in the “Raw HTML Example” section. This demonstrates the actual image syntax we want to use an ebook, and what we’ll be aiming for with more streamlined methods. On its own, it will be for most the least practical for every-day writing, but I suppose if one only has a few images in total, it might be more efficient to use this method, than build something more involved.
You don’t need any setup for this, other than creating a styled called “Raw HTML Block” in your project. The stock Ebook compile Format comes with a matching style that is already set up to do what we want: pass the text through as direct HTML.
-
Moving on to the “Styled Text” section, we will see one possible way of avoiding raw HTML in the editor. We are using two styles to generate the necessary HTML, first to give the image name, followed by the alt text.
In the first example a caption is provided on the following line. This is using a character style instead of a paragraph style, as the default setup in Scrivener does. We need that because we want to insert the caption into the HTML that will be added around the both of these lines. The “Figure” paragraph style, applied to both lines, will be responsible for doing that.
Refer again to the first section, to visualise how these styles all work together, by adding prefix and suffix text around what we see in the editor. The areas highlighted in purple are what we type in, while the compiler inserts all of the necessary text around them (and uses Replacements to fix our shorthand syntax for image sizes).
Moving on to that, there is a second example in this section that shows two different capabilities:
- The image size can be stipulated by typing in " @ width x height after the image name, within the style range for that. Thus when you examine this section in the compiled output, the two images will have slightly different sizes, since its natural size is 172 x 174.
- We also demonstrat how the caption line is optional. Leaving it out on this second example will not break the figure HTML.
-
Lastly, in the “Image Sections” demonstration, we show a technique that ought to work fine on both platforms, but given multiple competing bugs in the Windows version, presently only works on Mac.
- If you don’t treat text groups as folders in your settings, then manually press ⌘1 / Ctrl1, to view this section as intended.
- The notion of using special Section Types for figures is not unusual, and has other benefits than what can be done with them when compiling. We could for example create a search collection that looks for all items tagged with the “Figure” section type, and get a handy list of all illustrations in the work.
- In this case we are using the image’s filename as its binder title, which will be used by the compiler to help build the HTML. That is technically all we need, in fact. The image itself in the editor is cosmetic, and for our benefit while writing.
- Open the Inspector’s Metadata tab to view optional fields. We have a field for the Alt text, the Caption, and we can also give the image a relative scale based on the width of the display. This is of course just an example, we could have width and height fields if we wanted, or even a block where we could put our own custom CSS, or a custom metadata dropdown to influence its layout (right float with the text wrapping around it, for example). I.e. this concept can go a lot further than just supplying Alt text.
Some might find this approach better than styled text, because it provides a very similar feel to how one would work with images in the simpler and more limited fashion. On the other hand, others may find the concept of outlining in the draft to this level to be a bit much. Something to consider is that these figure items can be placed outside of the draft, and then inserted into the text with the
<$include>placeholder.[1] -
Lastly, we move on to the “Images (remove me)” section at the bottom of the Draft. This is a necessary technique to actually get the images in the book. If you don’t put the image into a file somewhere so that Scrivener processes it and exports it into the eBook, then these plain-text HTML requests for images won’t do anything except generate broken links. (Remember the image in the “Figure” section type will not export, it is just for us to see it easily.)
So this is the one point I mentioned earlier where a small amount of post-compile editing is necessary. Thankfully it’s pretty simple: you just open the .epub file in Calibre Editor or Sigil, locate the final document that contains the dummy images, right-click in the sidebar and delete the section from the book. This will also update both the visible ToC and all internal references to the file. Save it, and you’re done.
Compile settings
To see how these methods are put together, open File ▸ Compile..., and double-click the selected “Ebook (Alt Images)” Format, in the left sidebar, to examine its settings:
-
In the Styles pane, click on the “Figure” paragraph style. The Treat as raw markup setting is enabled, otherwise Scrivener will escape all of the HTML codes and you’ll end up being able to read them in the output, rather than have them function toward their intended purpose.
-
Next, it adds additional text around the styled lines of text, with the Prefix and Suffix fields. (You may not see all of the prefix/suffix, as I put carriage returns in there for prettier HTML output.)
-
Scroll down in the style list, and click on the “Image Name”, “Figure Caption” and “Image Alt Text” styles. The name and alt text styles are necessary, as they make the first line within the “Figure” block a valid image reference. The caption style is self-contained, on its own line, which is how it can be optional while writing.
All of these styles together help produce the text shown in the “Raw HTML Example” section.
-
Next, in the Replacements pane there is a RegEx replacement added at the bottom which looks for text matching the “@ 1 x 1” pattern, and turns it into
width="1" height="1". -
Lastly, we have the Section Layout that was used to turn a binder title and some custom metadata into an image. The text is being inserted by the Title Prefix and Suffix fields, in the Title Options tab. This is fairly straight-forward, where the title (the image’s file name) is inserted in between these two chunks, and the use of custom placeholders to insert other settings is done in the suffix.
So this is where you could modify how that boilerplate works, if you wanted to use image dimensions instead of a relative width, etc.
Refer to §10.1.5, Including Text From Other Documents, in the user manual PDF. ↩︎