feat: add PreviewableCode component with Mermaid and PlantUML support

[xianminx]

Overview

This PR introduces a new PreviewableCode component that enhances code block rendering in MDX by providing an interactive tabbed interface for previewable content. It supports rendering of Mermaid diagrams and PlantUML diagrams directly in the browser.

Key Features

• Interactive tabbed interface to switch between code and preview views
• Built-in support for Mermaid diagrams with client-side rendering
• Built-in support for PlantUML diagrams with server-side rendering
• Graceful fallback to standard code display for non-previewable blocks
• Error handling and display for diagram rendering failures
• Responsive design with dark mode support

Technical Details

• Added new components:
  • PreviewableCode.tsx: Main component for handling previewable code blocks
  • Mermaid.tsx: Client-side Mermaid diagram renderer
  • PlantUML.tsx: Server-side PlantUML diagram renderer
• Updated MDXComponents.tsx to use the new PreviewableCode component
• Added new dependencies:
  • mermaid: For client-side diagram rendering
  • plantuml-encoder: For PlantUML diagram encoding
  • @types/plantuml-encoder: TypeScript type definitions

Usage Examples

The component can be used in MDX files with the following syntax:

```mermaid
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
```

```plantuml
@startuml
abstract        abstract
abstract class  "abstract class"
annotation      annotation
circle          circle
()              circle_short_form
class           class
@enduml
```

Testing

• Added a new blog post previewable_code.mdx with examples and documentation
• Tested both Mermaid and PlantUML diagram rendering
• Verified dark mode compatibility
• Checked responsive design on various screen sizes

Notes

• PlantUML diagrams are rendered using the public PlantUML server
• Mermaid diagrams are rendered client-side using mermaid.js

[vercel]

@xianminx is attempting to deploy a commit to the timlrx's projects Team on Vercel.

A member of the Team first needs to authorize it.

[xianminx]

@timlrx
Hi, I've drafted a solution for previewing and rendering both Mermaid and PlantUML diagrams. I'm open to discussing other possible approaches.

For client-side Mermaid rendering, I understand it can be heavy. However, if we render Mermaid diagrams at build time, the mermaid.js library requires a browser environment for layout. Running it in Node.js would necessitate heavier tools like Puppeteer or Playwright. In comparison, client-side rendering seems like the more efficient option.

For PlantUML rendering, due to its heavy dependency on Java, the simplest approach is to leverage the official online service for previewing diagrams.

Looking forward to your thoughts!

Link issue #394 and PR #971
cc @rtkelly13 @aloisdg @abernier

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
tailwind-nextjs-starter-blog	❌ Failed (Inspect)			Mar 31, 2025 7:24am

[timlrx]

There's a bunch of warning and errors:

Failed to compile.
./components/MDXComponents.tsx
25:2  Error: Insert `⏎`  prettier/prettier
./components/Mermaid.tsx
63:25  Error: Replace `whitespace-pre-wrap·break-words·font-mono·text-sm·font-medium` with `font-mono·text-sm·font-medium·break-words·whitespace-pre-wrap`  prettier/prettier
./components/PlantUML.tsx
24:6  Warning: React Hook useEffect has a missing dependency: 'dpi'. Either include it or remove the dependency array.  react-hooks/exhaustive-deps
31:9  Error: Delete `·`  prettier/prettier
36:7  Warning: Using `<img>` could result in slower LCP and higher bandwidth. Consider using `<Image />` from `next/image` or a custom image loader to automatically optimize images. This may incur additional usage or cost from your provider. See: https://nextjs.org/docs/messages/no-img-element  @next/next/no-img-element
47:24  Error: Replace `opacity-100·translate-y-0'·:·'opacity-0·translate-y-2` with `translate-y-0·opacity-100'·:·'translate-y-2·opacity-0`  prettier/prettier
./components/PreviewableCode.tsx
32:18  Error: Unexpected any. Specify a different type.  @typescript-eslint/no-explicit-any
40:45  Error: Unexpected any. Specify a different type.  @typescript-eslint/no-explicit-any
info  - Need to disable some ESLint rules? Learn more here: https://nextjs.org/docs/app/api-reference/config/eslint#disabling-rules
Error: Command "yarn run build" exited with 1

You could try building locally to ensure that there are no issues before pushing

[timlrx]

@timlrx Hi, I've drafted a solution for previewing and rendering both Mermaid and PlantUML diagrams. I'm open to discussing other possible approaches.

For client-side Mermaid rendering, I understand it can be heavy. However, if we render Mermaid diagrams at build time, the mermaid.js library requires a browser environment for layout. Running it in Node.js would necessitate heavier tools like Puppeteer or Playwright. In comparison, client-side rendering seems like the more efficient option.

For PlantUML rendering, due to its heavy dependency on Java, the simplest approach is to leverage the official online service for previewing diagrams.

Looking forward to your thoughts!

Link issue #394 and PR #971 cc @rtkelly13 @aloisdg @abernier

Hi @xianminx, thanks for the PR and nice to see that you managed to integrate both mermaid and plantUML diagrams to the template!

Since, I believe most users of the blog will probably not use such diagrammatic features, my preference would be to exclude them and have users extend to include additional features as required. Having said that, the examples of the integration would be very useful though and we could link the preview build as an example for users who want to implement something similar - they can then copy the code from your branch.

[xianminx]

Fair enough. I also believe it's best to keep the product focused and simple. I'm still happy to experiment and contribute.

@timlrx