hermione-fe/MARKDOWN_VIEWER_MIGRATION.md

# MarkdownViewer Component - Migration Guide

## Overview
The new `MarkdownViewer` component replaces `MdPreview` from `md-editor-v3` with a more powerful markdown rendering solution based on `markdown-it`.

## Features
✅ **Mermaid Diagrams** - Full support for rendering Mermaid diagrams  
✅ **Enhanced Tables** - Tables with copy and CSV export functionality  
✅ **Syntax Highlighting** - Code blocks with automatic syntax highlighting  
✅ **GitHub-style Markdown** - Familiar GitHub-flavored markdown rendering  
✅ **Extensible** - Built on markdown-it with plugin support

## Installation
The required dependencies have been installed:
- `markdown-it` - Core markdown parser
- `markdown-it-highlightjs` - Code syntax highlighting
- `markdown-it-attrs` - Extended attribute support
- `mermaid` - Mermaid diagram rendering engine

**Note:** We handle Mermaid rendering directly without `markdown-it-mermaid` to avoid SSR/browser compatibility issues.

## Usage

### Before (MdPreview)
```vue
<template>
    <MdPreview class="editor" v-model="content" language="en-US" />
</template>

<script>
import { MdPreview } from 'md-editor-v3';
import 'md-editor-v3/lib/style.css';

export default {
    components: {
        MdPreview
    }
};
</script>
```

### After (MarkdownViewer)
```vue
<template>
    <MarkdownViewer class="editor" v-model="content" />
</template>

<script>
import MarkdownViewer from '@/components/MarkdownViewer.vue';

export default {
    components: {
        MarkdownViewer
    }
};
</script>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `modelValue` | String | `''` | The markdown content to render |
| `theme` | String | `'light'` | Theme for the component ('light' or 'dark') |
| `previewTheme` | String | `'github'` | Preview theme style |

## Examples

### Basic Markdown
```vue
<MarkdownViewer v-model="markdownContent" />
```

### With Theme
```vue
<MarkdownViewer 
    v-model="markdownContent" 
    theme="dark"
    previewTheme="github"
/>
```

### Sample Content with Features

#### Mermaid Diagram
```markdown
# System Architecture

\`\`\`mermaid
graph TD
    A[Client] --> B[Load Balancer]
    B --> C[Server 1]
    B --> D[Server 2]
    C --> E[Database]
    D --> E
\`\`\`
```

#### Tables with Copy/Export
```markdown
| Feature | MdPreview | MarkdownViewer |
|---------|-----------|----------------|
| Mermaid | ❌ | ✅ |
| Table Copy | ❌ | ✅ |
| CSV Export | ❌ | ✅ |
| Extensible | Limited | ✅ |
```

When rendered, tables will have "Copy Table" and "Export CSV" buttons automatically.

#### Code Blocks
```markdown
\`\`\`javascript
function greet(name) {
    console.log(\`Hello, \${name}!\`);
}
\`\`\`
```

## Migration Steps

### 1. Update Individual Components
For each component using `MdPreview`:

1. Remove the import:
```javascript
import { MdPreview } from 'md-editor-v3';
import 'md-editor-v3/lib/style.css';
```

2. Add the new import:
```javascript
import MarkdownViewer from '@/components/MarkdownViewer.vue';
```

3. Update the component registration:
```javascript
// Before
components: {
    MdPreview
}

// After
components: {
    MarkdownViewer
}
```

4. Replace the component in template:
```vue
<!-- Before -->
<MdPreview class="editor" v-model="content" language="en-US" />

<!-- After -->
<MarkdownViewer class="editor" v-model="content" />
```

### 2. Affected Files
Based on the codebase scan, the following files need to be updated:

- ✅ `/src/components/ChatClient.vue`
- ✅ `/src/components/ChangeImpactOutputViewer.vue`
- ✅ `/src/components/CiaMultipleImpactView.vue`
- ✅ `/src/components/CiaSingleImpactView.vue`
- ✅ `/src/components/OldExecutionResponsePanel.vue`
- ✅ `/src/components/SingleClassViewer.vue`
- ✅ `/src/components/WorkflowResponsePanel.vue`
- ✅ `/src/views/pages/OldScenarioExec.vue.backup`
- ✅ `/src/views/pages/ScenarioExec.vue`

### 3. Remove Old Dependency (Optional)
After migration is complete, you can optionally remove the old package:
```bash
npm uninstall md-editor-v3
```

## Customization

### Adding More Plugins
You can extend the component by adding more markdown-it plugins. Edit `MarkdownViewer.vue`:

```javascript
import markdownItFootnote from 'markdown-it-footnote';

const md = new MarkdownIt({...})
    .use(markdownItHighlightjs)
    .use(markdownItAttrs)
    .use(markdownItMermaid)
    .use(markdownItFootnote); // Add new plugin
```

### Styling
Customize the appearance by modifying the scoped styles in `MarkdownViewer.vue`.

## Troubleshooting

### Mermaid Diagrams Not Rendering
- Check browser console for errors
- Verify the mermaid syntax is correct
- Ensure the code block uses the `mermaid` language identifier

### Tables Not Showing Copy Buttons
- Ensure the table is properly formatted in markdown
- Check that JavaScript is enabled
- Verify no CSP restrictions on inline scripts

### Syntax Highlighting Not Working
- Verify highlight.js supports the language
- Check that the language identifier in code blocks is correct
- Ensure highlight.js CSS is loaded

## Support
For issues or questions, refer to the documentation:
- [markdown-it](https://github.com/markdown-it/markdown-it)
- [Mermaid](https://mermaid-js.github.io/mermaid/)
- [highlight.js](https://highlightjs.org/)