@types/markdown-it-container targets a different @types/markdown-it build, so
its plugin signature doesn't unify with our MarkdownIt instance — astro check
(tsc) failed. Cast it to the expected use() parameter type.
Make /docs/api/<operationId> the canonical shareable URL for an endpoint
(previously only /docs/api?op=<id> worked). The React app now reads the op from
the pathname (query ?op= kept as a fallback for old links) and pushes path URLs
on navigation. Add prerendered [op].astro routes (en + zh-CN/zh-HK) so direct
load, refresh, and sharing of /docs/api/<op> resolve — rendering the same
interactive reference, with the endpoint summary in the page title.
Region warnings, tips, etc. were rendering as plain blockquotes in the
reference. Convert them back to ::: container syntax in the descriptions and
add a markdown-it-container plugin that emits the same DOM as the docs
remark-callout (.callout.callout-<type> + .callout-title), with the docs
callout.css copied into the package. Now :::warning/:::tip render as the same
colored boxes as docs; the .md keeps readable ::: blocks for AI consumers.
The reference's QuotePermission was rendering unstyled (plain text, no green
box / shield icon / badge pill) because its class names had no CSS and it only
supported 'command' (level-only watchlist ops rendered nothing). Port it 1:1
from the docs MDX component: shield icon, data-level color theming, market tag,
description, footer link + note; resolve command/level/market. Copy the docs
QuotePermission.css into the package and load it via api-reference.css.
Add x-subgroup (docs subsection) to every op and x-subgroups (ordered
subsection labels, trilingual) to each tag, so the reference sidebar nests
like the docs menu: e.g. 行情 > 个股行情/期权/数据分析/自选股, 交易 >
订单/网格交易/成交/资产. Screener stays flat (no docs subsections).
- Loader: SubGroup type; parseSpec partitions each tag's endpoints into
ordered subgroups (by op x-subgroup, ordered per tag x-subgroups) plus
leftover flat endpoints.
- ApiReference: nested collapsible subgroup level in the sidebar.
- openapi-markdown: render ## section > ### subsection > #### endpoint;
fix endpointList / endpointMarkdownById to include subgroup endpoints
(they previously only walked flat endpoints, 404-ing per-endpoint .md).
Audited all 116 backing-page ops for special markers. Fixes:
- QuotePermission: render x-quote-command/level/market as a callout in BOTH
the CSR page and the AI markdown (openapi-markdown resolves
quote-permissions.yaml). Convert the 4 watchlist ops' leaked
'<QuotePermission level="basic" />' raw tags to x-quote-level: basic.
- Convert 2 topics ops' leaked '<TipContainer>' tags to blockquotes.
- Restore 3 admonitions dropped by the description cut / descOverride:
dca_toggle (US-account region warning), grid_trigger_history (uses
grid_order_id not order_id), ai_conversation (how to find an Agent UID).
- Loader: add x-quote-level / x-quote-market. CSR: pass level+market to
<QuotePermission>, render when any of command/level/market is set.
- Correct 5 endpoints' request params to true HTTP wire names (Rust does
client-side transforms): screener/search body (filters/returns/page/size),
broker-holding (add type), broker-holding/daily (parti_number),
ahpremium/klines (line_type/line_num), finance_calendar (date/date_end/
types[]/markets[]); fix finance_calendar response type wire name.
- Make POST examples executable: include full body (not just required) with
type-aware placeholders (arrays/ints/objects), so top_movers etc. no longer
emit an empty POST.
- Disambiguate duplicate summaries: short_positions/short_trades hk vs us now
carry market-specific titles.
- Strip embedded leading headings from descriptions (removes duplicate H1).
- Renderer: drop page-body heading that repeats the page title (fixes the
doubled '## Error Codes' in the aggregated api.md).
copy-routes now emits both foo.html and foo/index.html so the unchanged nginx serves docs/sdk (.html) and the catch-all (/index.html). Fix an invalid empty selector in api-reference.css that broke lightningcss minify. Exclude migration URLs from the sitemap. Point the release/canary deploy at dist/ instead of the removed docs/.vitepress/dist (was uploading an empty dir → no md/html on OSS).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
袁章洪