Inserting images with alt text to compile for epub/html?

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.

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:


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
## heading 2

![Engelbart Caption]( "Alt Text Description")

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.


Brilliant, thank you.