Accessibility / Graphics

I can think of a way of doing this that involves using HTML directly, 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:

  • In the “Some Chapter” file there are three examples, all using the same basic concept to get the job done, but with a few different variations and techniques.

    1. The first example simply uses raw HTML. It is typed into the editor as desired, and that’s all you really have to do at this level.

    2. The second example demonstrates a possible way of avoiding raw HTML in the editor. Here we use a basic pseudo-syntax to give the name of the image followed by the alt text.

      In both examples a caption is provided. 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 purple highlighted areas (those are the “HTML Image” paragraph style markings).

    3. The third example shows how either technique could be used without a caption. Adding a caption isn’t required, and leaving one out won’t break anything.

  • The other important ingredient in the binder is that “images” file 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.

    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.

  • The rest of the magic happens in Compile. Head over there, and double-click the provided project format to examine its settings:

    • In the Styles pane, check out both “Caption” and “HTML Image”. They will have the Treat as raw markup setting enabled. This is important, 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.

    • The other thing they do is wrap additional HTML around the styled text, with the Prefix and Suffix fields. We put the <figure> element around the whole HTML Image range, and <figcaption> around text marked as Caption. (You won’t see all of the prefix/suffix for the HTML Image style, as I put carriage returns in there for prettier HTML output.)

      With these style settings, what you’ll see in the ePub source files is:

      <img src="images/test_image.png" alt="This is a test" />
      <figcaption>This is the caption.</figcaption>

      You could of course type all of that into the editor and just have the style set to treat the range as raw markup. But I like to keep redundant codes out of the way. If all of these are going to have the same stuff around them, why bother typing it in over and over?

    • That’s all you really need in fact, if the thought of typing in raw HTML doesn’t put you off. But if you want to see how the pseudo-code works, head over to the Replacements pane. A regular expression is used to perform complex search and replace throughout the document. It looks for text that starts with “!img(” and ends with “)” and then captures the two phrases within it that are separated by a semicolon (with an optional space after it). The two captured phrases are then inserted into what will be the final HTML, in the With field.

      If you wanted to use a different way of addressing images, have a look at some of the examples that are included in the stock “Ebook” compile format for a simpler syntax.

This example uses ePub3, but the approach itself could be adapted to the “Web Page HTML” output as well. Keep in mind there that the native text engine does not support HTML5, and I don’t know how well the figure and figcaption elements are supported prior to that. Some of the HTML itself may need to be tweaked to pass validation—I didn’t test it.

Lastly, all of this is automatically done if you use MultiMarkdown or Pandoc as a writing method. I know that doesn’t appeal to everyone, but it’s worth noting that you can type the following into Scrivener:

![Here is the alt/caption text](image_name)

With the “image_name” part being a document link pointing to an image in the binder, that’s all you have to do. No special compile settings necessary, but one would then at that point be using the HTML option at the bottom of the Compile For list, and need to install Pandoc to make use of the Pandoc ePub compile format, rather than using the rich text based options higher up in the dropdown.