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