---
title: "Markdown documents"
description: "Write documents directly in Ocho and publish them into search."
canonical: https://ocho.bot/docs/library/markdown-documents
last_updated: 2026-07-12
---

# Markdown documents

> Write documents directly in Ocho and publish them into search.

Besides uploading files, you can author documents inside Ocho with a rich markdown editor, then publish them into the searchable corpus.

> Who can do this: users with the markdown editor role (`document_markdown_editor`). Everyone can read published documents.

## Create a markdown document

1. Open the document library — the **Documents** card on the Home page    (subtitle "Library"); it opens the document library page, heading    "Documents", subtitle "Org-wide document library. Upload once, attach to    any dataset." Note this is not the sidebar **Documents** item, which opens    the documents table and has no authoring controls. 2. Click **New markdown document**. In the dialog, enter a **Name** and click    **Create draft**. (You can also create one from a chat answer with    **Save to Library**.) 3. The draft opens in the editor. New empty documents start in edit mode;    existing documents open in read mode with an **Edit** button.

## Write

The editor supports rich formatting with slash commands — type `/` for headings, tables, task lists, code blocks, and more (menu items show short aliases, e.g. "Task List · Todo · Check"). Pasting markdown-formatted text from another tool is detected and rendered as rich content automatically.

## Save, publish, or discard

- **Save draft** — keeps your work without touching the published version.

Documents with unpublished changes are labeled "Unpublished draft";   never-published drafts also show "Draft (not yet published)".

- **Publish** — replaces the searchable version. Clicking it opens a

confirmation, "Publish to RAG corpus?" — confirm with **Publish**.   Re-indexing typically takes ~10–30 seconds; the previous version remains   searchable until the new one finishes indexing. Publish is disabled while   the document is empty ("Add some content before publishing").

- **Discard draft** — appears only while editing and only when you have

unpublished changes. It asks "Discard draft?"; confirm with **Discard** to   delete your unpublished changes. The published version, if there is one, is   untouched — but a draft that has never been published is deleted entirely.

## Good to know

- A draft is not searchable until you publish it.
- Citations pointing at an older version of the document temporarily lose

their exact highlight after you publish; they recover once re-indexing   completes.

- Non-markdown uploads (PDFs and the like) can't be edited in the markdown

editor. Uploaded `.md` files can: their overview shows a "Markdown preview"   section — click **Edit** to write or paste the content, then Save and   Publish to make it previewable and refresh the corpus. Re-uploading the   original file works too.

All docs: https://ocho.bot/docs

---

Ocho — AI knowledge orchestration · [Home](https://ocho.bot/) · [Docs](https://ocho.bot/docs) · [Blog](https://ocho.bot/blog) · [About](https://ocho.bot/about) · [Developers](https://ocho.bot/developers) · [Contact](https://ocho.bot/contact) · [llms.txt](https://ocho.bot/llms.txt)