feat: render API doc response examples and schemas in SSR for .md export #2239
Conversation
The llms-txt plugin generates .md files from static HTML, but three OpenAPI theme components (ResponseSchema, ParamsDetails, RequestSchema) were wrapped in BrowserOnly, rendering only skeleton placeholders during SSR. This removed the BrowserOnly wrapper so the full content renders server-side and appears in the .md exports. Co-Authored-By: Claude Opus 4.6 <[email protected]>
github-actions
bot
added
the
t-tooling
|
Preview for this PR was built for commit |
The .md export was mixing content from different response codes (200, 400) together because tab UI doesn't translate to markdown hierarchy. Add sr-only h3 headings per status code so the llms-txt plugin produces proper nesting. Co-Authored-By: Claude Opus 4.6 <[email protected]>
|
Preview for this PR was built for commit |
Add whitespace between property names, types, and badges (required, nullable, deprecated) so they don't run together in markdown output. Move label spaces outside <strong> elements to prevent   HTML entities and <!-- --> SSR comments in the exported .md files. Components patched: SchemaItem, Schema (Summary), ParamsItem, Example. Co-Authored-By: Claude Opus 4.6 <[email protected]>
|
Preview for this PR was built for commit |
Render Array [ and ] brackets via CSS ::before pseudo-elements instead of DOM text content so they don't leak into the markdown export. Also fixes remaining SSR comment artifacts in Schema Summary and ParamsItem. Co-Authored-By: Claude Opus 4.6 <[email protected]>
|
Preview for this PR was built for commit |
Change SchemaItem wrapper from <div> to <li> and SchemaNodeDetails nesting wrapper from <div> to <ul> so the HTML-to-markdown converter produces properly indented nested lists reflecting the schema hierarchy. Also fix remaining SSR comment in discriminator section. Co-Authored-By: Claude Opus 4.6 <[email protected]>
|
Preview for this PR was built for commit |
- ArrayBrackets: remove <li> wrapper (empty brackets produced stray `*`) - SchemaItem: use Fragment instead of <div> wrapper to avoid loose lists - Example/DefaultValue/ConstValue: use <br> + <span> instead of <div> to get line breaks without blank-line paragraph separation - SchemaNodeDetails: move description outside <ul> to avoid invalid block elements inside lists Co-Authored-By: Claude Opus 4.6 <[email protected]>
|
Preview for this PR was built for commit |
- Patch llms-txt plugin to use {type:'break'} instead of raw HTML for
<br> handler, producing clean \ line breaks instead of <br /> tags
- Conditionally render name <strong> in SchemaItem only when present,
preventing empty bold (****) for unnamed anyOf/oneOf schema options
Co-Authored-By: Claude Opus 4.6 <[email protected]>
|
Preview for this PR was built for commit |
… labels Hide status code, MIME type, and Example/Schema tab lists during SSR so they don't leak as bullet points into the markdown export. SchemaTabs uses a selective `hideTabListSSR` prop so anyOf/oneOf option labels (used by AnyOneOf) remain visible in the markdown. Co-Authored-By: Claude Opus 4.6 <[email protected]>
|
Preview for this PR was built for commit |
B4nan
changed the title
Add display:none to <br> elements used for markdown line breaks. The rehype-remark converter still processes them in the HTML AST, but they no longer create visual gaps in the browser. Co-Authored-By: Claude Opus 4.6 <[email protected]>
|
Preview for this PR was built for commit |
|
I wouldn't try to review the patches much, let's focus on how it looks and works in the preview. I checked it and there are just a few whitespace differences, looks good to me. |
There was a problem hiding this comment.
The rendered md documents seem mostly fine to me 👍
The only nit is that the markdown render drops the discriminator value for the tabs (e.g. FREE, PRICE_PER_DATASET_ITEM here)
| docs | md |
|---|---|
 |
 |
So there is no way of knowing why there are three similar sections on top of each other.
Also, docusaurus-theme-openapi-docs deserves a fork at this point 👀
|
Preview for this PR was built for commit |
Two fixes for discriminator schemas (e.g., pricingModel with PAY_PER_EVENT, PRICE_PER_DATASET_ITEM, etc.): 1. Pre-merge allOf subschemas in DiscriminatorNode so SchemaNode doesn't re-merge them and bring back the deleted discriminator property. This eliminates repeated pricingModel enum values. 2. Render discriminator variants with proper nesting during SSR: each variant label is a list item with its schema fields nested in a child <ul>, skipping the TabItem <div> wrapper that would break <li> nesting in HTML. Co-Authored-By: Claude Opus 4.6 <[email protected]>
B4nan
force-pushed
the
fix/api-docs-markdown-ssr-content
branch
from
f6aa084 to
e4cd321
Compare
|
Preview for this PR was built for commit |
|
This is how it looks now, should be good enough for now. 
|
3 participants
Summary
@signalwire/docusaurus-plugin-llms-txtplugin generates.mdfiles from static (SSR) HTML, but three OpenAPI theme components (ResponseSchema,ParamsDetails,RequestSchema) were wrapped inBrowserOnly, rendering only<div class="openapi-skeleton">placeholders during SSRBrowserOnlywrapper from these three components so the full content (response examples, schema definitions, request parameters) renders server-side and appears in the.mdexportsApiItemcomponent already creates a Redux store for SSR and none of these components use browser-specific APIsTest plan
npm run buildsucceeds without errors.mdfiles now contain full response examples (JSON bodies), schema definitions (field names, types, descriptions), and request parameters🤖 Generated with Claude Code