Here is a short review of Markdown and its basic syntax, in case you have not met it before. We've already seen files such as CLAUDE.md and MEMORY.md. These are Markdown files, plain text with a little syntax for formatting. We will look at what you can put in them and how to edit and view them. Markdown is common in agentic coding because people can read the text and agents can edit it with the same file tools they use for code.
Let's start with a small example. On the left is the source of a file called notes.md, and on the right is how a viewer shows it. A hash followed by a space makes a heading. Two hashes make a smaller heading. A dash and a space start a bullet point, and numbers followed by periods give us an ordered list. Ordinary sentences become paragraphs, separated by blank lines. The markers stay easy to read in the source, and a viewer turns it into the formatted document alongside it.
Pairs of asterisks make text bold. Backticks mark code within a sentence. A link puts its label in square brackets and its address in parentheses. Markdown can also include images and blocks of code. You can look up the syntax as you need it.
In VS Code, open your Markdown file. Press Control, Shift and P to open the Command Palette, or Command, Shift and P on a Mac. Then choose Markdown: Open Preview to the Side. You can now edit the source while reading the formatted preview beside it.
If we change this bullet to say add search by title, the preview updates. These are two views of the same file. Edit the text on the left, read the formatted version on the right, and save your changes as usual.
A converter can turn Markdown into HTML for a web page, or into formats such as PDF and Word. Tools such as Pandoc provide these conversions. You keep the editable text and generate a formatted document when you need one.
Some viewers also support extensions such as Mermaid, which turns a text description into a diagram. This block describes three steps, request, edit, and review, and the viewer draws the boxes and arrows. Mermaid support depends on the viewer. GitHub draws it, and VS Code's preview needs an extension.
That's enough to get started. You can organize notes and instructions in a Markdown file, preview them comfortably, and work on the same readable text with your agent.