docs(other): demo tag for Redocly's markdoc tags - #398
Conversation
remoteId: rem_01jwbtfqhbbam07z9j9m0etng6 remoteUpdateId: grupd_01m0yp3c953wmfnjz50ch4g9xt branchName: docs/card-styling-updates commitSha: 58efaf006b98b474ec66132dc20c14b1543da59e commitUrl: Redocly/redocly@58efaf0 prId: 26402
![redocly[bot]](https://avatars.githubusercontent.com/in/348054?s=60&v=4){kind=small}
There was a problem hiding this comment.
marketing-site AI Review: 🟢 Completed
Redocly Agent has reviewed your changes and found 4 potential issue(s).
Note
Low Risk
The changes are isolated to documentation and internal Markdoc tooling. The new demo tag is used strictly for documentation rendering, and the blast radius is limited to documentation pages that utilize this tag.
Overview
Introduces a custom demo Markdoc tag that enables interactive live previews and customizations of Markdoc tags within the documentation.
- Adds new React components to
@theme/markdoc(such asDemo,AttributeControl,ColorControl, andRadioGroup) to power the interactive demo UI. - Registers the
demotag in the Markdoc schema (@theme/markdoc/schema.ts). - Bumps
@redocly/realmand@redocly/themedependencies to their latestnextversions. - Demonstrates the new tag's configuration and usage in
docs/realm/content/markdoc-tags/cards.md.
There was a problem hiding this comment.
Caution
Remote content override — this pull request changes files that are managed by remote content. If it is merged, these changes may be overwritten on the next remote content update. Edit the content in its source instead.
docs/realm/content/markdoc-tags/cards.md— managed by the remote content mount/docs/realm/
| # required: false | ||
| # location: end | ||
| # separators: | ||
| # - location: align |
There was a problem hiding this comment.
The frontmatter contains numerous commented-out lines (e.g., # content:, # location: end, # separators:) across multiple property definitions like variantProperties and badgeProperties. Remove them to clean up the configuration.
| properties: { | ||
| type: Object, | ||
| description: | ||
| 'Attribute descriptors of the demonstrated tag, either as a flat map or as "groups", "content", and "attributes". Each descriptor holds a "type", and optionally "default", "required", "description", "enum", and "group".', |
There was a problem hiding this comment.
The description for properties lists "groups", "content", and "attributes", but omits "separators", which is supported and used in cards.md. The attribute descriptor list also omits supported fields like hidden and matches.
| return Object.fromEntries( | ||
| Object.entries(source).filter(([, descriptor]) => isPlainObject(descriptor)), | ||
| ) as AttributeDescriptors; | ||
| } |
There was a problem hiding this comment.
The toDescriptors function intends to exclude the "children" property, as the comment indicates, but its filter only checks isPlainObject(descriptor). Update the condition to explicitly filter it out by key name.
| # content: | ||
| # required: false | ||
| # location: end | ||
| attributes: |
There was a problem hiding this comment.
The new demo tag and its $frontmatter property schema (e.g., groups, attributes, separators) are completely undocumented. Without an explanation or reference page, other doc authors cannot intuitively know how to structure properties to use the demo tag.
1 participant
What/Why/How?
This PR introduces
democustom markdoc tag for our docs.The purpose of that tag is to demo and live customization of Redocly's markdoc tags directly on their docs page.
Reference
Testing
Screenshots (optional)
Check yourself
Security