# Images
This chapter covers how to insert and manage document images. You can embed
standard images, create text-based diagrams, and---as we'll see
later---integrate plots from R. The application supports various image formats
and provides flexible path resolution for both local and remote images.
## Inserting images
Insert an image into your Markdown document using the following syntax:
Replace `image description` with a descriptive caption for the image and `path`
with either a local file path or URL where the image is located.
For example, to embed a local image file named `chart.png` located in the same
directory as your document, you could write:
To embed an image from a remote server, use its URL:
The application will display the image in the preview tab upon download.
## Image server
By default, all text diagrams are sent to [Kroki](https://kroki.io) for
conversion into SVG images. A network connection is required to render all text
diagrams. There is a configuration option to change servers and Kroki is
open-source software, so it is possible to keep all source diagrams on premises
by setting up a locally hosted image server.
## Text diagrams
{{app.title}} distinguishes between diagrams and source code listings by
prefixing diagrams with a `diagram-` prefix, such as:
``` diagram-plantuml
@startuml
Alice -> Bob: Hello
@enduml
```
This has a few benefits. First, it allows rendering diagram types using a
service without having to codify all possible diagram types. Second, when a new
type of diagram is added, it's available immediately without needing to upgrade
the text editor. Third, it clearly distinguishes between a code block to be
rendered visually and one to be listed as verbatim source code.
Typically, source code is presented in code blocks that include the language
name so that syntax highlighting can be applied:
``` c
main() {
printf( "hello, world" );
}
```
### Mermaid
GitHub created a *de facto* standard that prevents parsers from dynamically
distinguishing between a diagram to render and source code to list. The
following code block could be either a source code listing or a pie chart:
``` mermaid
pie
title Turkish Empire Proportions, 1789
"Asia" : 66
"Africa" : 20
"Europe" : 14
```
While tagging the block as `mermaid-lang` could help, it creates a special case
that needs to be programmed into Markdown parsers. (Having both `c-lang` and
`c` is redundant.) The `diagram-` prefix side-steps the issue while keeping
true to the human-readability nature of Markdown. For this reason, using
`mermaid` alone for a fenced code block will show the source code rather than
draw a diagram.
## Image paths
Image file discovery enables flexible and intelligent handling of image links
within documents. It supports both remote and local image sources, and attempts
to resolve incomplete or relative paths.
### Resolution strategy
The algorithm follows a multi-step process to determine the file to display:
1. **Remote URLs** -- If the image reference begins with a remote protocol
(e.g., `http://`, `https://`), it is accepted as valid and used directly.
1. **Fully qualified paths** -- If the image refers to a specific file
path on the local system and the file is readable, it is used as-is.
1. **Relative paths** -- For unqualified links, the system checks if the image
exists relative to the base directory of the current document. If not found,
and there's no extension, all common image file name extensions (e.g., `.svg`,
`.png`, `.jpg`) are tried.
If the image cannot be resolved through any of the above methods, an error is
logged to indicate the missing file.
### Resolution example
A document that includes `` is resolved as follows:
1. If `company-logo` is a remote URL, try to fetch it.
1. Look for a local file named `company-logo`.
1. Look for a file named `company-logo` in a specified images directory.
1. Look for `company-logo.png`, `company-logo.jpg`, etc.
1. Use the first valid readable matching file found.
1. Log an error if the file cannot be found.