--- title: "Rendered vs raw: when to read agent Markdown each way" slug: rendered-vs-raw-agent-markdown excerpt: "Rendered Markdown is faster to skim. Raw text shows what is really in the file. Which view to use for plans, tables, headers, links and diffs." quickAnswer: "Read agent Markdown rendered when you want to understand it, and raw when you need to know exactly what the file says. Skim plans and handoffs rendered. Check tables rendered first, then raw if the columns look off. Check front matter, link targets, file paths and hidden problems like trailing spaces or an unclosed code fence in the raw text. To see what changed, diff the raw text." keyTakeaways: - Rendered is for understanding a file. Raw is for checking exactly what it says. - A link's text can differ from its target. The raw text shows the target without hovering or clicking. - HTML comments, trailing spaces and backslash escapes are hidden on most rendered pages. - Check what changed by diffing the raw text, then read the result rendered if it helps. - Sashmark is being built as a reader for the rendered side, with a Changes View and a Frontmatter Table planned for v1. publishedDate: 2026-10-20 dateModified: 2026-10-20 author: Bobby Huang cluster: A role: post status: published faq: - q: What is the difference between rendered and raw Markdown? a: "Raw Markdown is the plain text in the file, with symbols like #, * and | still in it. Rendered Markdown is what a viewer draws from that text, with real headings, bold words and tables. Both come from the same file." - q: How do I see the raw text of a Markdown file? a: Open it in any plain text editor, or run cat or less on it in a terminal. A .md file is plain text, so nothing special is needed. - q: Can a rendered page hide something an agent wrote? a: Yes. HTML comments, trailing spaces and the real target of a link usually do not show on the rendered page. Check the raw text when the exact contents matter. related: - how-to-review-markdown-your-ai-agents-write - see-what-changed-in-a-markdown-file - markdown-syntax-guide - open-and-read-a-markdown-file-on-mac-windows-linux --- Every Markdown file can be read two ways. The raw text is what the agent actually wrote, symbols and all. The rendered page is what a viewer draws from that text. Most of the time they agree. Sometimes they don't, and that is where review mistakes slip through. This guide gives you a simple rule for which view to use for common review jobs. It is part of a series on [reviewing the Markdown your AI agents write](how-to-review-markdown-your-ai-agents-write.md). That guide covers the full review loop. This one goes deeper on the rendered or raw choice. ## The short rule Read rendered to understand a file. Read raw to check exactly what it says. Rendered pages are built for people. Headings stand out and tables line up. That makes a long plan quick to skim. Raw text is built for accuracy. Every character is there, including the ones a renderer hides or turns into something else. When a detail must be right, the raw text is the record. ## A decision list for common jobs | Review job | Start with | Switch to raw when | |---|---|---| | Skim a plan or handoff | Rendered | You need to copy an exact command or id | | Check a table | Rendered | Columns look shifted, or a cell is empty or missing | | Check front matter | Raw YAML, or a key and value table | Always check raw before you edit it | | Check links and paths | Raw | Raw shows the target without hovering or clicking | | Check what changed | A diff of the raw text | Always; read the diff rendered only if that helps | | Spot hidden problems | Raw | Trailing spaces, comments or an unclosed code fence | The sections below explain each row. ## 1. Skim a plan: rendered A plan or handoff is mostly headings, lists and short notes. Rendered, you can see its shape at a glance. The parts that need you stand out. Stay in rendered for the first pass. Switch to raw only when you need to copy something exact, like a command or a long id. Copying from a rendered page can drop characters a renderer used for formatting. ## 2. Check a table: rendered, then raw Start rendered. A table that lines up and has the right number of columns is usually fine. If the columns look off, open the raw text. Two common causes: - **A pipe inside a cell.** A `|` in a cell starts a new column. Agents often write this inside a command like `cat log | grep error`. Escape it as `\|` or move the command out of the table. - **A row with extra cells.** Under the GFM table rules, a row with more cells than the header row loses the extra cells. They are simply not drawn. The rendered table looks tidy, and a value is gone. To catch it, count the cells in each raw row and compare with the header row. ## 3. Check front matter: raw YAML or a key and value table Front matter is the YAML block between two `---` lines at the top of a file. Renderers treat it in different ways. Some hide it. Some show it as a table. A renderer that does not know about front matter may draw it as a line and a big heading. For a quick status check, a key and value table is the easiest to read. For anything exact, read the raw YAML. Quotes, colons and indentation change what a value means, and none of them show in a table. The [syntax guide](markdown-syntax-guide.md) covers front matter basics. ## 4. Check links and paths: raw A Markdown link has two parts: the text you see and the target it points to. The rendered page shows only the text. Here is a made-up example from a handoff: > Raw: `See [the current plan](plans/old-plan-v1.md) before you start.` > > Rendered: See the current plan before you start. The words say "current plan". The target is an old file. On the rendered page you would only learn that by hovering or clicking. In the raw text it is right there. Agents also write relative paths that only work from one folder. A link that looks fine rendered may point at a file that does not exist. To list the common `[text](target)` links in a file at once, run: ``` grep -o '\]([^)]*)' plan.md ``` Each match looks like `](plans/old-plan-v1.md)`. The part inside the parentheses is the target. Check that each path exists. This search misses reference-style links, which put the target on a separate line that starts with `[name]:`, so look for those too. ## 5. Check what changed: diff the raw text When an agent rewrites a file, compare the raw text before and after. A diff of raw text is exact. It catches changes that would never show on a rendered page, like a changed link target or a removed comment. The [guide to seeing what changed in a Markdown file](see-what-changed-in-a-markdown-file.md) walks through line diffs, word diffs and rendered diffs, with and without git. Start with the raw diff. Use a rendered diff as a reading aid, not as the final check. ## 6. Spot hidden problems: raw Some problems are invisible by design. Here is a made-up file with two of them: > Raw, line 1: `Status: ready for review` > > Raw, line 2: `` Most renderers hide HTML comments. The rendered page says only "Status: ready for review". The raw text admits the tests were never run. Agents do leave notes like this, so a quick search is worth it: ``` grep -n '