# Markdown Rendering

> How to reliably open a markdown file in a cmux right pane without it rendering blank. Use whenever opening/showing/rendering a .md file in cmux's right pane via `cmux markdown open`. Covers the move-surface blank-render bug and the only two reliable approaches — open it correctly the first time, or close the existing right pane(s) first then open a fresh right pane.

- **Type:** Skill
- **Install:** `agentstack add skill-davidondrej-skills-markdown-rendering`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [davidondrej](https://agentstack.voostack.com/s/davidondrej)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [davidondrej](https://github.com/davidondrej)
- **Source:** https://github.com/davidondrej/skills/tree/main/skills/agent-orchestration/markdown-rendering

## Install

```sh
agentstack add skill-davidondrej-skills-markdown-rendering
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Markdown Rendering in cmux

## The Problem

`cmux markdown open` defaults to **spawning a brand-new pane** every time, even with `--direction right`. The common "fix" — moving the new markdown surface into the existing right pane with `move-surface` — **bugs out: the moved viewer renders BLANK.** The surface keeps `type=markdown` and looks healthy, but shows nothing.

So you get stuck: either a stray extra pane, or a blank viewer after moving it.

## The Rule

You have exactly two reliable options. **Never `move-surface` a markdown viewer** — that is the path that bugs.

### Option A — Open it right on the first try

If there is no usable right pane yet, just let cmux create one and leave it where it lands:

```bash
cmux markdown open /abs/path/file.md --direction right --focus false
```

Do NOT then move it. If it spawned where you want it, you're done.

### Option B — Close existing right pane(s), then open fresh

If there are other right panes in the way (and they're unused or irrelevant), **close them first**, then open the markdown fresh as a new right pane:

```bash
# 1. find panes in THIS workspace
cmux list-panes --workspace "$CMUX_WORKSPACE_ID"

# 2. close the unused/irrelevant right pane(s) by closing their surfaces
cmux list-pane-surfaces --pane pane:NN
cmux close-surface --surface surface:XX     # repeat per surface in that pane

# 3. THEN open the markdown fresh — it creates its own clean right pane
cmux markdown open /abs/path/file.md --direction right --focus false
```

## Hard Rules

- **Never `move-surface` a markdown viewer.** It renders blank afterward. This is the core bug this skill exists for.
- Open it correctly the first time (Option A), OR close the conflicting right pane(s) and open a fresh right pane from scratch (Option B).
- Only close panes that are unused or irrelevant — never close a pane the user is working in.
- Always anchor to `$CMUX_WORKSPACE_ID`; never assume the visually focused workspace.
- Pass `--focus false` so you don't steal the user's focus.
- You can't screenshot/read a markdown surface to verify it. If unsure it rendered, ask the user.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [davidondrej](https://github.com/davidondrej)
- **Source:** [davidondrej/skills](https://github.com/davidondrej/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-davidondrej-skills-markdown-rendering
- Seller: https://agentstack.voostack.com/s/davidondrej
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.