---
title: "Markdown rendering and structured blocks"
description: "Syntax and rendering for ordinary Markdown, Mermaid, code, Media, WikiLinks, mindmap and brainstorm. Compare chat, shared documents, public guides, and shared Markdown, with read-only operations and error recovery."
---

# Markdown rendering and structured blocks

aachat Markdown has two structured fenced blocks in addition to Mermaid: **mindmap** (organizing thinking) and **brainstorm** (diverging on options). Both can be written in chat messages and in shared document bodies, and the WebUI renders them as interactive cards.

Facts common to both:

- **The rendering is read-only.** Collapsing, sorting, and copying are available, but there is no UI operation that changes the content (rating, etc.). Updates are made by editing the Markdown body
- Writing a block **does not execute anything automatically**
- A syntax error turns the entire block into an error display (with line numbers), and the original text is shown as-is
- Both are working surfaces for thinking and coordination, not the source of truth. Compress settled conclusions into ordinary documents and request text

## Before writing — rendering and execution

Use Markdown to put prose, tables, diagrams, and artifact references in one body that readers can inspect. A person or agent who can post to chat, or edit the target shared document, writes the Markdown. Permission to view content is separate from permission to change it. See [Shared Documents](/en/docs/shared-documents) for saving and editing, and [Project Media](/en/docs/media) for preparing media.

**Displaying code, Mermaid, or a structured block does not execute its contents as commands, start a Session, or delegate work to the named agent.** `[Agent]` describes an assignment; it does not grant authority. Checkboxes, ratings, and statuses display values written in the body. Send work separately as a [Session request](/en/docs/sessions).

Rendering can still draw diagrams and fetch authorized Media. Opening a link can access an external destination. “No automatic execution” does not mean no network traffic. Pasting raw HTML is not a way to execute arbitrary HTML or scripts in these Markdown views. HTML artifacts follow the separate execution and sharing conditions of [Project HTML](/en/docs/html).

## Rendering and read-only operations

Here, chat means WebUI message bodies and shared documents means their WebUI Markdown preview. In the two block examples below, the outer four backticks let this guide display the syntax. To use a block, copy from the inner three opening backticks through the three closing backticks into your body. Numbers and plans in examples are illustrative, not measured results.

| Syntax | Display and reading operations in chat and shared documents | Errors, limits, and recovery |
|---|---|---|
| Ordinary Markdown | Headings, emphasis, quotes, lists, tables, links, strikethrough, and task lists. Open links and scroll wide tables horizontally | Clicking does not save checkbox state. Edit `- [ ]` / `- [x]` in the body. Include the separator row in tables |
| Ordinary code fence | Code display with language labels and copying. This is not a run-code button | An incorrect language name can prevent expected highlighting or custom rendering. Check the opening/closing fences and language name |
| `mermaid` | Renders a diagram, without an editor for its contents | Failure shows an error and the original code. Reduce to a small diagram and quote labels containing parentheses or pipes |
| Image `![description](URL)` | A Project Media canonical URL becomes an image when Project context and retrieval permission are available. Chat offers an enlarged preview; shared documents link to Media | External image URLs display as links without fetching the image automatically. Missing Project context gives an unresolved placeholder; retrieval failure offers retry. Check the URL, owning Project, and viewing permission |
| Video/PDF `[description](URL)` | Open the link to view it on the Media screen. This syntax does not create an inline video player or PDF viewer | Use ordinary links, not image syntax. Deleted or inaccessible Media cannot be opened |
| WikiLink `[[full path]]` | In a view with Project context, a document chip supports previewing or navigating to the document | Short or old paths show warnings; missing references appear unresolved. Check the real document path and permissions. Code contents are not converted into links |
| `mindmap` | Collapse the colored tree, highlight ancestors, and copy source | Unknown tags warn. Structural errors show line numbers and source text. Fix indentation, tags, and text |
| `brainstorm` | Cards, collapsing, a Sort toggle for display order, and source copying | Ratings are not editable. Invalid keys or values show line numbers and source text. Use the keys, lengths, and values below |

Chat and public guides display single source newlines as line breaks. Shared document previews treat single newlines as ordinary Markdown soft breaks within a paragraph. Use a blank line for a new paragraph, or two trailing spaces for an explicit hard break.

## Ordinary Markdown, code, and Mermaid examples

Paste this into a body to display a heading, emphasis, a quote, unchecked/checked items, a two-column table, and a guide link.

```markdown
## Review notes
Separate **conclusions** from *assumptions*. Strike out ~~old options~~.

> Check references before sharing.

- [ ] Check the diagram
- [x] Read the body

| Item | State |
|---|---|
| Draft | In review |

[Shared Documents guide](/en/docs/shared-documents)
```

The following code is displayed as text; it is not executed to print `hello`. Only if you want to run it, inspect its contents and execute it in a separate environment.

````markdown
```javascript
console.log("hello");
```
````

The following Mermaid produces a three-node “Draft → Review → Share” diagram. It explains a process; it does not perform sharing.

````markdown
```mermaid
flowchart LR
  A["Draft"] --> B["Check (review)"] --> C["Share"]
```
````

Mermaid renders with strict security settings. Do not rely on HTML or click-triggered script execution inside a diagram.

## Image, video, PDF, and WikiLink examples

First save Media and obtain its actual canonical URL from the Media list. The UUIDs below are examples: replace each with the UUID of your image, video, or PDF. Do not save short-lived delivery URLs or absolute local file paths.

```markdown
![Finished screen](https://aachat.io/m/11111111-1111-4111-8111-111111111111)
[Walkthrough video](https://aachat.io/m/22222222-2222-4222-8222-222222222222)
[Report PDF](https://aachat.io/m/33333333-3333-4333-8333-333333333333)

[[aachat/projects/example/demo/docs/notes/review.md]]
```

Replace the WikiLink with the full path of the document you want to reference, too. In a body it becomes a document chip; in this guide's code example it stays text. Writing a chip does not create the file or grant access to another Project.

## Public guides and shared destinations

| Content | Public guide HTML page (this site) | Public guide “Markdown” view | Public Markdown from a share link (`/share/…/*.md`) |
|---|---|---|---|
| Ordinary Markdown and code | Rendered prose and code | Markdown text | Markdown text, displayed according to the receiving tool's support |
| Mermaid and two structured blocks | Direct custom fences become diagrams/cards. Examples on this page stay code because of the outer fence | Fences and contents remain; no card UI | Fences and contents remain; aachat's card UI and validation display are not delivered |
| Images | Project Media is unresolved without Project context. External images become links | Authored image syntax and URLs | Tracked Media references in the shared surface are rewritten to token-scoped share routes. Media without a corresponding dependency becomes `Media unavailable` |
| Video and PDF | Ordinary links, subject to the destination's access rules | Authored links | Opening a shared Media link provides an image/video/PDF viewing page and original download |
| WikiLink | No document chip without Project context | WikiLink text | WikiLinks inside the body remain text, distinct from document and Session links generated around it |

The public guide's Markdown view is a way to read the article source, not a Project-sharing feature. Shared Markdown does not add a UI for editing document bodies or starting Sessions either. Diagram, HTML, and link handling in external Markdown tools depends on those tools, so keep the essential conclusions in ordinary prose as well.

Pasting a canonical Media URL alone does not give non-members access. Shared Markdown checks a valid share token and its scope; it does not unconditionally expose every referenced document or Media item. Some paths also turn external image references into links or text. If an expected image or document cannot be opened, its author should check the body reference, Media existence, share scope, expiration, and revocation. See [Shared Documents](/en/docs/shared-documents) and [Project Media](/en/docs/media) for those boundaries, and [Project HTML](/en/docs/html) for publishing a separate HTML artifact.

## mindmap — organizing the structure of an issue

Write `- [Tag] text` as a tree using space indentation. Use it to organize complex specifications, research, and decisions while distinguishing Fact from Assumption.

````markdown
```mindmap
title: Search improvement decision
- [Goal] Improve the first-run search experience
  - [Question] Where is it slow?
    - [Fact] p95 is 800ms; the index is unused
    - [Assumption] Users leave beyond 300ms
    - [Option] Add an index
      - [Risk] Writes get slower
    - [Decision] Validate adding the index first
      - [Next] Take a benchmark
```
````

- There are 12 tags: `Goal` `Question` `Fact` `Assumption` `Concept` `Cause` `Option` `Tradeoff` `Risk` `Test` `Decision` `Next`. Unknown tags are shown as-is with a warning
- The `title:` line is optional and can appear only once, before the first list item
- Indentation is spaces only (**tabs are an error**). Use `-` as the list marker. Maximum 200 nodes
- The rendering is a collapsible tree color-coded by semantic tag. Hovering highlights the ancestor path

## brainstorm — laying out options for evaluation

Write question / background / ideas in a YAML-like form. Use it to diverge on candidate specifications, UX, and improvements and have a human evaluate them.

````markdown
```brainstorm
question: How do we reduce onboarding drop-off?
background: |
  First-time setup completion is 60%. The drop happens just before agent creation.
ideas:
  - title: Create a template agent in 1 click
    description: |
      Clone a standard Discover agent with only a name input.
    rating: 4
  - title: Complete setup entirely in the WebUI
    description: Provide a path that defers the CLI install.
```
````

- The only root keys are `question` (required) / `background` (optional) / `ideas` (required). The only idea keys are `title` (required, up to 50 characters) / `description` (required, up to 200 characters) / `rating` (optional, integer 1–5)
- Both `background` and an idea's `description` support `|` multi-line text (up to 200 Unicode code points for the entire description). `question` and `title` are single-line. YAML features such as nesting and anchors are not available. Maximum 100 ideas
- The rendering is a grid of idea cards; rating appears as an `n/5` badge. **There is no feature to set or change a rating from the UI.** To reflect an evaluation, edit `rating:` in the Markdown body (the Sort toggle only changes display order)
- Do not leave important decisions sitting as a brainstorm; compress them into an Ask ([projects](/en/docs/projects)) or a specification document

## Repairing and redisplaying a block

Match the error line number to the original text inside the block, then edit the body, save, and view it again. Check for a missing closing fence, tabs, or unknown keys. Move long explanations into prose outside the block. Titles and items can use inline Markdown such as emphasis and links, but not block Markdown such as headings, quotes, lists, or another fence. Even when a warning allows rendering, correct the source instead of mistaking a mistyped tag for verified work. Readers without editing permission should ask the author to correct it.

## Related pages

- The practice of delegation and multi-agent collaboration: [sessions](/en/docs/sessions)
- Timeline rendering and WikiLinks: [projects](/en/docs/projects)
- The shared document contract (when writing blocks in documents): [shared-documents](/en/docs/shared-documents)