`docs +update` strips the native Feishu `<sub-page-list>` block as if it were an unsupported HTML tag

[Maples7]

docs +update strips the native Feishu <sub-page-list> tag as if it were an unsupported HTML tag

Summary

The Feishu wiki ecosystem ships a built-in block called sub-page-list. Hub pages in any wiki space typically use it as their entire body — e.g. the 更新日志 hub in our space contains only:

<sub-page-list wiki-token="WODuwHoXSiWhNkkiR5Lc2UBfnOh"/>

…and the wiki UI renders the page's children as a grid of cards. lark-cli docs +fetch correctly returns that exact markdown when reading such a hub.

However, lark-cli docs +update rejects the same tag on write — it strips the element and only keeps the text content, emitting:

[WARNING:UNSUPPORTED_HTML_TAG] unsupported HTML tag removed: sub-page-list
💡 Suggestion: This HTML tag is not supported. The tag has been removed and only the text content is kept. Please check the documentation for supported tags

So the round-trip fetch → update for a hub page is lossy by default: the CLI can read the native block but cannot write it back, even though it's a first-class block in the Feishu wiki product.

Repro

# Create a fresh hub
lark-cli wiki +node-create \
  --space-id <space> \
  --parent-node-token <root> \
  --title "Hub" --obj-type docx
# → returns node_token=<NEW>

# Try to write the canonical sub-page-list body
printf '<sub-page-list wiki-token="<NEW>"/>\n' | \
  lark-cli docs +update \
    --doc "https://my.feishu.cn/wiki/<NEW>" \
    --mode overwrite \
    --markdown -

Returns success but with warnings: [".../UNSUPPORTED_HTML_TAG"] and the body is empty after the call.

Meanwhile:

lark-cli docs +fetch --doc "https://my.feishu.cn/wiki/<existing-hub>" --format markdown

…happily returns "markdown": "<sub-page-list wiki-token=\"...\"/>\n" for hubs that already have the block (created via the Feishu web UI).

Impact

Any agent or script attempting to reproducibly recreate a wiki hub layout through lark-cli cannot write the standard hub body. Workarounds:

• Author the hub body manually in the Feishu web UI (defeats automation).
• Write a plain-markdown landing page instead, accepting that children only show in the side-nav tree, not as inline cards.

Proposal

Add sub-page-list (and likely a small whitelist of other native Feishu block tags such as lark-table, image, sheet, mention-doc which already round-trip correctly on the fetch side) to the allowed tag list in the docs +update markdown processor.

If a full block-level write is non-trivial, at minimum the warning message should mention that this is a known Feishu-native block the markdown writer doesn't yet support, and point at the OpenAPI block-create endpoint as the workaround — rather than reading as "this is an arbitrary unsupported HTML tag".

Environment

• lark-cli 1.0.27
• macOS, Node.js, user mode
• Hit while restructuring a wiki space into bilingual hubs.

Related

• #809, #810, #811 — other wiki-tooling friction encountered in the same workflow.

[Maples7]

Status update after upgrading to lark-cli 1.0.27 and re-syncing skills. Caveat (added in edit after #807#issuecomment-4419722347): lark-cli update --force only delivered references/lark-doc-*.md (which now teach --api-version v2) and left the top-level SKILL.md at 1.0.0. Only npx skills add larksuite/cli -g -y brought the bundle fully to 2.0.0. See #807 for details. The technical findings below stand either way — they only depend on agents using --api-version v2, which the references already teach.

The v2 +update surface is block-oriented — --command block_replace / block_insert_after / block_delete / overwrite / append / str_replace, addressing target blocks by --block-id rather than re-serializing the whole markdown body through Feishu's HTML→docx converter. So for an agent that has followed the skill upgrade, the v1 markdown-reshape path that triggered this bug is no longer the default path, and the <sub-page-list> strip won't be hit by such an agent.

Two caveats so this doesn't get closed prematurely:

1. The v1 surface is still supported and is still the default when --api-version is omitted — v1 callers (existing scripts and agents that haven't synced the skill) will keep hitting this.
2. I haven't directly tested whether v2's --command overwrite (which also takes a full markdown body) routes through the same normalizer that could re-introduce this symptom; if it does, the bug just moved. Happy to verify on request.

Flagging for triage — leave open / re-label as v1-only / close as wontfix is the maintainers' call.

[SunPeiYang996]

Thanks for the report. We plan to support this in a future version.

The current reason is that the sub-page-list block has not been implemented yet in the document block write path, so it is currently treated as unsupported during update. We will add support for this block later.

[fangshuyu-768]

Issue #813 — Status Update

The issue described here is no longer reproducible on the latest main branch.

What changed

The v1 MCP API path and all client-side markdown processing code were fully removed in commit f2a1390 ("feat: remove docs v1 api (#1291)"). This included:

• shortcuts/doc/markdown_fix.go (649 lines) — the client-side markdown-to-docx pipeline with 6 transforms (fixExportedMarkdown, fixBoldSpacing, fixTopLevelSoftbreaks, etc.)
• shortcuts/doc/docs_update_check.go (281 lines) — pre-write semantic warnings (docsUpdateWarnings, WarnCalloutType)

Current behavior

The docs +update command now passes markdown content directly to the server-side docs_ai OpenAPI (/open-apis/docs_ai/v1/documents/{token}) without any client-side HTML tag filtering or removal. The CLI acts as a thin pass-through — see shortcuts/doc/docs_update_v2.go:139-170 (buildUpdateBody).

Additionally, <sub-page-list> is now documented as a supported resource block in skills/lark-doc/references/lark-doc-xml.md:48:

<sub-page-list> — <sub-page-list></sub-page-list> 子页面列表块；仅 wiki 文档可插入

It is also listed as supporting copy operations (line 58).

Verification

• The string UNSUPPORTED_HTML_TAG does not appear anywhere in the current codebase or git history of this repository. The warning was likely emitted by the old v1 MCP server, not by the CLI itself.
• No client-side HTML tag filtering exists in the current docs +update code path.

Conclusion

The [WARNING:UNSUPPORTED_HTML_TAG] unsupported HTML tag removed: sub-page-list warning and the associated tag-stripping behavior no longer occur. Closing as resolved.

[fangshuyu-768]

Closing as resolved — the v1 API and client-side markdown processing have been fully removed. The docs +update command now passes content directly to the server-side docs_ai API without any client-side HTML tag filtering.