- The Markdown Landscape
- HTML: The Secret Weapon
- Elements in Markdown Images
- Image Markdown and HTML
- Getting Fancy with CSS
- Alternate Markdown Syntax
- Next Steps
- FAQ: Images in Markdown
It’s simple to insert an image into Markdown.
That’s it.
But doing much else with the image is a bit of a mess.
I’m here to give you something hard to find: Markdown that formats and enhances your images.
And there’s something else you should know.
Plain HTML works in Markdown. We’ll be using HTML to pull some nice image manipulation tricks.
Let’s get started.
The Markdown Landscape
Markdown is plenty powerful, especially for web content. What it does, it does well.
Markdown was created by John Gruber and Aaron Swartz in 2004. Its purpose is to be as easy to use and human-readable as possible in its raw, plain-text format.
Knowing a little Markdown history helps understand why some basic formatting functionality is so complicated. Using images in Markdown is a perfect example.
Markdown was not written as a standard. And therein lies the rub. It lacks a formal specification. It is a lightweight markup language. That’s all.
The lack of a formal specification has spawned many implementations and interpretations of Markdown. This causes some mayhem when trying to get anything done beyond basic markup tasks.
An effort to standardize Markdown is underway. CommonMark aims to create an unambiguous specification for Markdown. It has become widely adopted, but other Markdown flavors are still common.
Let’s sort through the variations of Markdown markup. We’ll create snippets and techniques you can use to do advanced image manipulation in Markdown.
And I’ll now reveal our secret weapon.
HTML: The Secret Weapon
Before I start with Markdown, I want to let you in on a poorly kept secret. Markdown supports inline HTML. Well, it’s not actually a secret. It was designed like this from the beginning.
Still…
This feature makes up for all the dissimilar Markdown syntax problems. Finding consistency in browsers, editors, previewers, and processors relies on inserting HTML tags into your markup wherever needed.
On to the solutions.
Elements in Markdown Images
Let’s resurrect our first example from the introduction.
The Markdown is in three parts. All three parts are required.
Image insertion begins with an exclamation point (!) or “bang.” This tells the Markdown interpreter that image information is coming.
[Alt text] is required and displayed when the image can’t be shown. A significant use for alt text is for screenreaders that speak webpage content for the visually impaired. It is also used for text-only browsing of any kind. [Square brackets] delineate alt text.
(File-path) is what it says, the path towards the image file itself. The file-path can be relative, absolute, or root-relative. It can also be a URL to an image on the internet. Use (parentheses) for the file path.
Relative file path
The path is relative to the Markdown file’s location.
Absolute file path
Specifies a complete path from the root of the file system.
Root-relative file path
When the image file is relative to the root directory.
URL
Points to an online image, file, or document.
NOTE: Relative paths or URLs are recommended for documents shared across different systems.
Image Markdown and HTML
It is common to alter an image’s appearance on a web page or document. You may wish to resize, align, or add a title or caption.
Here’s where it gets tricky.
Three of the most common flavors of Markdown are:
- Markdown
- MultiMarkdown
- CommonMark
But writing your Markdown in one of these doesn’t assure compatibility with the Markdown processor used for interpreting it. You must write specifically for your processor or else be as generic as possible.
If you will be using your Markdown on multiple platforms or in various applications, you can’t be sure what syntax all those processors use.
Enter HTML.
NOTE: If you don’t know any HTML, it’s worth learning a bit. It gives you the flexibility to script anything you need in Markdown. Visit w3schools.com or another HTML tutorial site to get started.
Here are several examples of image manipulation in HTML that you can use in Markdown.
Basic image tag
<img src="path-to-image.jpg" alt="Description of the image">
Change the image size
<img src="image.jpg" alt="Description" width="300" height="200">
Style: Border
<img src="image.jpg" alt="Description" style="border: 1px solid \#000;">
Style: Shadow
<img src="image.jpg" alt="Description" style="box-shadow: 5px 5px 10px \#888;">
Style: Opacity
<img src="image.jpg" alt="Description" style="opacity: 0.5;">
Style: Margin
<img src="image.jpg" alt="Description" style="margin: 10px;">
Style: Padding
<img src="image.jpg" alt="Description" style="padding: 10px;">
Style: Rounded Corners
<img src="image.jpg" alt="Description" style="border-radius: 20px;">
Style: Rotation
<img src="image.jpg" alt="Description" style="transform: rotate(45deg);">
Getting Fancy with CSS
If you know CSS, you can use it in your HTML either inline or as a referenced class. The CSS will style the image as you would expect.
HTML
<img src="image.jpg" alt="Description" class="hover-effect">
CSS
.hover-effect:hover { opacity: 0.7; }
Alternate Markdown Syntax
If you know what flavor Markdown your processor uses, you can take advantage of this knowledge and use the specialized syntax that the processor supports.
One brief example is this:
{width=300 height=200}
Note the {bracket notation} at the end of the primary tag.
Compatibility
While this example works in MultiMarkdown, this notation is not supported in CommonMark or most Markdown flavors. As shown in the section above, HTML is a more reliable choice for CommonMark or any other Markdown processor.
Next Steps
Now that you know how to access and manipulate your Markdown and images, you must host your web files somewhere.
Getting them working on your local computer is fine, but to share them online, you need a web hosting service to store your Markdown and image files with the world.
Did I mention that you can host a Markdown website for free?
Our service, Tiiny.host, automates the entire hosting process and puts your Markdown (.md) files and images online in moments, not hours. Just drag and drop and sign in. That’s it.
Visit Tiiny.host for more information about Markdown, hosting, images, or anything else web-related.
Our wonderful customer supportstaff is available free of charge to anyone. You needn’t have an account already. Try us out!
FAQ: Images in Markdown
How do I add an image in Markdown?
Use this syntax: . “Alt Text” is the alternative description of the image, and “URL” is the path or link to the image.
Can I resize images directly in Markdown?
Markdown doesn’t directly support resizing images. HTML tags, including the img tag, are supported within your Markdown. MultiMarkdown supports a direct image resize syntax.
Can I link an image to a URL in Markdown?
Yes, wrap the image syntax in link syntax: [](Link URL).
