Anki Workflow Verification

Date: 2 May 2026
Status: ✅ Verified and Working

Current Working Workflow

1. Card Creation (Manual)

• JSON files are manually created in: data/course/{course}/{unit}/{module}/{lesson}/anki/*.json
• Each JSON contains metadata + flashcards array
• Example: data/course/psychology-l2/01/01m/001/anki/01-counselling-skills.json

2. Card Generation (Automatic)

JSON File → apkg_generator.py → .apkg Package → Anki Desktop

Key Scripts:

• ✅ apkg_generator.py - Main generator (reads JSON, creates APKG)
• ✅ generate_unit_apkg.py - Creates unit-level APKG files
• ✅ rebuild_all_apkgs.py - Rebuilds all APKG files

NOT Used in Production:

• ❌ content_parser.py - Was created for markdown parsing (deprecated)
• ❌ json_generator.py - Was created to use content_parser (deprecated)

3. CSS Styling (Automatic)

How it Works:

1. JSON metadata includes "course": "Psychology"
2. Generator extracts course name: metadata.get("course")
3. Generator loads CSS: scripts/anki/styles/{course}.css
4. CSS is injected into ALL card models (basic, cloze, hints)

Example:

1# In apkg_generator.py
2course = metadata.get("course", None)  # "Psychology"
3basic_model = self._create_basic_model(course)  # Loads psychology.css

Available Compiled CSS:

• ✅ scripts/anki/styles/psychology.css (16 KB)
• ✅ scripts/anki/styles/devops.css (17 KB)

Compilation:

1npm run anki:styles:compile  # Compiles all SCSS → CSS
2npm run anki:styles:watch    # Watch mode for development

HTML Support in Cards

Current Behavior

• HTML is ALWAYS supported in all card fields (question, answer)
• The html_enabled flag in JSON is stored but NOT checked by the generator
• This is GOOD - means we can use HTML freely in all cards

Recommendation

• Set "html_enabled": true in JSON metadata for documentation purposes
• Use HTML formatting in card content for better presentation
• CSS classes from compiled stylesheets will be applied automatically

Example Card with HTML

1{
2  "id": "u1m1l01-006",
3  "question": "<b>Define:</b> What is <em>active listening</em>?",
4  "answer": "<p><strong>Active listening</strong> is a technique where:</p><ul><li>Fully concentrates</li><li>Demonstrates engagement</li><li>Responds appropriately</li></ul>",
5  "html_enabled": true,
6  "difficulty": 1
7}

SCSS Styling System

Architecture

scripts/anki/styles/
├── _variables.scss           # Global design tokens (colors, spacing)
├── _base-components.scss     # Universal components (all courses)
├── courses/
│   ├── psychology.scss       # Psychology-specific overrides
│   ├── devops.scss          # DevOps-specific overrides
│   └── {new-course}.scss    # Add new courses here
├── psychology.css           # Compiled output (16 KB)
└── devops.css               # Compiled output (17 KB)

CSS Components Available

From _base-components.scss:

• .skill-card - List of skills with left border
• .comparison-box - Side-by-side comparisons
• .definition-card - Highlighted definitions
• .emphasis-text - Emphasized text
• .code-block - Code formatting
• Status boxes: .success-box, .warning-box, .info-box

Course-specific overrides in courses/*.scss

Package.json Scripts

Styling Scripts:

1npm run anki:styles:compile            # Compile all SCSS to CSS
2npm run anki:styles:compile:psychology # Compile psychology only
3npm run anki:styles:compile:devops     # Compile devops only
4npm run anki:styles:watch              # Watch mode for development
5npm run anki:styles:list               # List compiled CSS files

Generation Scripts:

1npm run anki:rebuild         # Rebuild all APKG files
2npm run anki:rebuild:verbose # Verbose output
3npm run anki:rebuild:unit    # Rebuild specific unit

Testing Scripts:

1npm run test:anki:verbose    # Run tests with verbose output
2npm run test:anki:coverage   # Run with coverage report

What Changed (Previous Agent’s Work)

✅ Good Work (Keep)

1. SCSS Styling System - Modular, scalable architecture
2. Compiled CSS Files - psychology.css, devops.css
3. Package.json Scripts - All working and useful
4. CSS Injection - Automatic based on course name

❌ Wrong Direction (Deprecate)

1. Markdown Markers - Created <!-- ANKI:card:cs-001 --> system (not needed)
2. content_parser.py - Parses markdown markers (not used in production)
3. json_generator.py - Uses content_parser (not used in production)
4. Documentation Rewrite - Rewrote docs to reflect marker system (incorrect)

📝 Documentation Status

• .prompts/anki/ - Contains ORIGINAL correct documentation (JSON-based)
• content/docs/anki/ - Contains REWRITTEN documentation (marker-based, incorrect)
• Action Needed: Consolidate original docs → content/docs/anki/ with draft: true

Next Steps

1. ✅ Verification Complete - Workflow confirmed working
2. ⏭️ Add deprecation notices to content_parser.py and json_generator.py
3. ⏭️ Consolidate documentation from .prompts/anki/ → content/docs/anki/
4. ⏭️ Update anki-test page for styling verification
5. ⏭️ Document styling system as standard practice
6. ⏭️ Test complete workflow end-to-end

Key Takeaways

✅ JSON files are manually created - No markdown parsing
✅ CSS is automatically injected - Based on course name in metadata
✅ HTML is always supported - Use freely in all cards
✅ SCSS system is production-ready - Just compile and use
✅ Package scripts all work - No changes needed

❌ Marker system is not needed - content_parser.py not used
❌ Current docs are incorrect - Need to restore original workflow docs