# XBP Documentation
Welcome to the XBP documentation! This folder contains comprehensive guides and references for using XBP.
## Documentation Structure
```
docs/
├── index.mdx # Documentation home
├── getting-started.mdx # Quick start guide
├── installation.mdx # Installation instructions
├── configuration.mdx # Configuration reference
├── cli-reference.mdx # Complete CLI reference
├── commands/ # Command-specific docs
│ ├── diag.mdx # xbp diag
│ ├── monitor.mdx # xbp monitor
│ ├── tail.mdx # xbp tail
│ └── ports.mdx # xbp ports
└── guides/ # Tutorial-style guides
└── monitoring.mdx # Monitoring guide
```
## Quick Links
- **[Getting Started](./getting-started.mdx)** - Get up and running in 5 minutes
- **[Installation](./installation.mdx)** - How to install XBP
- **[Configuration](./configuration.mdx)** - Configure your project
- **[CLI Reference](./cli-reference.mdx)** - All commands and options
## Command Documentation
- **[xbp diag](./commands/diag.mdx)** - System diagnostics
- **[xbp monitor](./commands/monitor.mdx)** - Health monitoring
- **[xbp tail](./commands/tail.mdx)** - Log management
- **[xbp ports](./commands/ports.mdx)** - Port management
## Guides
- **[Monitoring Guide](./guides/monitoring.mdx)** - Set up comprehensive monitoring
## Documentation Format
All documentation is written in MDX (Markdown with JSX), which allows for:
- Rich formatting
- Code syntax highlighting
- Interactive examples
- Component embedding
## Contributing to Documentation
### File Naming
- Use kebab-case: `getting-started.mdx`
- Use `.mdx` extension for all docs
- Group related docs in subdirectories
### Front Matter
Each doc file should have front matter:
```mdx
---
title: Page Title
description: Brief description
---
```
### Code Examples
Use language-specific code blocks:
````mdx
```bash
xbp diag
```
```json
{
"project_name": "my-app"
}
```
````
### Internal Links
Use relative links:
```mdx
[Configuration Guide](/docs/configuration)
[Command Reference](/docs/commands/diag)
```
## Building Documentation
### For Static Site Generators
These MDX files can be used with:
- **Next.js** with `@next/mdx`
- **Docusaurus**
- **Gatsby**
- **VitePress**
### Example Next.js Setup
```bash
npm install @next/mdx @mdx-js/loader @mdx-js/react
```
```javascript
// next.config.js
const withMDX = require('@next/mdx')({
extension: /\.mdx?$/,
});
module.exports = withMDX({
pageExtensions: ['js', 'jsx', 'md', 'mdx'],
});
```
### Example Docusaurus Setup
```bash
npx create-docusaurus@latest my-website classic
# Copy docs/ folder to my-website/docs/
```
## Documentation Standards
### Writing Style
- **Clear and concise** - Get to the point quickly
- **Examples first** - Show, then explain
- **Progressive disclosure** - Basic → Advanced
- **Consistent terminology** - Use same terms throughout
### Code Examples
- **Complete and runnable** - Examples should work as-is
- **Realistic** - Use real-world scenarios
- **Commented** - Explain non-obvious parts
- **Tested** - Verify examples work
### Structure
- **Overview** - What and why
- **Usage** - How to use
- **Examples** - Real-world examples
- **Options** - Detailed option reference
- **Troubleshooting** - Common issues
- **See Also** - Related documentation
## Maintenance
### Updating Documentation
1. Update relevant `.mdx` files
2. Test all code examples
3. Update version numbers if needed
4. Check internal links
5. Update table of contents if structure changed
### Version Control
- Keep docs in sync with code
- Tag docs with releases
- Maintain changelog
- Archive old versions
## Support
For documentation issues:
- **Typos/Errors**: Open a PR with fix
- **Missing Info**: Open an issue describing what's needed
- **Unclear Sections**: Open an issue with suggestions
- **New Topics**: Open an issue proposing the topic
## License
Documentation is licensed under MIT, same as XBP itself.
## See Also
- [Main README](../README.md)
- [CLI Guide](../CLI_GUIDE.md)
- [Changelog](../CHANGELOG.md)
- [Implementation Summary](../IMPLEMENTATION_SUMMARY.md)