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)

<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)

<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

<MarkdownViewer v-model="markdownContent" />

With Theme

<MarkdownViewer 
    v-model="markdownContent" 
    theme="dark"
    previewTheme="github"
/>

Sample Content with Features

Mermaid Diagram

# 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

| Feature | MdPreview | MarkdownViewer |
|---------|-----------|----------------|
| Mermaid | ❌ | ✅ |
| Table Copy | ❌ | ✅ |
| CSV Export | ❌ | ✅ |
| Extensible | Limited | ✅ |

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

Code Blocks

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

Migration Steps

1. Update Individual Components

For each component using MdPreview:

1. Remove the import:

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

2. Add the new import:

import MarkdownViewer from '@/components/MarkdownViewer.vue';

3. Update the component registration:

// Before
components: {
    MdPreview
}

// After
components: {
    MarkdownViewer
}

4. Replace the component in template:

<!-- 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:

npm uninstall md-editor-v3

Customization

Adding More Plugins

You can extend the component by adding more markdown-it plugins. Edit MarkdownViewer.vue:

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
• Mermaid
• highlight.js