> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withrealm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Documents

> Plan, draft, review, and export long-form documents such as proposals

Documents is a Realm feature that writes long-form documents, such as proposals, from your company knowledge. In Documents, you plan the outline, Realm drafts the document section by section, your team reviews and approves each section, and then you export the document in your own template layout. Button and option names on this page are in bold.

## Before you start

Do these things before you write your first document.

* **Open Documents.** Click **Documents** in the sidebar. The Documents page opens.
* **Put your source files in the knowledge base.** The knowledge base is the company information that Realm is connected to. It includes documents, messages and data from your workplace tools. To see it, go to **Knowledge** > **Browse knowledge** in the main sidebar. See [Browsing knowledge](https://docs.withrealm.com/knowledge/browsing.md).
* **Or put your source files in a project.** Use a project when the files are only for one bid or one customer.
* **Ask an admin about a default template layout.** An admin can set a default template layout for your exports in **Settings** > **Organization settings**, under **Document template**. If your team uses a fixed template layout, ask your admin to set it. See [Document template](https://docs.withrealm.com/admin/organization-settings/overview#document-template).

## Start a document

Start a document from the Documents page. The message box sets the request, and the options around it set how Realm writes the document.

### Choose how Realm writes the document

![The message box on the Documents page with a request typed in and its mode menu open on Write, write in one pass, and Plan, plan section by section](https://mintcdn.com/realm/xViU5Fe1e4lRVgR7/images/documents/write-or-plan.png?fit=max\&auto=format\&n=xViU5Fe1e4lRVgR7\&q=85\&s=61c365ade5267c011aa986594bc5d4b0)

1. Click the menu at the bottom right of the message box. The menu shows **Write** and **Plan**.
2. Click **Write** to write the document in one pass. Use **Write** for short documents. **Write** is the default.
3. Or click **Plan** to plan the document section by section. Use **Plan** for long documents that need a review of each section.

### Add files, a starting point or a skill

![The + menu of the message box with Attach files, Start from document, Start from template, and Skill, Project and Tags, each set to None](https://mintcdn.com/realm/xViU5Fe1e4lRVgR7/images/documents/plus-menu.png?fit=max\&auto=format\&n=xViU5Fe1e4lRVgR7\&q=85\&s=16072c0c2068e77a821c5c850a88a83f)

1. Click **+** in the message box. The tooltip reads "Attach files, pick a starting point or a skill."
2. Click **Attach files** to add files to the request.
3. Click **Start from document**, then choose **Upload a file**, **Your documents** or **Knowledge base**. The draft is based on that document.
4. Click **Start from template**. The menu shows the groups **Suggested** and **All templates**.
5. Point at a template and click **Show** to preview it.
6. Click a template to use it. Click **Add template** to make a new template from a file or the knowledge base, or click **Browse all templates** to see every template.
7. Click **Skill**, then choose a published skill. The skill gives the draft its instructions. If the skill has a template, the draft starts from it.
8. Click **Project**, then choose a project. The document becomes an output of that project. It draws on the project's files and tags.
9. Click **Tags**, then choose the tags. The document draws only on knowledge with those tags. Tags are offered only when no project is picked.

If you pick a document and a template together, the document is the base, and the template gives the structure and style. For more on these options, see [Skills and projects](https://docs.withrealm.com/chat/special-features#skills-and-projects).

## Plan the document

In this part, you tell Realm what document you need. Realm makes a plan first, so you can examine and change the structure before Realm writes any text.

### Describe the document

1. Type a description of the document in the message box.
2. Optional: click **+** to add files, a starting point or a skill. See [Start a document](#start-a-document).
3. Click **Plan** instead of **Write**. Realm will make a plan, not a full draft.
4. Send the message. The Plan opens. It shows **Instructions**, **Rules & requirements** and **Length**.

### Make the outline

1. Read the **Instructions**, the **Rules & requirements** and the **Length** in the Plan. You can see how Realm will write the document.
2. Click **Write outline**. Realm shows the outline as a list of sections.
3. Open a section. You see the instructions, key points and requirements for that section.
4. Edit the instructions, key points or requirements of the section. The section keeps your changes.

### Arrange the sections

1. Drag a section to a new position in the outline. The section moves to the new position.
2. Drag a section to indent it below another section. The section shows as a subsection.
3. Click **Add section** if the outline needs more sections. A new section shows in the outline.
4. Choose an owner in the header of a section. The section now has an owner. The assigned sections show in the **My tasks** view for that person.
5. Click **Create document**. Realm starts to write the document.

### What happens next

Realm writes the sections in the same order as the plan. A spinner shows which section Realm writes now. You do not have to wait on this screen: sections keep drafting after you close the editor. When the sections are ready, you can edit them, fill in placeholders and continue with the steps in [Draft and edit](#draft-and-edit).

For every field of the plan, tables in sections and how the chat changes the plan, see [Planning a document section by section](https://docs.withrealm.com/rfp/document-responses.md#planning-a-document-section-by-section).

## Draft and edit

When you click **Create document**, Realm starts drafting the sections of the document. Realm writes the sections one by one in plan order. Do the steps below in the order that you need them.

### Follow the draft

1. Look at the outline. A spinner shows the section that Realm writes now.
2. Read the completed sections while Realm writes the next sections. The text of the completed sections stays in the same position.

### Check each section in the Plan tab

![The Plan tab listing six drafted sections with their status, word budget and regenerate button, with one section open to its instructions, key points and requirements](https://mintcdn.com/realm/xViU5Fe1e4lRVgR7/images/documents/plan-outline.png?fit=max\&auto=format\&n=xViU5Fe1e4lRVgR7\&q=85\&s=19e5c15c0c9552e0b2db58b95266c8eb)

1. Select the **Plan** tab. This tab is beside **Write** and **Preview**. You see each section with its placeholders, comments and status.
2. Read the status of each section. The status shows if the section is not written, writing, failed, has comments, in review or approved.
3. Click the regenerate button of a section to write that section again. Realm drafts a new version of the section. If the section was approved, Realm asks first, because the section goes back to review.

### Rewrite one paragraph

Use this procedure to change one paragraph without a rewrite of the full section.

1. Point at the paragraph and click the sparkle icon at its end, **Regenerate with AI**. A box opens.
2. Type how the paragraph should change, or leave the box empty, and press Enter. Realm rewrites the paragraph in place in a few seconds.
3. Press Ctrl+Z (Cmd+Z on Mac) if you want the earlier text again. The earlier text comes back.

### Fill placeholders

A placeholder is a blank that Realm cannot fill from your company knowledge, for example a name, a date or a price.

1. Click a placeholder in the text. A field opens for the value.
2. Type the value and press Enter. The placeholder changes to your value.
3. Choose **Fill all** to fill each placeholder that has the same label.

Submit an empty value to remove the placeholder instead. Word and PDF exports highlight unfilled placeholders in yellow.

### Change the document or the plan with the chat

1. Type your request in the chat in the editor. Tell Realm what to change in the document or in the plan.
2. Send the request. Realm changes the document or the plan.
3. Read the changed sections. Do the steps in this procedure again if you need more changes.

## Create a document from a project

Use a project when a tender asks for documents. The project keeps each document with the bid, so your team can find it in one place. For the details of each step, see [Document RFP responses](https://docs.withrealm.com/rfp/document-responses.md).

### Draft a requested document

Realm reads the project's files and lists each document they ask for, and that nobody has drafted yet, under **Suggested documents**. Each suggestion quotes the sentence that asks for it.

1. Open the project and select the **Files** tab. The **Suggested documents** band lists the documents that the project's files ask for.
2. Point at a suggestion and open **Create**. A menu opens with **Upload files…**, **Create document…** and **Existing document…**.
3. Choose **Create document…**. The dialog opens and links the new document to the suggestion.
4. Type the request in the message box, or keep the suggested sentence. The message box is the same as on the Documents page.
5. Choose **Write** to draft the document at once, or choose **Plan** to review the sections first. Realm starts the draft. The suggestion leaves the band when the document is drafted.

### Add a deliverable

You can add a new document deliverable to the project from either of the two places below.

![The Add menu in a project header, open on Upload files, Create document and Existing document](https://mintcdn.com/realm/xViU5Fe1e4lRVgR7/images/documents/project-add-menu.png?fit=max\&auto=format\&n=xViU5Fe1e4lRVgR7\&q=85\&s=0d28e282ef1e72df996806246f72ff1f)

1. Choose **Add** in the project header. A menu opens with **Upload files…**, **Create document…** and **Existing document…**.
2. Choose **Create document…**. The **Create document** dialog opens.

Or:

1. Select the **Files** tab and find the **Deliverables** band.
2. Choose **Add a deliverable**. A menu opens with the same three items: **Upload files…**, **Create document…** and **Existing document…**.

### Set up the new document

![The Create document dialog of a project with an empty message box, the Deliverable role, the Write mode and a suggested template below the box](https://mintcdn.com/realm/xViU5Fe1e4lRVgR7/images/documents/create-document-dialog.png?fit=max\&auto=format\&n=xViU5Fe1e4lRVgR7\&q=85\&s=c09e575ea91cad63c86c5f1bf1ee197e)

1. Type the request in the message box. The message box is the same as on the Documents page.
2. Choose **Write** to draft the document at once, or choose **Plan** to plan it first.
3. Under **Role**, choose **Deliverable** or **Supporting file**.
4. Under **Linked to**, choose a suggestion, or choose **None**.
5. Send the request. Realm drafts the document, and it appears in the project's files.

### Draft from a file or a questionnaire

1. Open the options menu on a file row and choose **Write response**. Realm drafts a written response to that file and opens the editor. Screenshot attachments are included.
2. Open the options menu of a questionnaire and choose **Turn responses into document**. Realm makes a document from its filled answers and screenshot attachments. See [Turning responses into a document](https://docs.withrealm.com/rfp/filling-rfps.md#turning-responses-into-a-document).
3. Open the menu of an answer column header and choose **Create document from this column**. Realm makes a document from the answers in that column.

When you choose **Export** in the project header, the document is included as a Word file or a PDF.

## Find your way in the editor

Use the views above the document, the sidebar and the header buttons to move around a document and to check it.

![The editor with the sidebar tabs on the left above an outline of six sections, and the Write, Preview and Plan tabs above the document](https://mintcdn.com/realm/xViU5Fe1e4lRVgR7/images/documents/editor-tabs.png?fit=max\&auto=format\&n=xViU5Fe1e4lRVgR7\&q=85\&s=179cb24296c2a7ed45068eb3abd366d2)

### Main tabs

* **Write**: edit the text.
* **Preview**: shows the document in its template layout, as it will export.
* **Plan**: shows only for a planned document. It lists each section with its instructions, key points, status and a regenerate button.

### Sidebar tabs

The sidebar sits to the left of the document.

* **Outline**: lists the sections with their status and owner. Click a section to go to it. Use **Add section** to add a section. Drag a section to move it.
* **Placeholders**: shows when the document has placeholders. It has one group for each placeholder label. Fill them here, or use **Find in document**.
* **Template values**: shows when the document has a template layout. It has one field for each text in the layout's cover, headers and footers. Type a replacement, or leave the field empty to keep the layout's text. Remove a text with **Remove from the template** on its row. Text that you change less often is under **Other text**.
* **Sources**: lists the sources that the document cites.

On a narrow screen, the sidebar folds to a column of icons.

### Header buttons

![The editor header showing 0 of 6 approved, then the tag, comments and version buttons, Share, Export, the options menu and the chat button](https://mintcdn.com/realm/xViU5Fe1e4lRVgR7/images/documents/editor-header-buttons.png?fit=max\&auto=format\&n=xViU5Fe1e4lRVgR7\&q=85\&s=995f71715b434fd58a720c7ebaa04136)

* **Tags**: shows the knowledge tags that the document draws from. A project document inherits its tags from the project, and shows the text **N from project**.
* **Comments**: opens the comments on the document.
* **Versions**: shows earlier versions.
* **Share**: share the document with other users.
* **Export**: export the document to Word, PDF, Markdown or Google Docs.
* **Options menu**: contains **Duplicate document**, **Save as template** and **Delete this document**. In a project document, it also contains **Approve document**.

## Images and screenshots

You can put images, such as diagrams and screenshots, in a document. Realm supports PNG, JPEG, GIF and WebP images.

### Add images

![The editor toolbar with the + menu open on Table and Image](https://mintcdn.com/realm/xViU5Fe1e4lRVgR7/images/documents/insert-image-menu.png?fit=max\&auto=format\&n=xViU5Fe1e4lRVgR7\&q=85\&s=fe4f64c7578087797ca40ec70cfa1384)

1. Click in the text where the image goes.
2. Paste the image, or drag one or more image files into the document.
3. Or click **+** in the toolbar and choose **Image**. You can select more than one image. The images appear at the cursor in file order.
4. Click an image to select it. Drag a corner to change the size. The image keeps its proportions, and Word exports keep the size that you set.
5. Use the buttons on the selected image to copy the image, copy its link or delete it.

### Place images with the chat

![The editor chat with an attached architecture-diagram.png and a request to put the diagram under Technical approach](https://mintcdn.com/realm/xViU5Fe1e4lRVgR7/images/documents/chat-attach-image.png?fit=max\&auto=format\&n=xViU5Fe1e4lRVgR7\&q=85\&s=8726d5977a0a9b93934d8a209e6d06cc)

1. Click the paperclip in the chat in the editor and attach the image.
2. Tell Realm where the image goes, for example "Put this architecture diagram under Technical approach".
3. Send the request. Realm puts a copy of the image at that position.

The document keeps its own copy of the image. Teammates and exports show the image, also when the chat is deleted. Save HEIC photos as PNG or JPEG before you attach them.

### Add screenshots to questionnaire answers

1. Open the questionnaire and find the **Attachments** column.
2. Point at the cell of the row and click **+**. The attachment picker opens.
3. Choose a document from the list, or click **Upload from computer** to add a screenshot. The cell shows the name of the attachment.

When you fill the original Word file, Realm puts each image that is attached to a row in the answer of that row, after the answer text. See [Attachments](https://docs.withrealm.com/rfp/attachments.md).

When you choose **Write response** or **Turn responses into document** (see [Draft from a file or a questionnaire](#draft-from-a-file-or-a-questionnaire)), Realm puts each PNG or JPEG image that is attached to a row next to the text that answers that row. The document keeps its own copy of the image. Check the draft, and add an image yourself, as in [Add images](#add-images), if Realm did not place it.

### Pictures in templates

A template made from a Word file keeps the pictures of the file, such as a logo, in the same position. Realm keeps PNG, JPEG and WebP pictures. Other picture formats, such as EMF drawings, show as their description.

## Review and approve

Your team can review each section, add comments, and approve each section.

![The Outline tab with a section's status menu open on Approve and Assign](https://mintcdn.com/realm/xViU5Fe1e4lRVgR7/images/documents/section-status-menu.png?fit=max\&auto=format\&n=xViU5Fe1e4lRVgR7\&q=85\&s=ad719e66320237cab1685cfbdacadad3)

1. Select the text that you want to comment on, then add a comment. The comment stays attached to the selected text.
2. Type @ and the name of a teammate in the comment to assign it to that person. A comment on an approved section puts the section back in review.
3. Open the **Outline** tab. Each section shows a status icon.
4. Click the status icon of a section. You see the options **Approve** or **Unapprove**, **Assign**, and **N unresolved comments**, where N is the number of open comments on that section.
5. Choose the option that you need. Choose **Assign** to give the section to a teammate. Choose **N unresolved comments** to read the open comments.
6. Choose **Approve** for a section that has open comments. Realm asks you to **Resolve and approve**.
7. Choose **Resolve and approve**. Realm resolves the open comments and approves the section.
8. In a project document, choose **Approve document** in the options menu of the document when your team agrees with all of it. Realm approves every section.
9. Open the **My tasks** view. You see the sections and comments that are assigned to you.

Realm never sends the document to anyone. You decide when the document is ready and who gets it. For who can approve and what reopens a document, see [Approving a document](https://docs.withrealm.com/rfp/document-responses.md#approving-a-document).

## Export in your template layout

Export the approved document in your own template layout. An admin can set a default template layout. If your document has no template layout of its own, **Preview** and the Word, PDF and Google Docs exports use the template layout of the default template.

1. Choose **Preview**. You see the document in its template layout.
2. Choose **Export**. The export panel opens.
3. Select **Word**, **PDF**, **Markdown** or **Google Docs**. The panel shows the options for this format.
4. For Word, PDF and Google Docs, use **Match formatting of** to select the template layout. The list shows the saved templates of your organization and **Standard Realm style**.
5. Choose **Use as document template**. The document keeps this layout.
6. Complete the export. You get the finished file in the format that you selected.

Good to know:

* Regenerating an approved section puts it back in review.
* Press Ctrl+Z to undo a paragraph rewrite.
* Choose **Versions** to see earlier versions. An export of an earlier version uses that version.
* Realm never sends the document to anyone.

For uploading a new template layout and the other export options, see [Exporting](https://docs.withrealm.com/rfp/document-responses.md#exporting).

## Templates and tags

Templates are saved documents that you can start new documents from. To open the **Document Templates** page, click **Templates** on the Documents page, or click **Browse all templates** in the **+** menu.

### Add a template

![The Add template button on the Document Templates page, open on Add from the knowledge base and Upload a file as a template](https://mintcdn.com/realm/xViU5Fe1e4lRVgR7/images/documents/add-template-menu.png?fit=max\&auto=format\&n=xViU5Fe1e4lRVgR7\&q=85\&s=103382d793ab1f46a22cef2bee6878b9)

1. Open the **Document Templates** page and click **Add template**.
2. Choose **Add from the knowledge base** or **Upload a file as a template**. A Word file keeps its layout in the template.

### Manage a template

1. Point at a template and click **Show** to preview it.
2. Open the row menu and click **Use template** to start a new document from the template.
3. Open the row menu to **Rename** or **Delete** the template.

### Save a document as a template

1. Open the options menu of the document and click **Save as template**. Realm copies the document into a template.
2. To undo this, click **Remove from templates**.

### Give a template tags

1. Open the template and click its tag button.
2. Choose the tags for the template. A document that you start from the template outside a project gets those tags. When a new document has tags that match a template, that template is listed first under **Suggested**.

### Add a template layout to a skill

1. Open the skill and click **Add property**.
2. Choose **Template**. The skill can carry a template layout. See [Properties](https://docs.withrealm.com/agents/skills.md#properties).

### Set the organization default template

An admin sets the default template in **Organization settings**, under **Document template**. See [Document template](https://docs.withrealm.com/admin/organization-settings/overview#document-template).

For more on templates and tags, see [Templates](https://docs.withrealm.com/chat/special-features#templates) and [Knowledge tags](https://docs.withrealm.com/chat/special-features#knowledge-tags).

## If something does not work

Find the problem that you see in the list below. Then do the action that is next to it.

* **A section stays on Writing.** Open the **Plan** tab and click the regenerate button for that section. If the section was approved, it goes back to review.
* **The layout looks wrong.** In **Match formatting of**, choose **Standard Realm style** or a different template. Look at the result in **Preview**.
* **You have a different problem.** Report it to the Realm team.

To report a problem:

1. Write the name of the document and the name of the section.
2. Write what you did and what you saw.
3. Send the report to [support@withrealm.com](mailto:support@withrealm.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.