Markdown Format Guide for Anki Cards

This guide explains how to write Markdown files that will be converted into Anki flashcards. Follow these simple rules to create effective study cards from your notes.

📤 Upload Options

Single File Upload

Upload a single .md file through the upload interface. Perfect for quick conversions and smaller study materials.

Batch Upload

Upload a ZIP file containing multiple .md files to create organized card decks with sub-decks. The folder structure in your ZIP file will automatically become sub-decks in Anki.

📝 Basic Format Rules

1. Document Title (Optional)

Use a level-one heading (#) at the top of your file as the document title. This will become the deck name:

# Python Programming Basics

If you don't include a # Title, the deck name will use your filename or the deck_name parameter you specify.

2. Chapter Separation (Required)

Use level-two headings (##) to separate different cards. Each ## Chapter Title will generate a separate Anki card.

## First Topic

Content for the first card...

## Second Topic

Content for the second card...

⚠️ Important: You must use ## headings at the start of each heading line. This is the only way the system can identify separate cards.

3. Front/Back Separation (Optional)

Within each chapter, use the % symbol to separate the front (question) and back (answer) of the card:

## Variable Definition

This is the question part

%

This is the answer part

• Content before % → Card front (question)
• Content after % → Card back (answer)

If you don't include a % separator, all chapter content will be used as the front, and the back will be empty.

📋 Complete Examples

Example 1: Basic Format

# Python Programming Basics

## What is Python?

What is the Python programming language?

%

Python is a high-level programming language with features including:
- Simple and readable syntax
- Powerful standard library
- Wide range of applications (Web, data science, AI)

## Python Variables

How do you define Python variables?

%

Use `=` for assignment:
```python
name = "Python"
age = 30

Python Functions

How do you define a function?

%

Use the def keyword:

def greet(name):
    return f"Hello, {name}!"

**Result**: Creates 3 cards in a deck named "Python Programming Basics"

### Example 2: Format Without Separator

```markdown
# Math Formulas

## Definition of Derivative

A derivative is the instantaneous rate of change of a function at a point.

**Mathematical Definition**:
$$
f'(x) = \lim_{h \to 0} \frac{f(x+h) - f(x)}{h}
$$

**Physical Meaning**:
- Velocity is the derivative of displacement with respect to time
- Acceleration is the derivative of velocity with respect to time

Result: Creates 1 card with all content on the front, empty back

🖼️ Image Support

Single File Upload

Only external URL images are supported:

## World Map

Here's a world map:

![World Map](https://example.com/world-map.png)

The system will automatically download images and include them in your Anki cards.

Batch Upload (ZIP)

Two image options are available:

1. Local images (recommended):

   • Place image files inside your ZIP archive
   • Reference them using relative paths in your Markdown

   obsidian-vault.zip
   ├── Python/
   │   ├── basics.md
   │   └── images/
   │       └── diagram.png
   └── JavaScript/
       └── async.md

   ## Asynchronous Programming
   
   Here's a flow diagram:
   
   ![Flow diagram](./images/diagram.png)

2. External URL images:

   ![Image](https://example.com/image.png)

📦 Batch Upload (Sub-deck Feature)

Using the batch upload feature, you can create Anki decks with organized sub-decks.

ZIP File Structure

my-study-deck.zip
├── Python/
│   ├── basics.md
│   └── advanced.md
├── JavaScript/
│   └── async.md
└── images/
    └── diagram.png

Generated Deck Structure

My Study Deck (root deck)
├── Python (sub-deck)
│   ├── Cards from basics.md
│   └── Cards from advanced.md
└── JavaScript (sub-deck)
    └── Cards from async.md

Notes

1. Folder structure = sub-deck hierarchy: The folder structure in your ZIP automatically maps to Anki sub-decks
2. Shared images: All Markdown files can share images within the ZIP
3. Automatic single-level skip: If all files are in the same top-level folder, that level is automatically skipped

✨ Supported Markdown Syntax

The system supports full Markdown syntax, including:

• ✅ Text formatting: Bold **bold**, italic *italic*, strikethrough ~~strike~~
• ✅ Code: Inline code `code` and code blocks
• ✅ Lists: Ordered and unordered lists
• ✅ Tables: Standard Markdown tables
• ✅ Images: ![alt](url) or HTML <img> tags
• ✅ Links: [text](url)
• ✅ Math formulas: LaTeX math formulas (if the renderer supports it)

Code Block Example

## Python Functions

How do you define a function?

%

Use the `def` keyword:

```python
def greet(name):
    """Greeting function"""
    return f"Hello, {name}!"
```

List Example

## Python Features

What are Python's key features?

%

- **Simple**: Clean and readable code
- **Powerful**: Rich standard library
  - Built-in data structures
  - Network programming
  - Data processing
- **Versatile**: Web, data science, AI

Table Example

## Data Type Comparison

What are the differences between data types?

%

| Type | Mutable | Example |
|------|---------|---------|
| List | Mutable | `[1, 2, 3]` |
| Tuple | Immutable | `(1, 2, 3)` |
| Dict | Mutable | `{"key": "value"}` |

🏷️ Tags

Automatic Tags

• Chapter titles as tags: Each chapter title is automatically added as a tag (after sanitization)
• Sub-deck names as tags: In batch uploads, sub-deck names are also added as tags

Example

## Python Variable Definition

Generated tags: ["Python_Variable_Definition"] (special characters are replaced)

⚠️ Common Mistakes

❌ Mistake 1: Missing Level-Two Headings

# Wrong Example

What is Python?

%

Python is a programming language.

Problem: No ## heading, so the system can't identify this as a card

Correct:

# Python Basics

## What is Python?

What is Python?

%

Python is a programming language.

❌ Mistake 2: Incorrect Heading Format

##Title (missing space)

Correct:

## Title (note the space)

❌ Mistake 3: Using Local Images in Single File Upload

Wrong: Using ./images/pic.png in single file upload

Solution:

• Use external URL: ![img](https://example.com/pic.png)
• Or use batch upload and include images in your ZIP file

📚 Best Practices

1. Clear Chapter Titles

Use descriptive titles that make it easy to find and review cards:

## Python Variable Definition and Assignment
## JavaScript Asynchronous Programming with Promises
## Calculus Fundamentals in Mathematics

2. Smart Use of Separators

• Use % for simple question-answer pairs
• Skip % for complex content where everything goes on the front

3. Image Optimization

• Use appropriate image sizes (avoid files that are too large)
• Use clear images (PNG for diagrams, JPG for photos)
• For batch uploads, organize related images in the same folder

4. Code Formatting

Specify language types in code blocks for syntax highlighting:

```python
def hello():
    print("Hello")
```

```javascript
function hello() {
    console.log("Hello");
}
```

5. Organizational Structure

Organize folders by topic when using batch upload:

programming.zip
├── Python/
│   ├── basics.md
│   └── advanced.md
├── JavaScript/
│   └── async.md
└── DataStructures/
    └── tree.md

🔍 Quick Checklist

Before uploading, make sure:

• Each topic starts with ## Title
• There's a space between ## and the title text
• Image paths are correct (URLs for single files, relative paths for batch uploads)
• Code blocks use correct language identifiers
• ZIP files contain .md files (for batch uploads)
• Files are encoded in UTF-8

💡 Tips

• Chapter titles become card tags, making it easy to filter cards in Anki
• Batch uploads create hierarchical deck structures automatically
• Images are downloaded and packaged automatically—no manual work needed
• All standard Markdown syntax is supported

Need help? Check out the example files or contact support if you have questions.