# Add images and assets

Prefer relative paths for Markdown images, especially when documentation is reviewed in GitHub:

markdown

    ![Options dialog](options-dialog.png)

GitHub previews relative image paths from the repository, and DocInsight collects relative topic images into generated output.

For downloads, samples, and other non-image files, see Add links and cross-references.

## Use clear image text

Write alt text that identifies the image:

markdown

    ![Project options dialog](project-options.png)

Add an optional title only when the generated output should expose extra hover text:

markdown

    ![Project options dialog](project-options.png "Project options")

## Add a topic image

The image path is resolved relative to the topic file:

text

    docs/
    |-- configuration.md
    `-- options-dialog.png

From `docs/configuration.md`, link to the image like this:

markdown

    ![Options dialog](options-dialog.png)

## Group topic image sets

When one topic has several local images, put them in a topic-named folder beside the topic:

text

    docs/
    |-- configuration.md
    `-- configuration/
        |-- options-dialog.png
        `-- output-targets.png

From `docs/configuration.md`, link to the images like this:

markdown

    ![Options dialog](configuration/options-dialog.png)

## Reuse an image across topics

Keep shared Markdown images in a common directory inside the Markdown content root:

text

    docs/
    |-- images/
    |   `-- logo.svg
    `-- guide/
        `-- overview.md

From `docs/guide/overview.md`, reference the shared image with a relative path:

markdown

    ![Shared logo](../images/logo.svg)

To use an image from a project asset set instead, use its root-relative path:

markdown

    ![Product logo](/assets/images/logo.svg)

Every output target that publishes the topic must select the asset set that owns the file. See Markdown path compatibility and Assets for asset-set configuration.

## Reference external images

External image URLs can be used for images that stay hosted elsewhere:

markdown

    ![Status badge](https://example.com/status.svg)

External images are less portable than project-local images. HTML output may load them from the network when the page is viewed. CHM output is offline-oriented, so remote images may not be available to readers. Prefer project-local images for screenshots, diagrams, and documentation that must build repeatably or work offline.