Prefer relative paths for Markdown images, especially when documentation is reviewed in GitHub:
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.
Write alt text that identifies the image:
Add an optional title only when the generated output should expose extra hover text:
The image path is resolved relative to the topic file:
docs/
|-- configuration.md
`-- options-dialog.png
From docs/configuration.md, link to the image like this:
When one topic has several local images, put them in a topic-named folder beside the topic:
docs/
|-- configuration.md
`-- configuration/
|-- options-dialog.png
`-- output-targets.png
From docs/configuration.md, link to the images like this:
Keep shared Markdown images in a common directory inside the Markdown content root:
docs/
|-- images/
| `-- logo.svg
`-- guide/
`-- overview.md
From docs/guide/overview.md, reference the shared image with a relative path:
To use an image from a project asset set instead, use its root-relative path:
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.
External image URLs can be used for images that stay hosted elsewhere:
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.