Problem: Missing spaces after heading markers

❌ ##Heading without space
✅ ## Heading with proper space

Why it matters: Without the space, Markdown processors won't recognize the heading and will render it as plain text.

Best Practice:

• Always use # , ## , ### (hash + space + text)
• Maintain logical heading hierarchy (don't skip levels)
• Leave blank lines before and after headings

Problem: Inconsistent bullet points or missing blank lines

❌ * Item 1
- Item 2
+ Item 3
No blank line before this paragraph

✅ * Item 1
* Item 2
* Item 3

Blank line separates list from paragraph

Nested Lists:

* Main item
  * Nested item (2 spaces indent)
  * Another nested item
* Back to main level

Problem: Using wrong syntax for different code types

❌ `for single line code should use backticks`
❌ ```python
print('this is correct')

✅ for single line code use backticks ✅ ```python print('this is correct')

Inline vs Block:

• Single backticks like this for inline code
• Triple backticks for multi-line code blocks
• Add language identifier for syntax highlighting

Problem: Misaligned table pipes

❌ |Column 1|Column 2|
|---|---|
|Value 1|Value 2|

✅ | Column 1 | Column 2 |
| --- | --- |
| Value 1  | Value 2  |

Tips:

• Add spaces around pipe characters for readability
• Keep separator lines aligned with header rows
• Use right alignment for numbers: |---:|

Problem: Incorrect alt text or title attributes

❌ ![Image](url)
✅ ![Descriptive alt text](url "Optional title")

❌ [Link text](url)
✅ [Link text](url "Optional title")

Best Practices:

• Always include descriptive alt text for images
• Use title attributes for additional context
• Escape special characters in URLs when needed

Problem: Unescaped special characters

❌ *emphasis with asterisks*
❌ _underline with underscores_

✅ \*emphasis with escaped asterisks\*
✅ \_underline with escaped underscores\_

Common characters to escape:

• \* (asterisk)
• \_ (underscore)
• ``` (backtick)
• \\ (backslash)
• \# (hash)

Problem: Unnecessary HTML in Markdown

❌ <div>Custom HTML</div>
✅ Use pure Markdown when possible

❌ <span style="color: red">Red text</span>
✅ Accept limited HTML for specific needs

Guidelines:

• Prefer pure Markdown syntax
• Use HTML only when Markdown can't achieve the needed formatting
• Test HTML rendering across different platforms

Problem: Improper quote formatting or nesting

❌ > Quote without blank line
Regular text

✅ > Proper quote with blank lines

Regular text

> > Nested quote
> Still in nested quote

Back to main quote

Problem: Using wrong characters for rules

❌ --------------------
✅ ---
✅ ***
✅ ___

Problem: Inconsistent line endings or trailing spaces

Solutions:

• Use LF (\n) line endings consistently
• Remove trailing spaces at line ends
• Use a text editor with visible whitespace

Problem: Broken reference-style links

❌ [link text]
[link text]: /url

✅ [link text]
[link text]: /url

Problem: Inconsistent checkbox syntax

❌ [x] Completed
[ ] Pending
- [ ] Wrong bullet type

✅ - [x] Completed
- [ ] Pending
- [ ] Wrong bullet type

Problem: Misformatted definition lists

❌ Term: Definition without proper spacing

✅ Term
: Proper definition with colon

Another term
: Another definition

Problem: Missing or broken footnotes

❌ Here's a text with a footnote[^1]
No footnote definition

✅ Here's a text with a footnote[^1]

[^1]: This is the footnote definition

Problem: Inconsistent emoji rendering

Best Practices:

• Test emoji rendering across platforms
• Consider using HTML entities for critical emojis
• Have fallback text for platform-specific emojis

Before exporting to Markdown2Image or publishing:

1. [ ] Check all headings have proper spacing
2. [ ] Verify list consistency and indentation
3. [ ] Confirm code blocks use correct syntax
4. [ ] Test table alignment and formatting
5. [ ] Validate all links and images
6. [ ] Check for escaped special characters
7. [ ] Remove unnecessary HTML
8. [ ] Verify proper blockquote nesting
9. [ ] Check horizontal rule formatting
10. [ ] Clean up whitespace and line endings
11. [ ] Test reference links
12. [ ] Verify task list formatting
13. [ ] Check definition lists
14. [ ] Validate footnotes
15. [ ] Test emoji rendering

• Markdown linting tools: markdownlint, remark-lint
• Preview editors: Typora, Mark Text, VS Code with Markdown preview
• Online validators: Markdown live preview websites
• Export testing: Test in your target platform first

After fixing these issues, preview your Markdown in a plain viewer before exporting to Markdown2Image. This ensures clean, predictable results across all platforms and maintains professional quality in your visual content.

Remember: Good Markdown isn't just about what works—it's about what's maintainable, readable, and consistent across different tools and platforms.