APIDoc 4.0.5 introduces powerful custom markdown content functionality that allows you to add rich, formatted content to any API group or section. This feature enables you to provide detailed explanations, usage examples, and contextual information directly within your API documentation.
The custom markdown feature allows you to:
apidoc.jsonAdd the settings section to your apidoc.json configuration file:
{
"name": "My API Documentation",
"version": "1.0.0",
"description": "API documentation with custom markdown content",
"settings": {
"Users": {
"icon": "fa-user",
"title": "User Management",
"filename": "docs/users.md"
},
"Authentication": {
"icon": "fa-shield-alt",
"title": "Authentication & Security",
"filename": "docs/auth.md"
},
"Company": {
"icon": "fa-building",
"title": "Company Operations",
"filename": "docs/company.md"
}
}
}
Create markdown files in your project directory:
docs/users.md:
## 👥 User Management
This section contains all endpoints related to user operations and profile management.
### Authentication Required
All user endpoints require a valid JWT token in the Authorization header:
```bash
Authorization: Bearer <your-jwt-token>
Different rate limits apply based on user tier:
| User Type | Requests/Minute | Burst Limit |
|---|---|---|
| Free | 60 | 100 |
| Premium | 600 | 1000 |
| Enterprise | 6000 | 10000 |
200 - Success401 - Unauthorized (invalid or missing token)403 - Forbidden (insufficient permissions)404 - User not found429 - Rate limit exceededconst response = await fetch('/api/users/me', {
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
}
});
💡 Tip: Always validate user permissions before performing operations that modify user data.
**`docs/auth.md`:**
```markdown
## 🔐 Authentication & Security
Our API uses JWT (JSON Web Tokens) for authentication with optional OAuth2 integration.
### Authentication Flow
1. **Login**: Exchange credentials for JWT token
2. **Token Usage**: Include token in Authorization header
3. **Refresh**: Use refresh token to get new access token
4. **Logout**: Invalidate tokens (optional)
### Security Best Practices
⚠️ **Important Security Guidelines:**
- Always use HTTPS in production
- Store tokens securely (httpOnly cookies recommended)
- Implement proper token expiration (15 minutes for access tokens)
- Use refresh tokens for longer sessions
- Validate tokens on every request
### Token Structure
Our JWT tokens contain the following claims:
```json
{
"sub": "user_id",
"email": "user@example.com",
"role": "admin|user|moderator",
"iat": 1640995200,
"exp": 1640998800
}
Authentication errors return consistent error responses:
{
"success": false,
"error": "INVALID_TOKEN",
"message": "Token has expired",
"code": 401
}
### 3. Generate Documentation
Run APIDoc to generate your documentation with custom markdown content:
```bash
# Basic generation
apidoc -i src/ -o docs/
# With verbose output
apidoc -v -i src/ -o docs/
# The custom markdown will automatically appear at the top of each section
| Property | Type | Required | Description |
|---|---|---|---|
icon |
string | No | Font Awesome icon class (e.g., fa-user, fa-cog) |
title |
string | No | Custom display title for the section |
filename |
string | Yes | Path to markdown file (relative to source directory) |
{
"settings": {
"GroupName": {
"icon": "fa-icon-name",
"title": "Custom Display Title",
"filename": "path/to/markdown/file.md"
}
}
}
The custom markdown content supports full markdown syntax including:
#, ##, ###)**bold**, *italic*, ~~strikethrough~~)Code blocks support syntax highlighting for all major languages:
{
"example": "JSON syntax highlighting"
}
// JavaScript syntax highlighting
function example() {
return "Hello World";
}
# Bash syntax highlighting
curl -X GET https://api.example.com/users
Create professional-looking tables:
| Feature | Status | Notes |
|---|---|---|
| Custom Icons | ✅ | Font Awesome icons |
| Markdown Support | ✅ | Full markdown syntax |
| Syntax Highlighting | ✅ | 100+ languages |
| HTML Integration | ✅ | Seamless rendering |
Use blockquotes for important information:
💡 Tip: This is a helpful tip for developers.
⚠️ Warning: This is an important warning.
❌ Error: This describes an error condition.
✅ Success: This indicates a successful operation.
Custom markdown content integrates perfectly with Font Awesome icons:
{
"settings": {
"Users": {
"icon": "fa-users",
"title": "User Management",
"filename": "docs/users.md"
},
"Analytics": {
"icon": "fa-chart-bar",
"title": "Analytics & Reports",
"filename": "docs/analytics.md"
}
}
}
| API Section | Recommended Icons |
|---|---|
| Users/Auth | fa-user, fa-users, fa-shield-alt |
| Admin | fa-crown, fa-cog, fa-tools |
| Files | fa-folder, fa-file, fa-upload |
| Analytics | fa-chart-bar, fa-chart-line |
| Payment | fa-credit-card, fa-dollar-sign |
| Location | fa-map-marker-alt, fa-globe |
| Communication | fa-envelope, fa-comments |
Use custom titles for localization:
{
"settings": {
"Users": {
"icon": "fa-user",
"title": "Gestión de Usuarios",
"filename": "docs/usuarios.md"
},
"Company": {
"icon": "fa-building",
"title": "Operaciones de Empresa",
"filename": "docs/empresa.md"
}
}
}
your-project/
├── src/ # Your API source code
├── docs/ # Custom markdown files
│ ├── users.md
│ ├── auth.md
│ ├── company.md
│ └── analytics.md
├── apidoc.json # APIDoc configuration
└── generated-docs/ # Generated documentation output
your-project/
├── src/
│ ├── controllers/
│ └── docs/ # Markdown files alongside source
│ ├── users.md
│ └── auth.md
├── apidoc.json
└── output/
You can include dynamic content using markdown features:
## 📊 API Statistics
Last updated: **$(date)**
### Current Status
- **Uptime**: 99.9%
- **Response Time**: < 100ms
- **Active Users**: 10,000+
### Recent Changes
Check our [changelog](./CHANGELOG.md) for the latest updates.
Reference external documentation:
## 📖 Additional Resources
For more detailed information, see:
- [API Design Guidelines](./DESIGN_GUIDELINES.md)
- [Security Best Practices](./SECURITY.md)
- [Rate Limiting Details](./RATE_LIMITS.md)
### External Links
- [OpenAPI Specification](https://swagger.io/specification/)
- [JWT.io](https://jwt.io/)
- [RESTful API Design](https://restfulapi.net/)
Use HTML comments for conditional content:
<!-- Development Environment Only -->
## 🔧 Development Tools
This section is only relevant for development environments.
### Debug Endpoints
These endpoints are available only in development mode:
- `GET /debug/health` - Health check with detailed info
- `GET /debug/metrics` - Internal metrics
- `POST /debug/reset` - Reset development data
<!-- End Development Content -->
Markdown file not found:
filename path is relative to your source directory.mdContent not rendering:
apidoc.json syntax is valid JSONIcons not displaying:
fa-user, not user)Use verbose mode to see markdown processing:
apidoc -v -i src/ -o docs/
Look for log messages like:
verbose: 📝 Loaded custom markdown for group: Users
verbose: 📝 Loaded custom markdown for group: Company
Project Structure:
my-api/
├── src/
│ ├── users.js
│ ├── auth.js
│ └── company.js
├── docs/
│ ├── users.md
│ ├── auth.md
│ └── company.md
├── apidoc.json
└── output/
apidoc.json:
{
"name": "My API Documentation",
"version": "1.0.0",
"description": "Comprehensive API documentation with custom content",
"url": "https://api.example.com",
"settings": {
"Users": {
"icon": "fa-users",
"title": "User Management",
"filename": "docs/users.md"
},
"Authentication": {
"icon": "fa-shield-alt",
"title": "Authentication",
"filename": "docs/auth.md"
},
"Company": {
"icon": "fa-building",
"title": "Company Operations",
"filename": "docs/company.md"
}
},
"order": ["Authentication", "Users", "Company"]
}
Generate Documentation:
apidoc -i src/ -o output/
This creates a professional API documentation site with custom markdown content integrated seamlessly into each section.
## for main sections, ### for subsections)Made with ❤️ by the APIDoc community