docs: add MDX features reference for content authors#1045
docs: add MDX features reference for content authors#1045je-contractor wants to merge 6 commits intomainfrom
Conversation
🔗 Preview Mode
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b9e53cf245
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
MDX_FEATURES.md
Outdated
| ```md | ||
| <Steps> |
There was a problem hiding this comment.
The Steps usage sample is opened with a triple-backtick fence ( ```md), but the sample itself contains multiple triple-backtick code blocks, so the first inner fence closes the outer block and the rest of the example is rendered as real markdown instead of literal source. This makes the section hard to read and gives authors a broken snippet to copy for Steps with nested code blocks.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Codex beat me to it. This section looks weird
There was a problem hiding this comment.
Fixed - switched to quintuple backtick fencing on the outer block.
MDX_FEATURES.md
Outdated
| * \[x] Completed task | ||
| * \[ ] Incomplete task |
There was a problem hiding this comment.
The task-list example escapes the brackets (\[x] and \[ ]), so readers who copy this snippet will get literal bracket text rather than GFM checkbox items. Since this section is documenting supported remark-gfm syntax, the sample should use unescaped [x]/[ ] to produce actual task lists.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed - removed the backslash escapes so they render as proper checkboxes.
MDX_FEATURES.md
Outdated
|
|
||
| ## Code Blocks | ||
|
|
||
| Fenced code blocks support syntax highlighting via [Shiki](https://shiki.matsu.io/) with dual light/dark themes. |
There was a problem hiding this comment.
Technically we use rehype-pretty-code which I think uses shiki under the hood
There was a problem hiding this comment.
Updated to reference rehype-pretty-code (powered by Shiki).
MDX_FEATURES.md
Outdated
| * \[x] Completed task | ||
| * \[ ] Incomplete task |
MDX_FEATURES.md
Outdated
| ```md | ||
| <Steps> |
There was a problem hiding this comment.
Codex beat me to it. This section looks weird
Fix task list escaping, correct Shiki attribution to rehype-pretty-code, add line highlighting syntax, fix broken Steps fencing, link icon sprite sheet, and correct StickyTable description.
Prettier re-escapes task list brackets on commit. Adding this specific file to .prettierignore prevents that while leaving all other md/mdx files unaffected.
Prettier re-escapes GFM task list brackets when run directly on staged files. Filter this file out of the prettier step in lint-staged config.
2 participants
Summary
Adds a practical reference doc (
MDX_FEATURES.md) listing all available MDX components, GFM features, props, and usage examples for content authors. This replaces reliance on Fern's documentation which will diverge over time.Covers: Callout (all variants), Card/CardGroup, CodeGroup, Tabs, Steps, Accordion, Markdown includes, Icon, Images, Mermaid diagrams, StickyTable, and standard GFM features.
Ticket: DX-2236