beautiful-mermaid-ascii_skill

Overview

This skill renders Mermaid diagrams as readable ASCII/Unicode art for the terminal. It accepts .mmd/.mermaid files, stdin, or Mermaid fenced blocks extracted from Markdown. The tool auto-installs the JavaScript renderer into a cache and provides a small CLI wrapper for convenient previewing and scripting.

How this skill works

A shell wrapper ensures the lukilabs/beautiful-mermaid library is available in a writable cache, then invokes a Node CLI that parses input (raw Mermaid text or fenced blocks from Markdown) and calls the renderer to produce terminal-friendly ASCII/Unicode output. The wrapper can read files, stdin, enumerate Markdown fences, and let you select a specific block to render. An installer script can symlink a mermaid-ascii command into ~/.local/bin for easy use.

When to use it

• You need a quick terminal preview of a Mermaid diagram without opening a browser or GUI.
• You want to embed Mermaid previews in CLI workflows, README checks, or CI logs.
• You need to extract and render the first or a specific Mermaid fence from a Markdown file.
• You prefer a standalone small CLI that auto-manages its Node dependency in a cache.
• You want to convert many local .mmd/.mermaid files to text output for documentation or diffs.

Best practices

• Install the symlinked command with the provided installer for a persistent mermaid-ascii on PATH.
• Use a writable cache directory (XDG_CACHE_HOME or /tmp) if npm or user caches are not writable.
• Validate Mermaid input starts with a diagram type (flowchart, sequenceDiagram, etc.) to avoid empty output.
• Use --list to inspect multiple fenced blocks in Markdown, then pass --block N to render a specific one.
• When embedding in scripts, prefer --pkg-dir . to reuse an existing beautiful-mermaid installation in the project.

Example use cases

• Preview a diagram before committing: skills/.../scripts/mermaid-ascii path/to/diagram.mmd
• Render the first Mermaid block from README.md for a quick terminal snapshot: mermaid-ascii --md README.md
• Pipe Mermaid text from another command: cat diagram.mmd | mermaid-ascii
• Install a user-level command: run the install script to symlink mermaid-ascii into ~/.local/bin
• Render the second fenced Mermaid block in a document: mermaid-ascii --md docs.md --block 2