Start with a working image
You need a text editor, an image file, and a browser to follow along. No particular editor or browser version is required for the basic HTML in this guide. Put a file named workshop-desk.jpg in the same folder as your HTML page, then add this element: <img src="workshop-desk.jpg" alt="A laptop and notebook on a workshop desk" width="800" height="500">. Open the page in your browser to check that the image appears.
The src attribute tells the browser where to find the file. A relative path such as workshop-desk.jpg looks beside the HTML page; if the file is in an images folder, use src="images/workshop-desk.jpg" instead. File names and folder names must match the actual files. If you see a broken-image symbol, check the path, spelling, and file extension before changing the other attributes.
Write alt text for the image’s purpose
The alt attribute supplies text that can stand in for an image when someone cannot see it or when the file does not load. Useful alt text depends on why the image is on the page, not just what objects it contains. On a page about setting up a coding workspace, “A laptop and notebook on a workshop desk” may be enough. On a page comparing cable arrangements, the same photo might need alt text describing the visible cable placement instead.
Keep the description concise, but include information the reader needs to understand the surrounding content. You usually do not need to begin with “Image of” or repeat a caption word for word. If a nearby sentence already conveys everything the picture adds, the image may not need a second description. For a purely decorative image, use an empty value, alt="", rather than leaving out the alt attribute. This lets assistive technology skip an image that adds no information.
Context also matters for images used as links. If an image is the only content inside a link, its alt text should identify the link’s destination or action, such as alt="View the workshop setup guide". A description such as “Laptop on a desk” would not explain what activating that link does. For a chart or diagram with important details, a short alt value can name its main point, while nearby page text explains the details.
Set dimensions that match the image
The width and height attributes give the browser the image’s intended proportions before the file finishes loading. This helps it reserve space so later content is less likely to jump down the page. Use the image file’s pixel dimensions as the attribute values: for an 800-by-500-pixel file, write width="800" height="500". The attributes take numbers, not values such as “800px”.
Find the dimensions in your operating system’s file information or an image editor. Do not guess a width and height with a different ratio: an 800-by-500 image has the same shape as a 400-by-250 image, but not a 400-by-400 square. Setting a square width and height for that rectangular photo can distort it. If you replace the file with one of a different shape, update the attributes too.
Keep the image responsive
An image that is 800 pixels wide might overflow a narrow screen. You can keep its HTML dimensions and add this CSS rule to your stylesheet: img { max-width: 100%; height: auto; }. The image can then shrink to fit its container while keeping its proportions. The width and height attributes still tell the browser the file’s shape; the CSS controls how large it may appear in the layout.
If you do not want that rule to affect every image, give the element a class, such as class="article-image", and use .article-image { max-width: 100%; height: auto; } instead. This is useful when a page also contains icons or other images that need different styling.
Check the result in context
After adding an image, check the page at both a wide and a narrow browser width. Confirm that the image loads, does not stretch or overflow, and has appropriate space around it. Then temporarily change its src to a nonexistent file name and read the alt text in the page. This quick check can reveal descriptions that are vague, redundant, or unrelated to the surrounding paragraph; restore the correct src when you finish.
As a final review, ask three questions: What does this image contribute here? Would its alt text help someone who cannot see it? Do its width and height match the file’s proportions? Answering those questions for each image builds a reliable habit: images become easier to understand, and pages behave more predictably as they load.
