When creating Markdown (.md) files to standardize prompt instructions or best practices, clarity, consistency, and structure are paramount. Below is a comprehensive guideline on how to structure these files and what to do-and avoid-when authoring them.
- Clarity: Use Markdown to make prompts and instructions easy to read, both for humans and AI models[6][8].
- Consistency: Stick to a single Markdown flavor (e.g., CommonMark, GitHub Flavored Markdown) throughout your project[5].
- Explicitness: Clearly state roles, expected outputs, and formatting requirements[6][7].
-
Front Matter (Optional but Recommended)
- Use YAML front matter for metadata (title, author, date, description)[2].
- Example:
--- title: Prompt Engineering Best Practices author: Jane Doe date: 2025-04-30 description: Guidelines for structuring prompt instructions in Markdown. ---
-
Title and Introduction
- Start with a single H1 heading that matches the filename or topic[4].
- Provide a concise introduction (1–3 sentences) explaining the document’s purpose[4].
-
Table of Contents (TOC)
- Add
[TOC]after the introduction if your platform supports it, to enhance navigation for longer documents[4].
- Add
-
Sectioned Content Using Headings
- Use H2 (
##) for main sections and H3 (###) for subsections[4][8]. - Example:
## Structuring Prompts ### Step-by-Step Instructions
- Use H2 (
-
Best Practices and Examples
- Use bulleted lists for unordered items and numbered lists for ordered steps[3][5][8].
- Highlight key points with bold (
**text**) or italics (*text*)[3][8]. - Include fenced code blocks for sample prompts or output, specifying the language if relevant[5].
- Example:
**Do:** - Use clear section headings. - Specify expected output format. - Break down complex instructions into steps. **Don't:** - Mix Markdown with other document formats. - Overcomplicate with unnecessary detail.
-
Formatting and Accessibility
- Use horizontal rules (
---) to separate major sections[8]. - Add alt text to images for accessibility[3].
- Keep lines at or below 80 characters for readability, except for links or tables[4].
- Use horizontal rules (
-
References and Further Reading
- End with a “See Also” or “References” section for additional resources[4].
| Do’s | Don’ts |
|---|---|
| Use a single H1 title per document[4] | Use multiple H1 headings |
| Start with a short, clear introduction[4] | Skip context or purpose |
| Add a TOC after the intro for long docs[4] | Place TOC at the end or in the middle |
| Use clear, descriptive section headings[4][8] | Use ambiguous or generic headings |
| Prefer bulleted/numbered lists for clarity[3][5][8] | Use long, dense paragraphs |
| Provide sample prompts and expected outputs[6][7] | Leave instructions vague or open-ended |
| Specify formatting/output requirements[6][7] | Assume the reader/model knows your preferred format |
| Keep instructions concise and explicit[6][7] | Overload with unnecessary details |
| Use fenced code blocks for examples[5] | Mix code and prose in the same block |
| Use bold/italics for emphasis[3][8] | Overuse formatting, making text hard to read |
| Maintain consistent Markdown flavor and style[5] | Mix different Markdown syntaxes |
| Organize files in a logical directory structure[5] | Scatter related files across unrelated directories |
---
title: Prompt Engineering Best Practices
author: Jane Doe
date: 2025-04-30
description: Guidelines for structuring prompt instructions in Markdown.
---
# Prompt Engineering Best Practices
A concise guide to creating clear, effective prompt instructions using Markdown.
[TOC]
## Structuring Your Prompt
- **Start with context:** Briefly explain the task or goal.
- **Specify roles:** e.g., “You are an expert editor...”
- **Break down steps:** Use numbered lists for step-by-step instructions.
- **Define output format:** e.g., “Respond in Markdown table format.”
## Do’s
- Use headings to separate sections.
- Provide sample input and expected output.
- Keep instructions concise and explicit.
## Don’ts
- Don’t mix Markdown with other document formats.
- Don’t skip specifying output format.
- Don’t use multiple H1 headings.
## Sample Prompt
Summarize the following text as a bullet point list.
Text: """ {Insert text here} """
- Point 1
- Point 2
## See Also
- [OpenAI Prompt Engineering Guide]
- [Markdown Style Guide]
- Preview your Markdown files to catch formatting errors before sharing[3].
- Escape special characters when needed (e.g.,
\*for a literal asterisk)[2]. - Use descriptive link text, not just “click here”[2].
- Keep document structure logical and easy to navigate[5].
By following these guidelines, your prompt instruction Markdown files will be clear, maintainable, and effective for both humans and AI models[4][5][6][7][8].
Sources [1] Prompting: Experimenting with Markdown (with Example of Multi ... https://www.linkedin.com/pulse/prompting-experimenting-markdown-example-test-data-generation-verma-toiuf [2] Best practices and tips in markdown https://technicalwritingmp.com/docs/markdown-course/best-practices-and-tips-in-markdown/ [3] 13 must-know Markdown tips and tricks - TechTarget https://www.techtarget.com/searchsoftwarequality/tip/Must-know-Markdown-tips-and-tricks [4] Markdown style guide | styleguide - Google https://google.github.io/styleguide/docguide/style.html [5] Markdown Best Practices for Documentation https://www.markdowntoolbox.com/blog/markdown-best-practices-for-documentation/ [6] How To Write Effective AI Prompts (Updated) - Daniel Miessler https://danielmiessler.com/blog/how-i-write-prompts [7] Best practices for prompt engineering with the OpenAI API https://help.openai.com/en/articles/6654000-best-practices-for-prompt-engineering-with-the-openai-api [8] Streamline Your Prompts with Markdown: A Quick Guide for Better ... https://nfps.ai/tutorials/prompt-with-markdown/ [9] Ultimate Markdown guide: 5 rules to know - TechTarget https://www.techtarget.com/searchsoftwarequality/tip/Ultimate-Markdown-guide-Rules-to-know [10] 10 Markdown Tips for Creating Beautiful Product Documentation in ... https://dev.to/auden/10-markdown-tips-for-creating-beautiful-product-documentation-in-2025-5ek4 [11] Understanding Prompt Structure: Key Parts of a Prompt https://learnprompting.org/docs/basics/prompt_structure [12] Do you write your prompts in Markdown? : r/PromptEngineering https://www.reddit.com/r/PromptEngineering/comments/17aktzb/do_you_write_your_prompts_in_markdown/ [13] 10 Quick Tips About A Great Markdown Editor - Froala https://froala.com/blog/editor/10-quick-tips-about-a-great-markdown-editor/ [14] (opinionated) Simple (and obvious) best practices for the Prompt https://community.openai.com/t/opinionated-simple-and-obvious-best-practices-for-the-prompt/984955 [15] Markdown Cheat Sheet https://www.markdownguide.org/cheat-sheet/ [16] What is the best practice for code runner for markdown files? #6629 squidfunk/mkdocs-material#6629 [17] Creating Instructions with Markdown Syntax - Skillable https://docs.skillable.com/docs/creating-instructions-with-markdown-syntax [18] Markdown Blocks Tips and Tricks - NocoBase https://www.nocobase.com/en/tutorials/clever-uses-of-markdown-blocks [19] Creating Beautiful Markdown Files in GitHub. - DEV Community https://dev.to/danishzayan/creating-beautiful-markdown-files-in-github-5ga3 [20] Basic writing and formatting syntax - GitHub Docs https://docs.github.com/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax [21] Novel organizer for markdown files : r/linuxquestions - Reddit https://www.reddit.com/r/linuxquestions/comments/18eam63/novel_organizer_for_markdown_files/ [22] Markdown Guide https://www.markdownguide.org [23] Markdown style guide - Gruntwork Docs https://docs.gruntwork.io/guides/style/markdown-style-guide/ [24] What is the right way to arrange the content folder and md files - HUGO https://discourse.gohugo.io/t/what-is-the-right-way-to-arrange-the-content-folder-and-md-files/45276 [25] Extended Syntax - Markdown Guide https://www.markdownguide.org/extended-syntax/ [26] How to maintain a good folder structure? : r/ObsidianMD - Reddit https://www.reddit.com/r/ObsidianMD/comments/16ebwaz/how_to_maintain_a_good_folder_structure/ [27] Markdown for Technical Writers: Tips, Tricks, and Best Practices https://israelmitolu.hashnode.dev/markdown-for-technical-writers-tips-tricks-and-best-practices [28] Markdown - Wikipedia https://en.wikipedia.org/wiki/Markdown [29] Is the best digital workplace just a bunch of Markdown files? https://luhr.co/blog/2024/09/02/markdown-files-as-the-digital-workplace/ [30] Basic Syntax - Markdown Guide https://www.markdownguide.org/basic-syntax/ [31] Prompts with Markdown format are better? : r/ChatGPT - Reddit https://www.reddit.com/r/ChatGPT/comments/1gfgvhc/prompts_with_markdown_format_are_better/ [32] Getting Started | Markdown Guide https://www.markdownguide.org/getting-started/ [33] How To Write Better & Cleaner Markdown: The Definitive Guide https://dev.to/soumikdhar/how-to-write-better-cleaner-markdown-the-definitive-guide-3fif [34] How to Organize Your Writing with Markdown https://redeemingproductivity.com/markdown/ [35] Introductory Guide to Markdown for Documentation Writers https://document360.com/blog/introductory-guide-to-markdown-for-documentation-writers/