docs(lark-doc): clarify when markdown escaping is needed

[OwenYWT]

Summary

Clarify that Lark Markdown escaping is only needed when characters would otherwise trigger Markdown / rich-text formatting.

Changes

• explain in the general rules section that isolated special characters in plain text should usually be left unescaped
• add concrete examples showing when escaping is unnecessary (5 * 3, version~1.0, final_trajectory)
• clarify in best practices that escaping is only needed when the intent is to render formatting markers literally

Related Issues

• closes docs(lark-doc): escape rules lack trigger context, causing agents to over-escape #155

Summary by CodeRabbit

• Documentation
  • Clarified Lark-flavored Markdown escaping: only require backslash escaping when characters would trigger formatting, reducing unnecessary escapes in ordinary text (e.g., 5 * 3, version~1.0, final_trajectory remain unescaped). Added examples showing when to escape formatting-triggering patterns (e.g., 斜体, 粗体, 删除线) and updated best-practice guidance accordingly.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1aa0a0cb-c2ad-494f-a5a4-35e6eb945e7f

📥 Commits

Reviewing files that changed from the base of the PR and between 9cbf8d7 and 5881729.

📒 Files selected for processing (1)

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

✅ Files skipped from review due to trivial changes (1)

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

---

📝 Walkthrough

Walkthrough

Documentation for Lark-flavored Markdown escape rules was narrowed: backslash escaping is required only when characters would be parsed as Markdown/Lark rich-text formatting, not for ordinary standalone characters.

Changes

Cohort / File(s)	Summary
Lark Markdown Escape Documentation skills/lark-doc/references/lark-doc-create.md	Refined guidance: state that \ escaping is only necessary when characters would activate formatting (e.g., *text*, **bold**, ~~strike~~); show examples where ordinary characters remain unescaped (e.g., 5 * 3, version~1.0, final_trajectory) and update best-practice bullets accordingly.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

Poem

🐰 I hopped through docs to tidy the track,
No need to hide a star in "5 * 3" back-to-back.
Escape when *bold* would take the stage,
Let lone _ and ~ live free on the page.
Hooray — clearer hops, no needless backslash wag! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: clarifying when markdown escaping is needed in Lark documentation.
Description check	✅ Passed	The description includes all required template sections: Summary, Changes, and Related Issues. Test Plan section is missing but is non-critical.
Linked Issues check	✅ Passed	The PR fully addresses issue #155 by explaining when escaping is needed, providing concrete examples of unnecessary escaping, and clarifying the formatting-trigger context.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to clarifying escaping rules in the Lark Markdown documentation and are aligned with the linked issue objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[greptile-apps]

Greptile Summary

This PR clarifies the Lark-flavored Markdown escaping guidance in lark-doc-create.md, narrowing the advice from "escape all special characters" to "only escape characters that would actually trigger formatting." It adds concrete examples (5 * 3, version~1.0, final_trajectory) to illustrate cases where escaping is unnecessary.

As a bonus, the change also silently fixes a malformed inline code span in the original rule: the old single-backtick delimiters `* ~ ` $ [ ] < > { } | ^` would have terminated early at the embedded backtick, while the new double-backtick delimiters ``* ~ ` $ [ ] < > { } | ^`` render correctly.

Confidence Score: 5/5

Documentation-only change; safe to merge.

All changes are documentation improvements with no logic, schema, or runtime code affected. The guidance is accurate, the examples are correct, and the PR also incidentally fixes a malformed code span. No P0/P1 findings.

No files require special attention.

Vulnerabilities

No security concerns identified.

Important Files Changed

Filename	Overview
skills/lark-doc/references/lark-doc-create.md	Two documentation improvements: tightened escaping rule to require escaping only when characters trigger formatting, added clarifying examples, and fixed a malformed single-backtick code span to use double backticks.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Character in content] --> B{Would it trigger\nMarkdown/Lark formatting?}
    B -- Yes --> C[Escape with backslash\ne.g. \\*italic\\*]
    B -- No --> D[Leave unescaped\ne.g. 5 * 3, version~1.0]
    C --> E[Renders as literal character]
    D --> F[Renders as plain text]

Loading

_{Reviews (2): Last reviewed commit: "docs(lark-doc): fix escaped special char..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@skills/lark-doc/references/lark-doc-create.md`:
- Line 123: The inline code span containing the special-character list is
malformed (triggers MD038); replace the single-backtick delimited span around
the sequence `* ~ ` $ [ ] < > { } | ^` with a double-backtick inline code span
so the embedded backtick is preserved (e.g. use `` `* ~ ` $ [ ] < > { } | ^` ``)
ensuring the entire character list renders correctly and the MD038 warning is
resolved.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5cfa917c-121c-474d-9cfd-5f6b025f6d49

📥 Commits

Reviewing files that changed from the base of the PR and between fe8da8d and 9cbf8d7.

📒 Files selected for processing (1)

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

[fangshuyu-768]

Thanks for the update and the careful clarification here. This makes the escaping rules much easier to understand, especially the distinction between characters that are merely present and characters that actually trigger formatting. Also appreciate the follow-up fix for the backtick example.