> For the complete documentation index, see [llms.txt](https://help.clause9.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.clause9.com/assemble-document/how-to-assemble-document/insert-images.md).

# Insert images

This page describes how to insert images in the body text of a document, through the special grammar of Clause9.

You can upload .PNG or .JPG image files, but also .PDF files.\
The image files can be directly inserted as part of the header or footer of the [page styling](/styling/page-styling.md).\
\
The PDF files can be used for different purposes (including pages before/after the main content, inserting graphics-heavy headers/footers, including watermaks, etc). This is not further discussed here.

## First step: uploading the image <a href="#first_step_uploading_the_image" id="first_step_uploading_the_image"></a>

Images are just another type of file that you can create in the file system, similar to how clauses, documents, binders and concepts are also files.

* Go to *Browse files*, click on <img src="/files/Brz8BNUP1hPTBh435SBv" alt="" data-size="line">  and select *Image / PDF / MS Word DOCX.*
* Give the image a descriptive *File name*.
* Perform the actual upload under the *Upload* tab. Both .PNG and .JPG file types are accepted.

<figure><img src="/files/YYGNzujtM9rtGCPvjd1P" alt=""><figcaption></figcaption></figure>

## Second step: including an image in a clause <a href="#second_step_including_an_image_in_a_clause" id="second_step_including_an_image_in_a_clause"></a>

You can insert the image in a clause by use the `@image(file)` [special function](/special-functions/introduction.md), optionally complemented by one or more optional additional parameters.

* The file-parameter is one of the following
  * a hashtag and a reference to the image-file, similar to how you would refer to a #concept (i.e., the software will invite you to specify which file you are actually referring to)
  * a URL (enclosed in single or double quotes)
  * a text datafield containing a URL (e.g., #corporate-logo^url)
  * a text datafield containing the image data itself, uploaded through an “image” question in the Q\&A
* The optional parameters can be one of the following:
  * maximum width/height
  * maximum width/height, border-width and color
  * width, height
  * width, height, border-width and color
* To be used as follows:
  * the maximum width, width, height and border width can be expressed in centimeters (“cm”), millimeters (“mm”), inches (“i), points (“pt”) or pixels (“px”). If no unit type is specified, then pixels will be assumed
  * the maximum width/height refers to one measurement, which will be used to determine either the maximum width (if the image is wider than high) or the maximum height (if the image is higher than wide)
    * for example, a 10cm x 5cm image will be scaled down to 6cm x 3cm when using *@image(#some-file, 6cm)*
  * the color should be expressed in the so-called “hex” format, a set of six characters — many software programs and color pickers will show you this format when selecting a color, alternatively you can use a website such as [www.color-hex.com](https://www.color-hex.com/) or [www.w3schools.com/colors/colors\_picker.asp](https://www.w3schools.com/colors/colors_picker.asp)
    * alternatively, you can also use one of the following human-readable colors: *black, grey, gray, white, salmon, red, pink, orange, gold, yellow, lavender, violet, fuchsia, purple, green, olive, teal, cyan, blue, navy, brown or maroon*
    * don’t forget to enclose the color in quotes!

## Examples <a href="#examples" id="examples"></a>

* `@image(#cb-logo)`&#x20;
* `@image(#cb-logo, 3cm)`&#x20;
* `@image(#cb-logo, 280px, 160px)`&#x20;

<figure><img src="/files/nfoud5mLTeJRiW62Np2J" alt="" width="318"><figcaption></figcaption></figure>

* `@image(#cb-logo, 3cm, 4pt, "black")`&#x20;

<figure><img src="/files/9uyTOu67YEq7B3tDBdfA" alt="" width="354"><figcaption></figcaption></figure>

* `@image(#cb-logo, 3cm, 4pt, "#ff6666")`

<figure><img src="/files/05uotDG9kUOAXpB6cvII" alt="" width="360"><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.clause9.com/assemble-document/how-to-assemble-document/insert-images.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.