How to Add Links and SEO-Friendly Images in Markdown (Markdown 101 - Part 04)

// SERIES: Markdown 101 (10 lessons · Jump to any part)
  1. 01 Capstone Practice - Write a Complete Markdown Article from Scratch (Markdown 101 - Part 10)
  2. 02 How to Add Links and SEO-Friendly Images in Markdown (Markdown 101 - Part 04)
  3. 03 How to Create Tables and Horizontal Rules in Markdown (Markdown 101 - Part 07)
  4. 04 How to Preview and Publish Markdown Posts to Hugo on GitHub Pages (Markdown 101 - Part 06)
  5. 05 How to Use Obsidian Callouts and Wikilinks and Export Cleanly to Hugo (Markdown 101 - Part 09)
  6. 06 How to Write Checklists, Footnotes, and Escaped Characters in Markdown (Markdown 101 - Part 08)
  7. 07 How to Write Headings, Paragraphs, and Emphasis in Markdown (Markdown 101 - Part 02)
  8. 08 How to Write Lists, Blockquotes, and Code Blocks in Markdown (Markdown 101 - Part 03)
  9. 09 Minimal Markdown Post Template and YAML Front Matter for Blogs (Markdown 101 - Part 05)
  10. 10 What Is Markdown and How to Create Your First .md File (Markdown 101 - Part 01)

Markdown 101 · Part 4/10

Add links with [label](url) and images with ![alt text](image-path). Good link labels describe the destination, and good alt text describes what the image shows for both accessibility and search engines.

Read the [CommonMark syntax reference](https://commonmark.org/help/).

“CommonMark syntax reference” tells readers where the link leads—far better than vague labels like “click here”.

Common link patterns for blogs:

  • External link: full URL https://....
  • Internal post link: root-relative path, such as [Part 1: Getting Started](/posts/markdown-101-01-getting-started/).
  • Same-page anchor link: [Section Name](#section-name) using lowercase letters and hyphens.
  • Hover title: [label](https://... "Short tooltip").

Adding Images With Meaningful Alt Text

![Live Markdown preview inside Hugo](hugo-markdown-preview.png)

Include images when they clarify a workflow or diagram. The text inside [] (alt text) appears if the image fails to load and helps screen readers and search engines understand the visual—avoid generic names like image1 or screenshot.png.

In Dyn’s Obsidian-to-Hugo workflow, images placed next to the note or in Tệp đính kèm/ are copied automatically into the Hugo post bundle on publish.

Avoid Local Drive Paths

Never reference local filesystem paths such as D:\Brain2nd\... in public articles—readers on the web cannot access files on your machine. Use short, lowercase, hyphenated filenames (e.g., markdown-cheat-sheet.png) and verify every image in Hugo preview before publishing.

Practice Now

Replace the generic link label and image alt text below with clear, descriptive wording.

Practice Now

Change the link label to a clear resource name and replace the image alt text with what the icon represents.

Live Preview
Show hint

Keep the URL inside parentheses. Update the text inside square brackets; images keep the leading !.

Runs locally in your browser (nothing is uploaded or auto-saved). Supports headings, paragraphs, lists, checklists, tables, blockquotes, code, emphasis, links, and local site images.

Source: CommonMark Links & Images.


In the Markdown 101 series:

Loading comments...