Prompts That Return Clean Markdown
Say which heading level the output starts at, forbid the wrapper code fence, and bound how much structure is allowed. Markdown is read by people, so its failures are cosmetic rather than fatal — which is exactly why they survive review and reach the published page.
Markdown output rarely breaks anything, and that is the problem: a document whose headings start one level too deep, or that arrives wrapped in a code fence, gets pasted in and fixed by hand every single time. This guide covers the instructions that stop that, and the line between markdown and the two shapes either side of it.
By Andrei Bădulescu, Founder at VantagePrompt·Updated
Markdown is the default shape for anything a person reads and something else renders — release notes, a README section, a summary that lands in a wiki. Its failure mode is not corruption but friction: output that is correct and needs five minutes of tidying before it can be used, every time.
Why does heading depth need to be stated?
Because the model does not know what surrounds the output. Asked for a section, it will usually start at #, which is the document title level — so pasting it into a page that already has a title produces two H1s, and every heading below it is one level too shallow.
One sentence fixes it permanently: "Start headings at level 2 (##); never use level 1." If the output nests, bound the depth too — "no heading deeper than ###" — because unbounded nesting is how a 400-word section acquires a five-level outline.
Format: Markdown. Start headings at "##" and never go deeper than "###".
Do not include a document title. Do not wrap the response in a code fence.How do I stop the whole answer arriving in a code fence?
Ask for it not to be, in those words. The wrapper fence appears because "return markdown" reads to the model as "return markdown source", and source is something you show rather than render — so it helpfully shows it.
Worth separating from the legitimate case: code blocks inside the answer are fine and should stay. What you are forbidding is the outer fence around the entire response. Say "do not wrap the response in a code fence" rather than "no code fences", or you will lose the ones you wanted.
How much structure is too much?
Markdown invites structure, and a model that has been asked for markdown will supply it whether or not the content has any: three sentences of explanation become a bulleted list of three fragments, each of which is now harder to read than the sentence it replaced.
Bound it the same way you bound heading depth. "Use bullets only for genuine lists of three or more parallel items; write explanation as prose" keeps the formatting doing work rather than decorating.
Bullets that each run to two or three sentences are paragraphs wearing bullet points. The list is not helping — it is just adding a dot to every paragraph and removing the connective tissue between them.
What about front matter and metadata?
If the output goes into a static site or a docs pipeline, say so and specify the block exactly — the delimiter, the keys, the quoting. Front matter is the one part of a markdown document that is machine-read, which makes it a key contract rather than a formatting preference, and it deserves the same treatment as a JSON contract.
The most common failure is a date. Say the format — "date: YYYY-MM-DD, quoted" — because otherwise you get whichever of five representations the model reached for, and the build breaks on the one day nobody is watching.
Markdown, prose, or list — which one am I actually asking for?
| Shape | The reader wants | Signal it in your input with |
|---|---|---|
| markdown | To scan: headings, short sections, maybe one small table. | "top 5", "best", "give me a list of", "a short guide to" |
| list | To follow or check off: steps, options, a checklist. | "steps", "checklist", "options" |
| prose | To read: an argument or explanation that holds together. | no structural signal at all |
When VantagePrompt resolves your prompt to the markdown shape, the optimized prompt carries a mixed-section skeleton — headings, bullets, and at most one short table. That "at most one" is the same instinct as bounding structure by hand: markdown output that turns into three tables has stopped being a document and become a report nobody asked for.
Frequently asked questions
- How do I stop the model wrapping the whole answer in a code fence?
- Say "do not wrap the response in a code fence". Phrase it that way rather than "no code fences", so that code blocks inside the answer — which you usually want — are not removed along with the outer wrapper.
- How do I control heading levels in generated markdown?
- State the starting level and the maximum depth: "start headings at ## and never go deeper than ###; do not include a document title". Without it the model starts at #, which collides with the title of whatever page you paste it into.
- Why does every explanation come back as bullet points?
- Because asking for markdown reads as asking for structure, and the model supplies it whether the content has any. Add "use bullets only for genuine lists of three or more parallel items; write explanation as prose".
- Can I get YAML front matter in the output?
- Yes, and it should be specified exactly — delimiter, keys, and value formats, including the date format. Front matter is the machine-read part of a markdown file, so treat it as a key contract rather than a formatting preference.
- When should I ask for prose instead of markdown?
- When the answer is an argument rather than a reference. Prose is the right shape when the connections between points carry the meaning; markdown is right when the reader will scan for one section and skip the rest.
Sources
structured prompts to try
Browse all structured promptsPublished by the community and free to copy — worked examples of what this guide describes.
Put it into practice.
Run this technique in the optimizer.