feat: support Mermaid Add-On widget (block_type=40) to preserve editable mermaid source code
Nobody has claimed this yet.
- 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:
- The mermaid source code is preserved and remains editable in the document
- Users can switch between code view and chart view
- The source can be updated programmatically via
docs +updateorwhiteboard +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:
- Insert them into Lark documents via lark-cli
- Later update the mermaid source and push the changes back
- 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_idisblk_631fefbbae02400430b8f9f4 - The widget data is stored in the
recordfield ofblock_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
- Short-term: Add a
--preserve-mermaid-codeflag that keeps mermaid as a code block (block_type=14,language="mermaid") instead of converting to whiteboard — source is preserved even without widget support - Medium-term: Implement
block_type=40create/read/update for the Mermaid widget specifically - Long-term: Extend to other widget subtypes (HTML, timeline, etc.) as the
recordformat becomes documented
Environment
- lark-cli version: 1.0.67
- OS: macOS (Darwin arm64)
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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