mirror of
https://github.com/vercel/components.build.git
synced 2026-09-14 20:06:39 +08:00
Hayden Bleasel
156 lines
6.2 KiB
Plaintext
156 lines
6.2 KiB
Plaintext
---
|
||
title: Docs
|
||
description: How to document your components.
|
||
type: guide
|
||
summary: Essential documentation sections for components including demos, installation, API reference, accessibility notes, and changelog.
|
||
prerequisites:
|
||
- /composition
|
||
related:
|
||
- /registry
|
||
- /npm
|
||
- /marketplaces
|
||
---
|
||
|
||
Good documentation is essential for making your components accessible and easy to use. This guide outlines the key elements every component documentation page should include.
|
||
|
||
## Documentation Framework
|
||
|
||
To scale your documentation, you can use a documentation framework. There are many options available depending on your projects' language and project needs. Popular options include:
|
||
|
||
- [Fumadocs](https://fumadocs.dev/) - Fast, feature-rich documentation framework for Next.js
|
||
- [Nextra](https://nextra.site/) - Markdown-based documentation with built-in search and theming
|
||
- [Content Collections](https://content-collections.dev/) - Type-safe content management for documentation
|
||
- [Docusaurus](https://docusaurus.io/) - Feature-rich documentation sites with versioning support
|
||
- [VitePress](https://vitepress.dev/) - Vue-powered static site generator optimized for documentation
|
||
|
||
Preferably, your framework choice should support syntax highlighting, custom components and be generally well designed.
|
||
|
||
## Essential Documentation Sections
|
||
|
||
### Overview
|
||
|
||
Start with a brief introduction explaining what the component does and when to use it.
|
||
|
||
### Demo, Source Code, and Preview
|
||
|
||
For a great first impression for developers, you should include a demo that shows the component in action, as well as the code used to create the demo.
|
||
|
||
If you're using an open source [Registry](/registry), you can also include a preview of the source code that is used to create the component.
|
||
|
||
Use code blocks with syntax highlighting and copy-to-clipboard functionality. Consider using tabbed interfaces to switch between these views without cluttering the page.
|
||
|
||
### Installation
|
||
|
||
Include a clear instruction on how to install the component. Preferably this should be a single command you can copy and paste into your terminal.
|
||
|
||
If you're building on shadcn/ui, you can use the [shadcn CLI](https://ui.shadcn.com/docs/cli) to install the component e.g.
|
||
|
||
```package-install
|
||
npx shadcn@latest add <your-component-url>
|
||
```
|
||
|
||
If you're publishing to a [Marketplace](/marketplaces), you can use the marketplace's CLI to install the component e.g.
|
||
|
||
```package-install
|
||
npx shadcn@latest add https://21st.dev/r/<your-author>/<your-component>
|
||
```
|
||
|
||
If you're not using shadcn/ui but you are building a [Registry](/registry), you could build your own CLI to install the component, e.g.
|
||
|
||
```package-install
|
||
npx your-registry-cli@latest add <your-component-url>
|
||
```
|
||
|
||
Lastly, if you're publishing to npm, you can use the npm CLI to install the component e.g.
|
||
|
||
```package-install
|
||
npm install <your-component-name>
|
||
```
|
||
|
||
<Callout>
|
||
To show multiple installation options like we've done above, you can use
|
||
something like Fumadocs' [`package-install`
|
||
syntax](https://fumadocs.dev/docs/headless/mdx/install).
|
||
</Callout>
|
||
|
||
### Features
|
||
|
||
List the key features of your component to help users quickly understand its capabilities and advantages. For example:
|
||
|
||
- **Customizable** – Easily adjust styles, sizes, and behavior to fit your needs.
|
||
- **Accessible by default** – Follows best practices for keyboard navigation, ARIA roles, and screen reader support.
|
||
- **Composable** – Designed to work seamlessly with other components and patterns.
|
||
- **Type-safe** – Ships with comprehensive TypeScript types for maximum safety and autocomplete.
|
||
- **Theming support** – Integrates with your design tokens or theme system.
|
||
- **Lightweight** – Minimal dependencies and optimized for performance.
|
||
- **SSR/SSG ready** – Works with server-side and static rendering frameworks.
|
||
- **Well-documented** – Includes clear usage examples and API reference.
|
||
|
||
Tailor this list to your specific component. Highlight what makes it unique or especially useful for developers.
|
||
|
||
### Examples
|
||
|
||
Demonstrate the component's flexibility with practical examples:
|
||
|
||
- **Variants** - Different visual styles or sizes available
|
||
- **States** - Loading, disabled, error, or success states
|
||
- **Advanced Usage** - Complex scenarios and edge cases
|
||
- **Composition** - How the component works with other components
|
||
- **Responsive Behavior** - How it adapts to different screen sizes
|
||
|
||
Each example should include both the rendered output and the corresponding code.
|
||
|
||
### Props and API Reference
|
||
|
||
Document all available props, methods, and configuration options. Consider grouping related props together and highlighting commonly used ones. For each prop, include:
|
||
|
||
- **Name** - The prop identifier
|
||
- **Type** - TypeScript type definition
|
||
- **Default** - Default value if not specified
|
||
- **Required** - Whether the prop is mandatory
|
||
- **Description** - What the prop does and when to use it
|
||
|
||
<Callout>
|
||
If you're using Fumadocs, you might consider using [Auto Type
|
||
Table](https://fumadocs.dev/docs/ui/components/auto-type-table) to ensure
|
||
accuracy and reduce maintenance burden.
|
||
</Callout>
|
||
|
||
### Accessibility
|
||
|
||
Document how your component supports accessibility features:
|
||
|
||
- Keyboard navigation patterns
|
||
- ARIA attributes and roles
|
||
- Screen reader support
|
||
- Focus management
|
||
- Color contrast considerations
|
||
|
||
### Changelog and Versioning
|
||
|
||
It can be useful to maintain a changelog on each component documentation page covering:
|
||
|
||
- Version numbers following semantic versioning
|
||
- New features and enhancements
|
||
- Bug fixes
|
||
- Breaking changes
|
||
- Migration guides for major version updates
|
||
|
||
Help users understand what changed between versions and how to upgrade safely. Include code examples showing before/after patterns for breaking changes.
|
||
|
||
<Callout>
|
||
If your syntax highlighting framework supports it (like Shiki), you might want
|
||
to use a [diff transformer
|
||
notation](https://shiki.style/packages/transformers#transformernotationdiff)
|
||
to show the changes between versions.
|
||
</Callout>
|
||
|
||
## Best Practices
|
||
|
||
- Keep documentation up-to-date with code changes
|
||
- Use real-world examples that solve actual problems
|
||
- Include common pitfalls and troubleshooting tips
|
||
- Provide performance considerations when relevant
|
||
- Link to related components and patterns
|
||
- Make all code examples runnable and tested
|