home / skills / ratacat / claude-skills / beautiful-mermaid-ascii

beautiful-mermaid-ascii skill

safe

/skills/beautiful-mermaid-ascii

This skill renders Mermaid diagrams as readable ASCII art in the terminal from files, stdin, or Markdown fences.

npx playbooks add skill ratacat/claude-skills --skill beautiful-mermaid-ascii

Review the files below or copy the command above to add this skill to your agents.

Files (8)

SKILL.md

2.9 KB

---
name: beautiful-mermaid-ascii
description: Render Mermaid diagrams as readable ASCII/Unicode art in the terminal (from .mmd/.mermaid files, stdin, or Markdown ```mermaid fences). Use when installing or using lukilabs/beautiful-mermaid, creating a CLI renderer for Mermaid-to-ASCII output, previewing Mermaid diagrams in terminal, or extracting/rendering Mermaid blocks from Markdown files.
---

# Beautiful Mermaid ASCII Rendering

Use `lukilabs/beautiful-mermaid` (a JS library, not a CLI) to turn Mermaid diagrams into terminal-friendly ASCII/Unicode art.

## Quick start

Render a Mermaid file:

```bash
skills/beautiful-mermaid-ascii/scripts/mermaid-ascii path/to/diagram.mmd
```

Install a clean `mermaid-ascii` command on your PATH (symlink into `~/.local/bin` by default):

```bash
skills/beautiful-mermaid-ascii/scripts/install-mermaid-ascii
```

Render from stdin:

```bash
cat path/to/diagram.mmd | skills/beautiful-mermaid-ascii/scripts/mermaid-ascii
```

Render the first Mermaid fenced block from Markdown:

```bash
skills/beautiful-mermaid-ascii/scripts/mermaid-ascii --md README.md
```

Select a different fenced block (1-based):

```bash
skills/beautiful-mermaid-ascii/scripts/mermaid-ascii --md README.md --block 2
```

## Installation approach (how this skill “deals with installing”)

`scripts/mermaid-ascii` auto-installs `beautiful-mermaid` into a writable cache directory (defaults to `$XDG_CACHE_HOME/beautiful-mermaid-ascii`, or `/tmp/beautiful-mermaid-ascii`) when needed, then runs the renderer.

If you want a “real” command on your PATH, prefer the symlink installer:

```bash
skills/beautiful-mermaid-ascii/scripts/install-mermaid-ascii
```

You can also install this folder as a local/global npm package (use a writable npm cache if your `~/.npm` is not writable):

```bash
# from the repo root
NPM_CONFIG_CACHE=/tmp/npm-cache npm install -g --prefix ~/.local ./skills/beautiful-mermaid-ascii
```

If you already have `beautiful-mermaid` installed in the current project, run with:

```bash
skills/beautiful-mermaid-ascii/scripts/mermaid-ascii --pkg-dir . path/to/diagram.mmd
```

## Troubleshooting

- If installs fail due to permission errors in `~/.npm` or `~/Library/Caches`, run with a writable cache directory:
  - `skills/beautiful-mermaid-ascii/scripts/mermaid-ascii --cache-dir /tmp/bm-cache ...`
- If output is empty, verify the Mermaid text is valid and starts with a diagram type (`flowchart`, `sequenceDiagram`, etc.).
- For multiple diagrams in Markdown, use `--list` to enumerate fenced blocks and choose one with `--block`.

## Bundled resources

- `skills/beautiful-mermaid-ascii/scripts/mermaid-ascii`: Shell wrapper that ensures dependencies are available, then renders.
- `skills/beautiful-mermaid-ascii/scripts/mermaid-ascii.mjs`: Node CLI that extracts Mermaid (raw or from Markdown fences) and calls `renderMermaidAscii`.
- `skills/beautiful-mermaid-ascii/references/notes.md`: Small notes about Mermaid inputs and common patterns.

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

FAQ

Why is nothing printed?

Empty output usually means the input did not start with a supported diagram keyword. Confirm the Mermaid text begins with a diagram type like flowchart or sequenceDiagram.

How do I fix permission errors during install?

Re-run the command with --cache-dir pointing to a writable directory (for example /tmp/bm-cache) or use the symlink installer to avoid global npm writes.