MSK Institute • Shikohabad
Loading Page Content...
Preparing courses, live labs, and learning resources.सामग्री लोड हो रही है, कृपया प्रतीक्षा करें...
Connecting serverPlease wait...
💻 Practical Labs🚀 Free Demo📜 Verified Certificates
Images, Alt Text & Captions0%
Images, Alt Text & Captions
Beginner12 min read•Updated: Jul 11, 2026
Visual assets—such as architectural diagrams, UI mockups, and charts—make technical documentation engaging and easy to understand. In Markdown, image syntax is closely related to link syntax, differentiated by a single leading exclamation mark (!).
Click to Zoom1. Basic Image Syntax
To embed an image in Markdown, prefix the link syntax with an exclamation mark (!):
- The Exclamation Mark (
!): Tells the parser this is an embedded image, not a clickable text hyperlink. - Square Brackets
[ ]: Contain the Alt Text (alternative text used by screen readers and displayed if the image fails to load). - Parentheses
( ): Contain the image source path or URL.
Optional Image Title:
Just like links, you can include an optional title displayed on hover:
- HTML Output:
<img src="/images/git-flow.png" alt="Git Architecture Flowchart" title="Git Branching Workflow Diagram" />
2. Writing Accessible Alt Text (A11y Best Practices)
Alt text is essential for web accessibility:
- 1Screen Readers: Visually impaired developers rely on screen readers that read the alt text aloud.
- 2Broken Images: If an image fails to load due to network errors, the browser displays the alt text in its place.
- 3SEO Ranking: Search engines crawl alt text to understand the context of documentation images.
| Bad Alt Text (Avoid) | Good Accessible Alt Text |
|---|---|
 |  |
 |  |
3. Clickable Image Links (Image inside a Link)
Often you want a badge, logo, or diagram preview to be clickable (e.g., clicking a thumbnail opens the full-resolution diagram, or clicking an npm badge opens the npm package page).
To make an image clickable, simply wrap the entire image expression inside a standard link:
[](https://github.com/msk/api/actions)
4. Controlling Image Dimensions (Width & Height)
Standard Markdown syntax does NOT provide native properties for adjusting image dimensions (like width or height). When you need to scale an image down (e.g. A logo that renders too large):
Use Raw HTML <img>:
<img src="/images/tutorials/markdown/markdown-parsing-rendering-pipeline.svg" alt="Pipeline" width="600" />
Raw HTML is 100% valid inside Markdown documents and gives you exact pixel control!
Interactive Quiz
Multiple Choice Questions
Question 1
What character distinguishes Markdown image syntax from standard hyperlink syntax?
Question 2
In '
Database Schema', what purpose does the text inside the square brackets serve?
Database Schema', what purpose does the text inside the square brackets serve?Question 3
How do you create an image that functions as a clickable hyperlink in Markdown?
Question 4
Why does standard Markdown lack native width and height controls for images?
Question 5
Which of the following is an example of high-quality accessible alt text for a code diagram?
Next Lesson
Embedding Raw HTML & Media in Markdown
Continue learning with hands-on practice, examples, and exercises in the upcoming topic.
Related Lessons
| Previous Lesson | Next Lesson |
|---|---|
| Links: Inline, Reference & Automatic URLs | Embedding Raw HTML & Media in Markdown |
Practice Quiz
Test your understanding of this lesson with 5 questions. Each question has one correct answer.