hermione-fe/MARKDOWN_VIEWER_REFERENCE.md

# MarkdownViewer - Quick Reference

## Component Props

```vue
<MarkdownViewer 
    v-model="markdownContent"
    theme="light"
    previewTheme="github"
/>
```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `modelValue` | String | `''` | Markdown content to render |
| `theme` | String | `'light'` | Component theme (`'light'` or `'dark'`) |
| `previewTheme` | String | `'github'` | Preview style theme |

## Table Features

### Copy to Clipboard
Click the **"Copy Table"** button above any table to copy its contents as tab-separated values.

### Export to CSV
Click the **"Export CSV"** button to download the table as a CSV file.

## Mermaid Diagram Examples

### Flowchart
```mermaid
graph LR
    A[Start] --> B[Process]
    B --> C{Decision}
    C -->|Yes| D[End]
    C -->|No| B
```

### Sequence Diagram
```mermaid
sequenceDiagram
    Alice->>Bob: Hello Bob!
    Bob-->>Alice: Hi Alice!
```

### Pie Chart
```mermaid
pie title Programming Languages
    "JavaScript" : 35
    "Python" : 30
    "Java" : 20
    "Other" : 15
```

### State Diagram
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: Start
    Processing --> Success: Complete
    Processing --> Error: Fail
    Success --> [*]
    Error --> Idle: Retry
```

## Supported Code Languages

The component supports syntax highlighting for 100+ languages including:

- JavaScript/TypeScript
- Python
- Java
- C/C++/C#
- Ruby
- Go
- Rust
- PHP
- SQL
- HTML/CSS
- XML
- JSON
- YAML
- Markdown
- Bash/Shell
- And many more...

## Advanced Markdown Features

### Attributes
You can add attributes to elements using the `markdown-it-attrs` plugin:

```markdown
# Heading {#custom-id}
Paragraph with custom class {.custom-class}
```

### Extended Tables
Tables support alignment:

```markdown
| Left Aligned | Center Aligned | Right Aligned |
|:-------------|:--------------:|--------------:|
| Left         | Center         | Right         |
```

## API - Programmatic Usage

While the component is primarily used declaratively, you can access internal methods if needed:

```vue
<script setup>
import { ref } from 'vue';
import MarkdownViewer from '@/components/MarkdownViewer.vue';

const markdownRef = ref(null);
const content = ref('# Hello World');

// The component handles rendering automatically
// No manual render calls needed
</script>

<template>
    <MarkdownViewer ref="markdownRef" v-model="content" />
</template>
```

## Browser Compatibility

- Chrome/Edge: ✅ Full support
- Firefox: ✅ Full support
- Safari: ✅ Full support
- Opera: ✅ Full support

## Performance Tips

1. **Large Documents**: The component handles large documents efficiently, but consider pagination for very large content
2. **Multiple Instances**: Each instance is independent and can render different content
3. **Dynamic Updates**: Content updates are reactive and re-render automatically
4. **Mermaid Caching**: Diagrams are cached after first render

## Common Patterns

### Dynamic Content Loading
```vue
<script setup>
import { ref, onMounted } from 'vue';
import MarkdownViewer from '@/components/MarkdownViewer.vue';

const content = ref('Loading...');

onMounted(async () => {
    const response = await fetch('/api/markdown/document');
    content.value = await response.text();
});
</script>

<template>
    <MarkdownViewer v-model="content" />
</template>
```

### Conditional Rendering
```vue
<template>
    <div>
        <button @click="showMarkdown = !showMarkdown">
            Toggle Markdown
        </button>
        
        <MarkdownViewer 
            v-if="showMarkdown"
            v-model="content"
        />
    </div>
</template>
```

### With Loading State
```vue
<script setup>
import { ref } from 'vue';
import MarkdownViewer from '@/components/MarkdownViewer.vue';

const loading = ref(true);
const content = ref('');

async function loadContent() {
    loading.value = true;
    // Fetch content...
    content.value = await fetchMarkdown();
    loading.value = false;
}
</script>

<template>
    <div>
        <div v-if="loading">Loading...</div>
        <MarkdownViewer v-else v-model="content" />
    </div>
</template>
```

## Troubleshooting

### Issue: Mermaid diagrams show as text
**Solution**: Ensure the code block uses `mermaid` as the language identifier:
````markdown
```mermaid
graph TD
    A-->B
```
````

### Issue: Table buttons not appearing
**Solution**: Verify the table syntax is correct and has headers:
```markdown
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
```

### Issue: Code not highlighted
**Solution**: Check that the language identifier is correct and supported by highlight.js

### Issue: Content not updating
**Solution**: Ensure you're using `v-model` or watching the `modelValue` prop correctly

## Security

The component uses `v-html` to render markdown. Only use with trusted content or sanitize user input before passing to the component.

For user-generated content, consider adding a sanitization layer:
```javascript
import DOMPurify from 'dompurify';

const sanitizedContent = DOMPurify.sanitize(userContent);
```

## Further Reading

- [Markdown Guide](https://www.markdownguide.org/)
- [Mermaid Documentation](https://mermaid-js.github.io/)
- [markdown-it Documentation](https://github.com/markdown-it/markdown-it)
- [highlight.js Languages](https://github.com/highlightjs/highlight.js/blob/main/SUPPORTED_LANGUAGES.md)