I Thought Markdown Was Fine for Prompts | 3 Situations Where You Need to Switch Formats
I had always thought that prompts should just be written in Markdown.
Set the objective with headers and list the conditions with bullet points. That usually works well. I didn't really understand the reason to go out of my way to use JSON or YAML. I even thought, 'Does YAML even have a place here?'
However, I still had a lingering feeling of, 'Is that really true?' So, I looked into it.
In conclusion, Markdown is basically correct. However, there are three moments where Markdown alone becomes a bit difficult, and switching formats just for those instances makes things more stable.
🗺️ What can AI generate?
Before getting into the discussion of formats, let's broaden our perspective a bit. This is because the 'targets' to which we pass prompts are expanding beyond just text.
Text
Articles, summaries, proofreading, translation, emails, FAQs
Images
Thumbnails, illustrations, image editing, variation generation
Video
Short clips, image-to-video conversion, shot sequence specification
Audio
Narration scripts, sound effects, BGM fragments
Design assets
Icon concepts, color schemes, banners, logo roughs
Code
Implementation, fixes, reviews, test generation
Settings, specifications, and templates
Configuration files, schemas, standard forms
Structured data
Tables, tagging, classification, extraction results
Processes and procedures
Checklists, production flows, recipes
📋 Suitable formats for each type of output
When the target audience changes, the 'shape' of the information you include in your prompt also changes. Here is a rough summary of the formats suitable for each.
Text (articles, summaries, proofreading)
Markdown. Simply writing the purpose, conditions, prohibitions, and examples usually works well.
Images/Videos
Markdown is the standard (for composition, direction, duration, etc.). Only add JSON when you need to fix ratios or sizes.
Audio (narration)
Markdown. You can pass the script as is.
Code
Markdown (requirements, constraints, test perspectives) + JSON when input/output examples are complex.
Structured data (classification, tagging, extraction)
Instructions in Markdown, source material in CSV or JSON. The key is to separate the instructions from the data.
Configuration/Specification files
Follow the format specified by the tool (YAML / TOML / JSON, etc.).
When you want to classify 50 lines of material at once, or when you want to consistently output a specification document with 10 mandatory items every time—how stable can you be with just Markdown? This breakdown provides a hint for that.
📝 Markdown is fine for the basics
First, as a premise, a prompt is a document written by humans, read back by humans, and corrected by humans. It is also sometimes shared within a team.
Markdown is a writing style that allows you to express headings and bullet points with simple symbols. You can create headings with `#` or bullet points with `-`. It can be displayed in many tools such as GitHub and Notion.
Markdown is well-suited for such documents. It is fast to write, easy to read back, and tool-agnostic. AI can also read it without difficulty.
As long as it is used as a "design document for humans to read," Markdown functions sufficiently. My impression did not change even after looking into it.
However, as the ways you use it increase, the story changes a little.
🔄 3 Situations Where Markdown Becomes Difficult
When you don't want to drop mandatory fields
Even though I want it to output in the same structure every time, for some reason, items are slightly missing. The expressions fluctuate.
Because Markdown has a high degree of freedom, AI also operates by filling in the blanks with "it probably intends this." This is not a problem for one-off use. However, when you use the same prompt repeatedly, a different approach seems better for situations where you want it to return in a stable form every time.
What came up during my research is the method of explicitly stating the necessary items in JSON. JSON is a format where you write item names and values as a set. For example, if you pass items like "title," "target audience," and "character count" as a structure, it becomes easier for the AI to accept that "this is a frame that must be included." It is like passing it as a frame rather than writing "please include ~" in text.
When you want to pass a large amount of data as is
I want to tag 50 product names. I want it to read trends from a 100-line list.
When you pass data in bullet points, it seems that the AI can easily confuse the "list of instructions" and the "list of data."
In such cases, it is easier to stabilize by keeping the instruction part in Markdown and passing only the data in CSV. CSV is a text format separated by commas, which can also be opened in Excel. It is the idea of passing "instructions" and "materials" in separate formats.
When the tool you use determines the format
As you use AI, situations will arise where you use it in combination with specific tools or services. Some of those tools specify that you must "write prompts and settings in YAML format."
YAML is a way of writing configuration files that expresses hierarchy through indentation. It is easy for humans to read and is often used as a configuration file for tools.
In this situation, it appears more like "this is the common language in that tool's world" rather than "choosing it because it is convenient." It is enough to just follow the format specified by the tool, and there is almost no need to choose it yourself.
💡 What I learned from my research
To summarize, it looks like this.
Markdown is the default. Since prompts are design documents meant for humans to read, this works well most of the time.
Use JSON to specify fields when you need to lock in mandatory sections. Use CSV to pass large amounts of data separately. Follow the format if a tool specifies one.
I think it's enough to be able to come back to this when the situation arises, rather than trying to memorize everything right now.
It's not about increasing the number of formats, but simply separating their use cases.
Since realizing that, I feel like I have a little less hesitation when writing prompts.
Afterword
Thank you for reading this far.
I was curious about how to choose between Markdown, YAML, and JSON, so I looked into it.
I had fun making new discoveries while researching, but in the end, I just felt like Markdown is fine after all lol
What do you all think?
Please feel free to make use of this.
It would encourage me if you could 'follow' or 'like' this! I look forward to your continued support!
🔗 Reference Links
いいなと思ったら応援しよう！
気に入っていただけたら、チップで応援してもらえると嬉しいです。
いただいた応援は、今後の記事作りの励みになります！