Embedding Media
Inline Images and Video using Markdown and the Typography Component
This document explains how to add images and videos to your Markdown files. These are particularly useful when writing long-form content such as blog posts, guides, or documentation.
When working with media, it’s important to note that inline media embedding only works with the Typography Component, not the Text Component. The Typography Component supports rich inline elements like images, videos, and code blocks, allowing your content to flow naturally with surrounding text.
Images
You can include both local and remote images in your Markdown files using the standard Markdown syntax:
f you reference a local file, Elements CMS will automatically detect it and prefix the correct path to your project’s resources folder during publishing. This ensures that your image links always remain valid, both locally and when uploaded to your web host.
Remote images (hosted externally) can also be embedded by using a full URL:
Images displayed within the Typography Component are automatically set to a maximum width of 100%, meaning they’ll scale down to fit smaller screens but will never be enlarged beyond their actual pixel size. This ensures your content remains sharp and visually consistent across all devices.
File Naming Best Practices
When working with local images, always use lowercase filenames and avoid spaces or special characters.
Instead of Images/My-Image.jpg use all lowercase, like this: images/my-image.jpg.
Elements automatically converts filenames to lowercase and replaces spaces or non-standard characters with underscores to make them web-safe. For example:
my~file.pngwould becomemy_file.png.my file has spaces.pngwould becomemy_file_has_spaces.png.myFile.pngwould becomemyfile.png.
Many web servers (Linux/Unix based) treat File.jpg and file.jpg as two different files. However, on Windows or macOS (i.e. Elements), the filesystem often isn’t case-sensitive, so it looks fine locally, but when uploaded, it can cause broken links and 404 errors.
By using lowercase files, you’ll ensure they will ALWAYS work on different environments (Windows, Linux, macOS), this could be very important depending on the hosting platform you have chosen.
Using Inline CSS to style images (not recommend)
You can also use basic HTML and inline CSS to position or style images, though it’s generally best to avoid this unless absolutely necessary. If you do choose to use HTML, make sure you reference the full, correct path to your image files.
The following example floats the image to the left to allow text to wrap around it:
YouTube Videos
To embed a YouTube video, copy the embed code from the video’s “Share → Embed” option. It should look something like this:
You can paste this HTML directly into your Markdown file. Elements CMS will render the video inline when displayed within the Typography Component.
If you’d like the video to fill the width of the container, remove the width and height attributes and use Tailwind utility classes on the parent component to make it responsive:
Add the following classes to the component displaying your Markdown:
This ensures that the embedded video maintains a proper aspect ratio while scaling fluidly across screen sizes.
Common Issues
Image not showing up?
Make sure the file exists in your project’s resources folder and that the path is correct. For example, if your resource file is in a /blog/ folder, your image should be referenced as blog/filename.jpg.
Video cut off or not scaling correctly?
Check that you’ve removed the fixed width and height attributes from the <iframe> and that your parent component includes the Tailwind classes: [&_iframe]:w-full [&_iframe]:aspect-video
File path case mismatch
If you’re developing on macOS or Windows and everything works locally but breaks after upload, check for mismatched uppercase/lowercase letters in file names. Web servers treat Image.jpg and image.jpg as different files.
Last updated
Was this helpful?