I imported and linked some graphics into my novel and it occurs to me that there is critical text in the graphics that should be available to screen readers (alt=some text) style. Is there a way to add accessibility text for images for digital compiles? The text itself should not be visible “normally”.
I’m afraid that macOS provides no facility for doing this in the text system that we use.
All the best,
Keith
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. ↩︎
Thank you !!!
I’m working on a series of tutorials about web accessibility. Each tutorial will include several images throughout the text, typically screenshots. The content prepared in Scrivener will be compiled to HTML to be used on the website, and also compiled to ePub for people to access offline. I typically create content using Markdown, but am open to other suggestions.
What I need to know is how to insert images, and ensure that I can add alternate text for these images, which will carry over once the content is compiled. I’ve been looking through the forum and online writings about Scrivener and I’m not seeing this anywhere.
Any suggestion would be greatly appreciated.
As a follow up - I ought to point out that I tried the following:
- Adding the HTML img tag with the alt attribute. This is rendered with correct tags in HTML. The image is not rendered when compiling to epub.
- Using MultiMarkDown image format. This is rendered with the figure tag around the the image tag in HTML. The image is not rendered when compiling to epub.
- Using the <$img:image-name-path;> tag format. Does not render in either HTML or epub, whether I use an image in the project or refer to an image on my hard drive outside the project.
- Dragging an image directly into my document. This renders in both HTML and epub. With alt text defaulting to “image” and no obvious way on how to include custom alternate text, or leave the alt attribute with an empty value if the image is decorative.
I feel I’m missing something here, but I can’t put my finger on it. Surely there’s a way to include images that can be rendered both when compiling to epub or compiling multimarkdown to html, and lets us add alternate text?
I have the same issue. Did you ever find a solution to add alt text?
What’s meant by “alt text”, @vavroom? What’s the purpose of it, and what would it look like? Do you mean you want two compile options, one with the image and the other with the alternative text?
alt text is “alternate text”. it is an attribute in HTML for when you are inserting an image in an HTML document or web page, you can describe the image for people who are blind and rely on assistive technologies that “reads the screen” for them.
Because I’m using Scrivener and MultiMarkDown for all my content creation, including compiling to web or to epub, I need to be able to plan for the images I’m using to have alternate text.
The final markup in HTML might look like:
<img src="some-image.png" alt="Clear and concise description of the image">
But I need to be able to write that in multimarkdown in my Scrivener and have the app compile the information appropriately.
It’s a “description” or “caption”, then. “alt” doesn’t mean anything outside of the weird HTML notation.
It’s not as easy as that :). Even without harping on why accessible digital materials are good digital materials, KDP states:
Accessibility: For accessibility, all images must have text in the alt attribute in the HTML tag. For decorative images, set alt = “” or role = “presentation” in the image tag so that it can be ignored by assistive technology. Alt text should be short, concise and specific. Alt text should provide a description of the image and it’s meaning in context as appropriate. For linked images, provide the purpose of the link rather than description of the image in alt text.
https://kdp.amazon.com/en_US/help/topic/G75V4YX5X8GRGXWV
It’s a bit disappointing that you cant do this in Scrivener … Accessibility in digital media is a topic since 2005 and not just yesterday … :(.
Have a look at this post; although the macOS text system limits what Scrivener can do directly, Ioa wrote up instructions a while back and provided a sample project to demonstrate a way to add alt text to ebook images:
https://forum.literatureandlatte.com/t/accessibility-graphics/42038/3?u=mimeticmouton
3 Likes
Thank you! I think the way to go is to add the alt text in the raw HTML. I have looked into Sigil and Calibre before and I might give it another go … but at this stage only if KDP’s quality control rejects the epub as it is now and the Kindle preview app doesn’t seem to mind :)! I also added a wish list item to allow meta data for images at some time in the future.
Can macOS Scrivener (or TextEdit or any Markdown editor) and Marked 2 get around this?
# heading 1
Blah-de-blah
## heading 2
Here is some more text.
Well, no. It’s not a caption - a caption is something entirely different. And while a “description” might be a way to describe this, I used the correct vocabulary. I’m looking for a way to implement alt text in the image element in HTML, from Scrivener MMD.
I use the term “alt text” because that’s what I need.
A caption, in HTML, isn’t processed the same way as alt text by screen readers.
I’m sorry if my use of technical accessibility terms isn’t matching your expectations, but as a guy who has worked in the field of digital accessibility for 25 years, I’m going to use the correct terminology.
2 Likes
Brilliant, thank you.
I studied the 2022 post of satisfying KDP’s “For accessibility, all images must have text in the alt attribute in the HTML tag” requirement. Did anyone ever come up with a way to satisfy this? I haven’t submitted the final yet, so don’t yet know if they are requiring.
See the post that @MimeticMouton referenced, here: Accessibility / Graphics - #3
In fact I’ve merged these two topics together, since it has been linked to twice now from this discussion, and the topics are essentially identical queries anyway. The post is now up there, toward the top.
That said I can think of maybe a better way of doing this, and the original post was missing its example project anyway (I guess I forgot to attach it). I’ll put together an update.
1 Like
Thanks for posting, but I think I’m missing something. The post says “Take a look at the example project while following along with these notes:”
Where would I find the example project that’s being referring to?