Image Alt Text

It is a best practice to provide an alt attribute for images. This attribute is used to describe the image to users who are unable to see it. It is also used by search engines to understand the content of the image.

<img src="..." alt="describe the image here" />

However, this task can be tedious and developer are often tempted to skip it, or provide a generic alt text like “image”.

<img src="..." alt="image" />

The script

To solve this issue, we created a script that uses the OpenAI Vision model to analyze the documentation images and generate a description alt text.

To start, we assume that the script is run on a single image file and we use defImage to add it to the prompt context.

image-alt-text.genai.js

const file = env.files[0]
defImages(file)

Then we give a task to the LLM to generate a good alt text and save in a file.

image-alt-text.genai.js

...
$`You are an expert in assistive technology. You will analyze each image
and generate a description alt text for the image.

Save the alt text in a file called "${file.filename + ".txt"}".
`

Usage in Astro

The GenAIScript documentation uses Astro, which allows to author pages in MDX. The code below shows how the generate alt text, stored in a separate text file, is injected in the final HTML.

import { Image } from "astro:assets"
import src from "../../../assets/debugger.png"
import alt from "../../../assets/debugger.png.txt?raw"

<Image src={src} alt={alt} />

The debugger.png image shows the screenshot of a debugging session and the generate alt text file contents.

debugger.png.txt

A screenshot of a debugging session in a code editor with a breakpoint set on a line of code. The editor is displaying several panels including the watch variables, call stack, and a terminal output. The code is partially visible with a function definition and JSON configuration data.

Automation

Using the batch command, we can apply the script to all images in the docs in a single command.

for file in assets/**.png; do
  npx --yes genaiscript run image-alt-text "$file" --apply-edits

To avoid regenerating the alt text, we also detect if a file exists in the script and cancel accordingly.

image-alt-text.genai.js

...
// skip if alt-text file already exists
const txt = await workspace.readText(file.filename + ".txt")
if (txt.content)
    cancel("Alt text file already exists")

Full source

The full source looks like this:

image-alt-text.genai.js

script({
    title: "Image Alt Text generator",
    description: "Generate alt text for images",
    model: "gpt-4-turbo-v",
    group: "docs",
    maxTokens: 4000,
    temperature: 0
})

const file = env.files[0]

// skip if alt-text file already exists
const txt = await workspace.readText(file.filename + ".txt")
if (txt.content)
    cancel("alt text file already exists")

// context
defImages(file)
// task
$`You are an expert in assistive technology. You will analyze each image
and generate a description alt text for the image.

Save the alt text in a file called "${file.filename + ".txt"}".
`