larksuite / larksuite/cli

feat: support Mermaid Add-On widget (block_type=40) to preserve editable mermaid source code

Open
#1,834 1 comment 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Go
Stars
17.3k
Forks
1.4k
Avg merge
2d 4h
Merged PRs (30d)
105

Description

Summary

When inserting mermaid diagrams into Lark documents via lark-cli, the current implementation converts mermaid source into a whiteboard block (block_type=43). This is a one-way conversion — the mermaid source code is parsed into editable nodes and the original source is lost. Users can no longer modify the diagram by editing mermaid code.

Lark documents natively support a "Text Drawing" widget (block_type=40, Add-On) that preserves the mermaid source code and supports three view modes: codeChart, chart, and code. This widget allows users to edit mermaid source directly in the document UI. lark-cli does not currently support creating, reading, or updating this block type.

Expected Behavior

lark-cli should support creating mermaid diagrams as Add-On widgets (block_type=40) so that:

  1. The mermaid source code is preserved and remains editable in the document
  2. Users can switch between code view and chart view
  3. The source can be updated programmatically via docs +update or whiteboard +update

Proposed XML Schema

Extend the existing <whiteboard> tag with a mode attribute, or introduce a new <widget> tag:

<!-- Option A: extend whiteboard -->
<whiteboard type="mermaid" mode="widget">
graph TD
    A[Start] --> B{Decision}
    B -- Yes --> C[Execute]
    B -- No --> D[End]
</whiteboard>

<!-- Option B: new widget tag -->
<widget type="mermaid" view="codeChart">
graph TD
    A[Start] --> B{Decision}
    B -- Yes --> C[Execute]
    B -- No --> D[End]
</widget>

Use Case

I maintain a set of architecture diagrams as .mmd files. I want to:

  1. Insert them into Lark documents via lark-cli
  2. Later update the mermaid source and push the changes back
  3. Have team members edit the mermaid source directly in the Lark doc UI

Currently, after insertion, the only way to update is to delete the whiteboard block and re-insert — losing any manual adjustments and breaking the edit-in-place workflow.

Implementation Notes

  • The Mermaid widget component_type_id is blk_631fefbbae02400430b8f9f4
  • The widget data is stored in the record field of block_type=40
  • Three view modes exist: codeChart (code + rendered side by side), chart (rendered only), code (source only)
  • Related closed issues: #911, #1209, #1263 — maintainers acknowledged the need and suggested opening focused issues per widget type

Suggested Rollout

  1. Short-term: Add a --preserve-mermaid-code flag that keeps mermaid as a code block (block_type=14, language="mermaid") instead of converting to whiteboard — source is preserved even without widget support
  2. Medium-term: Implement block_type=40 create/read/update for the Mermaid widget specifically
  3. Long-term: Extend to other widget subtypes (HTML, timeline, etc.) as the record format becomes documented

Environment

  • lark-cli version: 1.0.67
  • OS: macOS (Darwin arm64)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating lark-cli's existing Mermaid and whiteboard handling, then trace how document block creation, reading, and updating represent block_type=40 records. Compare that path with the existing block_type=43 and block_type=14 behavior; done means a focused XML interface can preserve Mermaid source and support the stated codeChart, chart, and code modes without losing edits.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.