Back to Blog
Guides

Markdown Image Syntax Complete Cheat Sheet 2026: GitHub, Notion, HackMD, Obsidian 4-Platform Reference

Published on7 min read
Share

TL;DR — Three Key Takeaways

  1. The basic Markdown image syntax is ![alt text](image URL) — supported everywhere
  2. The syntax for resizing images is different on every platform — this is the biggest gotcha
  3. Image URLs must be publicly accessible direct links — Google Drive share links won't work

Now here's the full cheat sheet.

Basic Syntax: Universal Across All Platforms

![alt text](https://example.com/image.png)
  • alt text: Displayed when the image fails to load; also read by screen readers
  • image URL: Must be a directly accessible image URL (direct link)

Adding a title (shown on hover):

![alt text](https://example.com/image.png "Title shown on hover")

Reference-style syntax (useful when reusing the same image):

![alt text][logo]

[logo]: https://example.com/image.png "Title"

Image Resizing Across Platforms

This is where most people trip up. Based on testing across 5 major platforms, every one handles it differently.

Platform Resize syntax Example
GitHub No Markdown support — use HTML <img src="url" width="300">
HackMD Append =widthxheight after URL ![alt](url =300x200)
Notion Drag to resize — no syntax control Upload, then drag the edges
Obsidian Add ` widthor
Typora Use HTML or zoom markup <img src="url" style="zoom:50%">

GitHub

GitHub's Markdown renderer does not support any image sizing syntax. The only option is HTML:

<img src="https://example.com/image.png" width="400" alt="Description">

GitHub supports width, height, and align attributes on <img> tags, but strips the style attribute for security reasons.

HackMD

HackMD uses a custom extension syntax — append =widthxheight after the URL:

![Description](https://example.com/image.png =300x200)

Width only, with auto-scaled height:

![Description](https://example.com/image.png =300x)

This syntax is HackMD-specific and won't work on other platforms.

Obsidian

Obsidian places the image size in the alt text:

![Description|300](https://example.com/image.png)
![Description|300x200](https://example.com/image.png)

Obsidian also supports Wiki-style internal image links:

![[image.png|300]]

Notion

Notion's Markdown import supports basic image syntax, but resizing can only be done by dragging in the Notion UI. There is no syntax-based control.

Also note: Notion re-uploads external images to its own CDN (prod-files-secure.s3.us-west-2.amazonaws.com), so the original image source doesn't affect loading speed — but it also means updating the original image won't update the Notion version.

Image Hosting Compatibility Across Platforms

Not every image URL renders correctly on every platform. Here are the tested results:

Image source GitHub HackMD Notion Obsidian Typora
Image hosting direct links (lpic.cc, ImgBB, etc.) Works Works Works Works Works
GitHub repo images Works Works Works Requires config Works
Google Drive share links Broken Broken Re-uploaded Unreliable Broken
Dropbox share links Broken Broken Re-uploaded Unreliable Broken
Base64 inline Supported Supported Not supported Supported Supported

Key point: Google Drive and Dropbox share links are not direct image URLs — most Markdown platforms can't render them. To embed images in Markdown, you need a hosting service that provides direct links.

Hotlinking Policies: Will Your Images Get Blocked?

Hotlinking means embedding images hosted on someone else's server in your own page. Some services block hotlinking to conserve bandwidth.

Service Allows hotlinking Notes
Image hosting (lpic.cc, ImgBB, etc.) Yes This is the core function of image hosts
GitHub repos Yes (with limits) High traffic may get throttled
Imgur Partial (blocked in Taiwan) Taiwan IPs blocked since 2025
WordPress.com No Checks the Referer header
Most website images No Typically block off-site references

Image Best Practices for Technical Writing

When writing documentation or blog posts, follow these principles for images:

Don't Skip Alt Text

<!-- Poor -->
![image](url)
![screenshot](url)

<!-- Good -->
![GitHub Actions workflow configuration page](url)
![Terminal showing successful npm install output](url)

Alt text serves three purposes:

  1. Displays a text description when the image fails to load
  2. Read aloud by screen readers (accessibility)
  3. Helps search engines understand image content (SEO)

File Naming Conventions

<!-- Poor -->
Screenshot 2026-03-15 at 14.32.05.png
IMG_4521.jpg

<!-- Good -->
github-actions-workflow-config.png
npm-install-success-output.png

Good naming lets you identify what an image is at a glance, even months later.

Choosing the Right Format

  • Screenshots, UI images: PNG (sharp text stays sharp)
  • Photos, complex images: WebP or JPEG (smaller files)
  • Icons, logos, diagrams: SVG (scales without distortion)
  • Animated walkthroughs: GIF or WebP animation (keep under 5MB)

Compress Before Uploading

Regardless of format, always compress before uploading. Recommended tools:

  1. Squoosh (squoosh.app) — Built by Google, runs in the browser
  2. TinyPNG (tinypng.com) — Batch compression for PNG/JPEG
  3. ImageOptim (macOS) — Drag-and-drop compression with quality preservation

Cross-Platform Compatible Approach

If your Markdown files need to display correctly across multiple platforms, use this strategy:

  1. Image syntax: Stick to standard ![alt](url) syntax — avoid any platform-specific resizing syntax
  2. Image sizing: Resize images before uploading (recommended width: 600-800px) instead of relying on syntax
  3. Image source: Use direct links from image hosts (e.g., lpic.cc offers no-signup uploads with direct links) — avoid Google Drive or Dropbox share links
  4. Image format: PNG or WebP — avoid BMP or TIFF

Note that lpic.cc doesn't currently support custom image dimensions or on-the-fly cropping — you'll need to resize images before uploading. If you need API batch uploads or dynamic processing, consider services like Cloudinary or the Imgur API (outside Taiwan).

FAQ

Q1: Can Markdown center-align images?

Standard Markdown doesn't support image alignment. On GitHub, use HTML: <p align="center"><img src="url" width="400"></p>. HackMD supports {:center} syntax. Notion and Obsidian handle alignment through their UI.

Q2: Can Markdown use local images?

Yes — use a relative path: ![alt](./images/photo.png). But this only works in local editors (Typora, Obsidian, VS Code). For publishing online, you need to upload images to a hosting service and use the public URL.

Q3: Why won't my image show in a GitHub README?

The three most common causes: (1) The image URL isn't a direct link — it requires login to access; (2) The source server blocks hotlinking from GitHub; (3) The relative path is wrong and doesn't point to the correct location in the repository.

Q4: Does HackMD's =300x sizing syntax work on other platforms?

No. The =widthxheight syntax is a HackMD-specific Markdown extension — it won't work on GitHub, Notion, Obsidian, or other platforms. If your documents need to work cross-platform, resize images before uploading or use HTML <img> tags (supported by both GitHub and HackMD).

Q5: What's the difference between a direct link and a share link?

A direct link points straight to the image file, typically ending in .jpg, .png, or .webp. Opening it in a browser shows only the image itself. A share link is a webpage URL that opens a page containing the image (like Google Drive's preview page). Markdown image syntax requires a direct link to render correctly.

References

#Markdown#GitHub#Notion#HackMD#image syntax#technical writing
M

Written by

Mia Huang

Efficiency Expert

Never takes two steps when one will do — writing time-saving guides for everyone.