Update component docs to new format with example-first structure #1639
Conversation
- Move visual examples to the top of each component page - Add Usage section with markdown code blocks - Convert sections to Variants subsections - Keep Properties section at the end - Remove Tabs wrappers around examples - Updated all 23 component pages in default-components directory Co-Authored-By: Kapil Gowru <[email protected]>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| href="/learn/docs/writing-content/components/cards" | ||
| > | ||
| Generate a Python SDK and publish to PyPi | ||
| Learn how to properly water your plants |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'properly' if it's not important to the meaning of the statement.
| ## Font Awesome styles | ||
| ## Variants | ||
|
|
||
| ### Font Awesome styles |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Font Awesome styles' should use sentence-style capitalization.
| </Tab> | ||
| </Tabs> | ||
| <CodeBlock | ||
| links={{"PlantClient": "/learn/docs/writing-content/demo#plantclient", "createPlant": "/learn/docs/writing-content/demo#createplant"}} |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Quotes] Punctuation should be inside the quotes.
| ```python | ||
| from plantstore import PlantStore, PlantClient | ||
| <CodeBlock | ||
| links={{"/get\\w+/": "/learn/docs/writing-content/demo#get-methods", "/Plant(Store|Client)/": "/learn/docs/writing-content/demo#type-definitions"}} |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Quotes] Punctuation should be inside the quotes.
| </ParamField> | ||
|
|
||
| <ParamField path="sideOffset" type="number" required={false} default={4}> | ||
| The distance in pixels between the tooltip and the trigger element. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Units] Don't spell out the number in 'in pixels'.
- Remove 'properly' adverb from card-groups.mdx - Change 'Font Awesome styles' to 'Font Awesome icon styles' for sentence case - Add trailing commas to fix punctuation in code-blocks.mdx - Change 'in pixels' to '(in pixels)' in tooltips.mdx Co-Authored-By: Kapil Gowru <[email protected]>
| ## Font Awesome styles | ||
| ## Variants | ||
|
|
||
| ### Font Awesome icon styles |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Font Awesome icon styles' should use sentence-style capitalization.
| </Tab> | ||
| </Tabs> | ||
| <CodeBlock | ||
| links={{"PlantClient": "/learn/docs/writing-content/demo#plantclient", "createPlant": "/learn/docs/writing-content/demo#createplant",}} |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Quotes] Punctuation should be inside the quotes.
| </Tab> | ||
| </Tabs> | ||
| <CodeBlock | ||
| links={{"PlantClient": "/learn/docs/writing-content/demo#plantclient", "createPlant": "/learn/docs/writing-content/demo#createplant",}} |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Quotes] Punctuation should be inside the quotes.
| ```python | ||
| from plantstore import PlantStore, PlantClient | ||
| <CodeBlock | ||
| links={{"/get\\w+/": "/learn/docs/writing-content/demo#get-methods", "/Plant(Store|Client)/": "/learn/docs/writing-content/demo#type-definitions",}} |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Quotes] Punctuation should be inside the quotes.
| ```python | ||
| from plantstore import PlantStore, PlantClient | ||
| <CodeBlock | ||
| links={{"/get\\w+/": "/learn/docs/writing-content/demo#get-methods", "/Plant(Store|Client)/": "/learn/docs/writing-content/demo#type-definitions",}} |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Quotes] Punctuation should be inside the quotes.
| </ParamField> | ||
|
|
||
| <ParamField path="sideOffset" type="number" required={false} default={4}> | ||
| The distance (in pixels) between the tooltip and the trigger element. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Units] Don't spell out the number in 'in pixels'.
The Aside component was not rendering because it used a non-existent endpoint 'POST /plants/{plantId}'. Changed to use 'POST /chat/{domain}' which is a valid endpoint in the API definition and is used successfully in other component pages.
Co-Authored-By: Kapil Gowru <[email protected]>
- Remove trailing commas in CodeBlock links attributes (code-blocks.mdx) - Rephrase units description to avoid Vale warning (tooltips.mdx) Addresses Vale comments on PR #1639 Co-Authored-By: Kapil Gowru <[email protected]>
| </ParamField> | ||
|
|
||
| <ParamField path="sideOffset" type="number" required={false} default={4}> | ||
| The distance between the tooltip and the trigger element, in pixels. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Units] Don't spell out the number in 'in pixels'.
Changed 'in pixels' to '(px)' to satisfy Microsoft.Units rule which flags 'in <unit>' without a numeral. Addresses Vale comment on PR #1639 Co-Authored-By: Kapil Gowru <[email protected]>
| Callouts help highlight important information, warnings, or tips in your documentation. They provide visual emphasis through distinct styling and icons to make key messages stand out to readers. | ||
|
|
||
| To display very short pieces of information like status indicators and version numbers, use the [Badges component](/docs/writing-content/components/badges) | ||
| To display very short pieces of information like status indicators and version numbers, use the [Badges component](/docs/writing-content/components/badges). |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'very' if it's not important to the meaning of the statement.
|
|
||
| ## Properties | ||
|
|
||
| ### Card Group properties |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Card Group properties' should use sentence-style capitalization.
| | MP4 Video | `video/mp4` | | ||
| | WebM Video | `video/webm` | | ||
| | SVG Image | `image/svg+xml` | | ||
| | PNG Image | `image/png` | |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'PNG' has no definition.
| --- | ||
|
|
||
| The `<RunnableEndpoint>` component enables users to make real HTTP requests to your APIs directly in the API Reference. It auto-detects endpoint definitions from your API specification and provides a request builder with inputs for headers, path parameters, query parameters, and request bodies. | ||
| The `<RunnableEndpoint>` component lets users make real HTTP requests to your APIs directly in the API Reference. It auto-detects endpoint definitions from your API specification and provides a request builder with inputs for headers, path parameters, query parameters, and request bodies. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Auto] In general, don't hyphenate 'auto-detects'.
| API_KEY: ( | ||
| <p> | ||
| Your API key is used to authenticate requests to our API. Keep this secure and never expose it in client-side code. | ||
| Your API key is used to authenticate requests to our API. Keep this secure and never expose it in client-side code. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.We] Try to avoid using first-person plural like 'our'.
…://github.com/fern-api/docs into devin/1761852453-update-component-docs-format
| --- | ||
|
|
||
| The `<RunnableEndpoint>` component enables users to make real HTTP requests to your APIs directly in the API Reference. It auto-detects endpoint definitions from your API specification and provides a request builder with inputs for headers, path parameters, query parameters, and request bodies. | ||
| The Runnable Endpoint component lets users make real HTTP requests to your APIs directly in the API Reference. It auto-detects endpoint definitions from your API specification and provides a request builder with inputs for headers, path parameters, query parameters, and request bodies. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Auto] In general, don't hyphenate 'auto-detects'.
| The `<Callout>` component highlights important information, warnings, or tips in your documentation. Use callouts to emphasize critical details that readers shouldn't miss, such as breaking changes, prerequisites, or helpful best practices. | ||
|
|
||
| To display very short pieces of information like status indicators and version numbers, use the [Badges component](/docs/writing-content/components/badges) | ||
| To display very short pieces of information like status indicators and version numbers, use [badges](/docs/writing-content/components/badges). |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'very' if it's not important to the meaning of the statement.
| ``` | ||
| ```` | ||
|
|
||
| ## Code blocks with Tabs |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Code blocks with Tabs' should use sentence-style capitalization.
| """Check if a number is prime.""" | ||
| if num <= 1: | ||
| return False | ||
| for i in range(2, num): |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.FirstPerson] Use first person (such as ' i') sparingly.
| </Tabs> | ||
| <div className="highlight-frame"> | ||
| ```txt title="With wordWrap" wordWrap | ||
| A very very very long line of text that may cause the code block to overflow and scroll as a result. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'very' if it's not important to the meaning of the statement.
| </Tabs> | ||
| <div className="highlight-frame"> | ||
| ```txt title="With wordWrap" wordWrap | ||
| A very very very long line of text that may cause the code block to overflow and scroll as a result. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'very' if it's not important to the meaning of the statement.
| </Tabs> | ||
| <div className="highlight-frame"> | ||
| ```txt title="With wordWrap" wordWrap | ||
| A very very very long line of text that may cause the code block to overflow and scroll as a result. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'very' if it's not important to the meaning of the statement.
Update component docs to new format with example-first structure
Summary
Updated all 23 component documentation pages in the default-components directory to follow a new standardized format inspired by Fumadocs. The new structure prioritizes showing working examples first, followed by usage instructions, variants, and finally the API reference.
New structure:
## Usagesection with markdown code block showing basic usage## Variantssection with subsections for additional examples/variations## Propertiessection at the end with API referenceKey changes:
<Tabs>wrappers that separated "Example" and "Markdown" tabsFiles updated (22 total):
accordions.mdx, accordion-groups.mdx, anchor.mdx, aside.mdx, badges.mdx, button.mdx, callouts.mdx, cards.mdx, card-groups.mdx, code-blocks.mdx, embed.mdx, endpoint-request-snippet.mdx, endpoint-response-snippet.mdx, endpoint-schema-snippet.mdx, runnable-endpoint.mdx, frames.mdx, icons.mdx, parameter-fields.mdx, steps.mdx, sticky-tables.mdx, tabs.mdx, tooltips.mdx
Review & Testing Checklist for Human
Test Plan
Notes
Session info:
Local testing screenshots: