Skip to main content

Assets in Markdown

In CodeHarborHub documentation, you may need to include images, files, or SVGs inside Markdown (.md / .mdx) files.

Docusaurus provides several ways to handle these assets while keeping everything organized and optimized.

A common practice is to co-locate assets next to the Markdown file that uses them:

/docs/guides/markdown-features/markdown-features-assets.mdx
/docs/guides/markdown-features/assets/example-banner.png
/docs/guides/markdown-features/assets/example-file.docx

This keeps docs self-contained and easy to maintain.

Images​

You can display images using three different methods:

1. Simple Markdown Syntax​

The easiest way to add an image:

![Example banner](./assets/example-banner.jpg)

This works for most cases and Docusaurus will automatically process the file.

All three methods display the same image:

http://localhost:3000

Example banner

Downloadable Files​

You can also link downloadable files (like .docx, .pdf, .zip) directly.

Markdown link syntax (recommended):

[Download the example doc](./assets/example-file.docx)

JSX with require() (for dynamic attributes):

<a target="_blank" href={require('./assets/example-file.docx').default}>
  Download this docx
</a>
http://localhost:3000

Download the example doc

Inline SVGs​

Docusaurus supports importing SVGs as React components. This allows you to style or animate parts of the SVG using CSS.

import MyIcon from './assets/logo.svg';

<MyIcon className="customSvg" />;

For example, you can change the SVG color based on the current theme:

[data-theme='light'] .customSvg [fill='#000'] {
  fill: #1e90ff;
}
[data-theme='dark'] .customSvg [fill='#000'] {
  fill: #00fa9a;
}

Themed Images​

For sites that support light/dark mode, you may want different images per theme. Use the ThemedImage component to automatically swap images.

import useBaseUrl from '@docusaurus/useBaseUrl';
import ThemedImage from '@theme/ThemedImage';

<ThemedImage
  alt="CodeHarborHub Logo"
  sources={{
    light: useBaseUrl('/img/codeharborhub-light.svg'),
    dark: useBaseUrl('/img/codeharborhub-dark.svg'),
  }}
/>

This ensures the correct image is loaded depending on the current theme.

GitHub-style Theme Switching​

You can also replicate GitHub’s approach using path fragments:

![Light mode](/img/codeharborhub-light.svg#gh-light-mode-only)
![Dark mode](/img/codeharborhub-dark.svg#gh-dark-mode-only)

Add this CSS to hide/show based on theme:

src/css/custom.css
[data-theme='light'] img[src$='#gh-dark-mode-only'],
[data-theme='dark'] img[src$='#gh-light-mode-only'] {
  display: none;
}

Static Assets​

If you use absolute paths (/img/...), Docusaurus treats them as static assets.

Example:

![Static asset](/img/nav-logo.jpg)

Docusaurus will look for this image inside the static/ directory:

/static/img/nav-logo.jpg

Benefits of using static assets:

  1. Automatic Base URL Handling – works even when deploying to a subpath.
  2. Cache Optimization – images are processed by Webpack and get a unique hash for better caching.

If you need a raw URL (without build processing), use the pathname:// protocol:

![Raw image](pathname:///img/nav-logo.jpg)

This generates a direct <img src="/img/nav-logo.jpg" /> tag.

Best Practices​

  • Keep assets close to the docs that use them for easier maintenance.
  • Prefer Markdown syntax for most links/images for cleaner code.
  • Use ThemedImage or inline SVGs when working with dark/light mode.
  • Use static assets for site-wide shared files like logos and large downloads.