Docus provides multiple ways to include visual content in your documentation, from simple images to embedded videos and interactive media.
Images
Basic Image Syntax
Use standard Markdown syntax to include images:
Local Images
Reference images stored in your project’s public directory:
Docus uses the <NuxtImg> component under the hood instead of the native img tag, providing automatic optimization and lazy loading.
Image Optimization
Docus integrates with Nuxt Image for automatic image optimization:
- Automatic format conversion - WebP and AVIF support
- Responsive images - Multiple sizes for different screens
- Lazy loading - Images load as users scroll
- Blur placeholder - Smooth loading experience
Place images in the public/ directory to reference them with absolute paths starting with /.
Image Sizing
Control image dimensions using HTML attributes:
<img src="/images/logo.svg" alt="Logo" width="200" height="100" />
:img{src="/images/logo.svg" alt="Logo" width="200"}
Videos
Embedded Videos
Embed videos using the MDC video component:
:video{autoplay controls loop src="https://example.com/video.mp4"}
Supported video formats include MP4, WebM, and OGG. Always provide a controls attribute for better accessibility.
Video Attributes
Common video attributes:
| Attribute | Description |
|---|
autoplay | Start playing automatically |
controls | Show playback controls |
loop | Loop the video |
muted | Mute audio (required for autoplay) |
poster | Thumbnail image before video plays |
Autoplay videos should always be muted to comply with browser policies and provide a better user experience.
YouTube Embeds
Embed YouTube videos using the standard iframe syntax or MDC component:
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/dQw4w9WgXcQ"
title="YouTube video"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
Use YouTube’s “Share” → “Embed” option to get the correct iframe code with privacy-enhanced mode.
CodePen Embeds
Embed CodePen examples for interactive code demonstrations:
<iframe
height="400"
style="width: 100%;"
scrolling="no"
title="Example Pen"
src="https://codepen.io/username/embed/penid?default-tab=html,result"
frameborder="no"
loading="lazy"
allowtransparency="true"
allowfullscreen="true"
>
</iframe>
<blockquote class="twitter-tweet">
<p lang="en" dir="ltr">Tweet text here</p>
<a href="https://twitter.com/user/status/123456">Date</a>
</blockquote>
<script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
GitHub Gists
Embed GitHub Gists for code snippets:
<script src="https://gist.github.com/username/gist-id.js"></script>
Interactive Embeds
Embed Figma prototypes:<iframe
style="border: 1px solid rgba(0, 0, 0, 0.1);"
width="800"
height="450"
src="https://www.figma.com/embed?embed_host=share&url=YOUR_FIGMA_URL"
allowfullscreen
></iframe>
Embed Loom videos:<div style="position: relative; padding-bottom: 56.25%; height: 0;">
<iframe
src="https://www.loom.com/embed/VIDEO_ID"
frameborder="0"
webkitallowfullscreen
mozallowfullscreen
allowfullscreen
style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
></iframe>
</div>
Embed Miro boards:<iframe
width="768"
height="432"
src="https://miro.com/app/embed/BOARD_ID"
frameborder="0"
scrolling="no"
allowfullscreen
></iframe>
Image Galleries
Create image galleries using card groups:
<CardGroup cols={2}>
<Card>
</Card>
<Card>
</Card>
<Card>
</Card>
<Card>
</Card>
</CardGroup>
::card-group
:::card
:::
:::card
:::
::
SVG Images
SVG files work perfectly in documentation:
SVG images scale perfectly at any size and support transparency, making them ideal for logos and diagrams.
Accessibility Best Practices
Every image should have descriptive alt text for screen readers:
Use descriptive filenames
Name files descriptively: authentication-flow.png instead of img123.png
Provide captions when needed
For complex diagrams, include explanatory captions below the image.
Include video transcripts
For important video content, provide text transcripts or summaries.
CDN and External Images
When using external images, consider:
External images from third-party CDNs may:
- Slow down page load times
- Introduce privacy concerns
- Become unavailable if the external source goes down
Whenever possible, host critical images in your project. Image Organization
Organize your images effectively:
public/
├── images/
│ ├── screenshots/
│ │ ├── dashboard.png
│ │ └── settings.png
│ ├── diagrams/
│ │ ├── architecture.svg
│ │ └── workflow.svg
│ └── logos/
│ ├── logo.svg
│ └── logo-dark.svg
Use a consistent naming convention and directory structure to make images easy to find and maintain.