1 line
4.5 KiB
Markdown
1 line
4.5 KiB
Markdown
|
# Markdown Image Syntax Fix - Final Resolution\n\n## Problem\n\nVite/Slidev continued to fail with "Failed to resolve import" errors even with `?url` query parameter because:\n\n- Slidev converts HTML to Vue components\n- Vue/Vite processes all paths as potential module imports\n- HTML `<img>` tags go through JavaScript processing pipeline\n- Query parameters didn't prevent Vue from attempting the import\n\n```plaintext\nPlugin: vite:import-analysis\nFailed to resolve import "/images/provisioning-logo.svg"\n```\n\n## Root Cause\n\nThe issue was architectural:\n\n1. Markdown HTML (`<img src="...">`) → Vue template compilation\n2. Vue treats all `src` attributes as potential modules\n3. Vite import analyzer processes before image resolution\n4. Static asset path resolution happens after module processing\n\n## Solution: Markdown Image Syntax\n\nChanged from HTML `<img>` tags to markdown image syntax: ``\n\n**Why this works:**\n\n1. Markdown images are processed by the markdown parser\n2. Markdown parser handles them BEFORE Vue compilation\n3. Static assets are resolved in the markdown→HTML phase\n4. No Vue/Vite module import processing occurs\n\n### Before (HTML - Failed)\n\n```html\n<img src="/images/provisioning-logo.svg" class="w-32 mx-auto mt-8" />\n<img src="/images/provisioning-logo.svg?url" class="w-32 mx-auto mt-8" />\n```\n\n### After (Markdown - Works!)\n\n```markdown\n\n```\n\n## Implementation Details\n\n### Markdown Syntax\n\n```markdown\n\n```\n\n- `alt text` - Accessibility text, displayed if image fails to load\n- `image path` - Supports absolute paths to `public/` assets\n- No CSS styling needed (centering handled by Slidev defaults)\n\n### All Files Updated (8 instances)\n\n**Presentation Files:**\n\n- ✅ versions/pitch.md (1 instance)\n- ✅ versions/demo-intro.md (1 instance)\n- ✅ versions/talk.md (1 instance)\n- ✅ versions/full.md (1 instance)\n- ✅ versions/workshop.md (2 instances)\n\n**Section Files:**\n\n- ✅ versions/sections/01-intro.md (1 instance)\n- ✅ versions/sections/07-conclusion.md (1 instance)\n\n## Key Insights\n\n### Why Markdown Syntax is Better for Slidev\n\n1. **Proper Processing Order**: Markdown → HTML happens before Vue compilation\n2. **Clarity**: Markdown syntax explicitly marks content as static markdown\n3. **Reliability**: Markdown image processing is stable and well-tested\n4. **Consistency**: Aligns with how Slidev documentation recommends handling images\n5. **Simplicity**: No complex query parameters or workarounds needed\n\n### Slidev Best Practices\n\nFor static assets in `public/` folder:\n\n- ✅ Use markdown image syntax: ``\n- ✅ Use absolute paths: `/images/logo.svg`\n- ❌ Don't use HTML `<img>` tags\n- ❌ Don't use Vue imports for static assets\n- ❌ Don't rely on query parameters like `?url`\n\n## Verification\n\nAll 8 instances converted:\n\n```bash\n$ grep -r '!\[Provisioning' versions/\n✅ 8 matches found across 7 files\n```\n\nNo HTML img tags remain:\n\n```bash\n$ grep -r '<img' versions/\n✅ No results (all removed)\n```\n\n## Testing Instructions\n\nRun presentations to verify images load correctly:\n\n```bash\ncd /Users/Akasha/project-provisioning/pres-prvng\nnu run-ultra-simple.nu\n```\n\nSelect any presentation and verify:\n\n1. ✅ No build errors in terminal\n2. ✅ No "import-analysis" plugin errors\n3. ✅ Logo image displays on first and last slides\n4. ✅ Images render with proper styling\n5. ✅ All slides load without errors\n\n## Technical Details\n\n### Processing Pipeline (Now Working)\n\n```plaintext\nMarkdown Input\n ↓\nMarkdown Parser (handles  syntax)\n ↓\nHTML Output (<img src="..." alt="..." />)\n ↓\nVue Component (receives static src attribute)\n ↓\nBrowser (renders image from public/images/)\n```\n\n### Markdown Conversion\n\nSlidev's markdown parser automatically converts:\n\n```markdown\n\n```\n\nTo HTML (with styling
|