docs(lark-doc): replace literal \n examples with real-newline forms

[fangshuyu-768]

Summary

Fixes #580 — the official docs +create / docs +update skill examples teach the pattern:

lark-cli docs +create --title "项目计划" --markdown "## 目标\n\n- 目标 1\n- 目标 2"

Inside bash double quotes, \n is a literal backslash + n (two characters), not a newline. lark-cli forwards the value byte-for-byte to MCP, so the resulting Feishu document ends up containing the literal text \n\n everywhere instead of paragraph breaks. Agents and users copy-pasting the examples reliably produce broken docs.

Verified locally

Reproduced against lark-cli v1.0.14-8-g9017741 on macOS, bash:

• --dry-run payload shows "content": "## A\\n\\n- x\\n- y" (literal backslash-n passed through to the API)
• Creating a real doc with the buggy pattern yields <title>Untitled</title><h2>A\n\n- x\n- y</h2> — the whole markdown structure collapses into a single H2 with visible \n\n text

Scope

Documentation-only fix, per the reporter's Option 1. CLI behavior is intentionally unchanged — byte-for-byte forwarding matches standard shell semantics, and auto-interpreting \n (Option 2) would be a breaking change.

Changes

Two skill files, 9 buggy example occurrences plus 1 single-quoted variant:

skills/lark-doc/references/lark-doc-create.md

• Fix 3 "...\n..." examples in the ## 命令 block (lines 15, 18 previously)
• Fix 1 "...\n..." example in ## 示例 1 (line 119 previously)
• Fix 1 '...\n...' single-quoted example in ## 示例 2 — same bug, different quote style
• Add a prominent warning callout in ## 重要说明 explaining the pitfall and listing three safe alternatives
• Add a new --markdown - <<'MD' heredoc example for longer content

skills/lark-doc/references/lark-doc-update.md

• Fix 6 "...\n..." examples across ## 命令 and # 使用示例 sections
• Add the same warning callout at the top
• Add a --markdown - heredoc example for longer content
• Leave the existing two $'...' ANSI-C examples untouched — those already produce real newlines and serve as a valid short-form option for inline whiteboard tags

Test plan

• grep -nE '--(markdown\|content) "[^"]*\\n' on both files returns no matches after the fix
• Remaining $'...\n...' occurrences are intentional (ANSI-C quoting actually produces real newlines)
• Reviewed rendered diff — no unintended changes

Related

• Issue docs +create / +update: skill examples with "...\n..." send literal \n to MCP, breaking Markdown rendering #580 — original report with detailed reproduction
• PR feat: markdown support line breaks #338 / issue im +messages-send --markdown: table syntax and blank lines are silently dropped #202 — earlier fix for a similar blank-line loss on im +messages-send; the doc creation path was not covered at the time

Summary by CodeRabbit

• Documentation
  • Added a warning that shell-quoted --markdown "...\n..." passes literal backslash + n, not line breaks.
  • Replaced escaped \n examples with actual multi-line quoted content across create/update/append/replace/overwrite docs.
  • Added a heredoc stdin example (--markdown -) for providing multi-line Markdown.
  • Noted ANSI‑C $'...\n...' quoting as an alternative for short sequences and updated extended callout examples to use real newlines.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Clarifies that "\n" inside shell-quoted --markdown "..." is passed as literal backslash-n to MCP; examples updated to use actual newlines (multi-line quotes), ANSI‑C $'...' where appropriate, or heredoc/stdin (--markdown -) and adds a heredoc stdin example.

Changes

Cohort / File(s)	Summary
Lark Doc Skill References skills/lark-doc/references/lark-doc-create.md, skills/lark-doc/references/lark-doc-update.md	Added a warning that "\n" in double-quoted --markdown "...\n..." is literal backslash+n. Rewrote command examples to embed real newlines (multi-line quoted strings), noted ANSI‑C $'...' usage for short cases, and added a heredoc/stdin example (--markdown - <<'MD' ... MD). Updated HTML/callout examples to use real newlines.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I nibbled at strings where \n would stay,
Swapped backslashes for real breaks in play,
Heredocs and newlines hop in tune,
Docs now breathe under the moon,
A tiny rabbit cheers — hooray! 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title clearly and specifically describes the main change: fixing documentation examples to use real newlines instead of literal \n escape sequences in bash quoted strings.
Linked Issues check	✅ Passed	All coding requirements from issue #580 are met: buggy examples with literal \n in double quotes replaced with real newlines or heredoc forms, warning callouts added to both files, and ANSI-C $'...' examples intentionally preserved.
Out of Scope Changes check	✅ Passed	All changes directly address issue #580 objectives: fixing documentation examples and adding clarifications without modifying CLI behavior or unrelated content.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The PR description comprehensively documents the problem, solution, verification steps, scope, specific file changes, test plan, and related issues.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/skill-markdown-newline-examples

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 59.94%. Comparing base (11191df) to head (d692694).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #602      +/-   ##
==========================================
+ Coverage   59.81%   59.94%   +0.12%     
==========================================
  Files         404      405       +1     
  Lines       42526    42673     +147     
==========================================
+ Hits        25439    25580     +141     
- Misses      15082    15084       +2     
- Partials     2005     2009       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@d69269430eb90b523dee9b26411db67d45d805ed

🧩 Skill update

npx skills add larksuite/cli#fix/skill-markdown-newline-examples -y -g

[SunPeiYang996]

good