Skip to content

docs(lark-doc): clarify formula rendering for XML document writes #2042

Description

@Alpha-Girl

Summary

Clarify the lark-doc Skill guidance for mathematical formulas so AI agents do not write Markdown/LaTeX delimiters as literal text when the document command is using the default XML format.

Problem

lark-cli docs +create and docs +update default to --doc-format xml. The XML reference currently lists <latex>E = mc^2</latex> in the inline-component table, but the format-dependent rule is easy to miss.

As a result, an agent may generate content such as:

<p>The result is $E = mc^2$.</p>
<p>$$\sum_{i=1}^{n} i$$</p>

In XML mode, $...$, $$...$$, \(...\), and \[...\] are ordinary text. They can therefore appear verbatim in the Feishu/Lark document instead of becoming native formula nodes.

The correct XML is:

<p>The result is <latex>E = mc^2</latex>.</p>
<p><latex>\sum_{i=1}^{n} i</latex></p>

Markdown writes are different: $...$ is valid only when the command explicitly uses --doc-format markdown.

Proposed Change

Update the existing lark-doc Skill rather than adding a duplicate Skill:

  1. Add a formula-routing rule to skills/lark-doc/SKILL.md.
  2. Add a dedicated formula section to references/lark-doc-xml.md covering:
    • conversion from $...$, $$...$$, \(...\), and \[...\] to <latex>...</latex>;
    • inline versus standalone-paragraph examples;
    • XML escaping for &, <, and > inside formulas;
    • avoiding <pre> / <code> for formulas;
    • relative @file input for content containing $ and backslashes.
  3. Add matching Markdown guidance to references/lark-doc-md.md.
  4. Recommend a post-write docs +fetch --doc-format xml --detail full check to verify that the content contains <latex> nodes rather than literal delimiters.

Acceptance Criteria

  • The Skill clearly distinguishes XML formula syntax from Markdown formula syntax.
  • Agents are explicitly told not to write Markdown/LaTeX delimiters verbatim in XML mode.
  • Examples cover inline and standalone formulas.
  • Shell-safe relative @file input is recommended for formula-heavy content.
  • The repository's Skill format check passes.

Validation

I prepared the documentation-only change locally and verified it with:

node scripts/skill-format-check/index.js
✅ Skill format check passed!

git diff --check
✅ no whitespace errors

I can open a PR with the prepared patch once a fork branch is available.

Metadata

Metadata

Assignees

No one assigned

    Labels

    domain/coreCLI framework and core librariesdomain/docDocs domain

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions