444 lines
9.1 KiB
Plaintext
444 lines
9.1 KiB
Plaintext
---
|
|
description: "Guidelines for developing and maintaining Langflow documentation using Docusaurus, including content structure, style, and deployment processes."
|
|
globs:
|
|
- "docs/**/*.{md,mdx}"
|
|
- "docs/**/*.{js,jsx,ts,tsx}"
|
|
- "docs/package*.json"
|
|
- "docs/docusaurus.config.js"
|
|
- "docs/sidebars.js"
|
|
- "docs/static/**/*"
|
|
alwaysApply: false
|
|
---
|
|
|
|
|
|
# Documentation Development Guidelines
|
|
|
|
## Purpose
|
|
Guidelines for developing and maintaining Langflow documentation using Docusaurus, including content structure, style, and deployment processes.
|
|
|
|
---
|
|
|
|
## 1. Documentation Environment Setup
|
|
|
|
### Prerequisites
|
|
- **Node.js:** v22.12 LTS for runtime
|
|
- **Package Manager:** npm for dependency management
|
|
- **Documentation Framework:** Docusaurus v3
|
|
|
|
### Documentation Service
|
|
```bash
|
|
cd docs
|
|
npm install # Install dependencies
|
|
npm run start # Start dev server (usually port 3001)
|
|
```
|
|
- Auto-reloads on documentation changes
|
|
- Access at: http://localhost:3001/
|
|
- Documentation source: `docs/`
|
|
|
|
---
|
|
|
|
## 2. Documentation Structure
|
|
|
|
### Directory Layout
|
|
```
|
|
docs/
|
|
├── docs/ # Main documentation content
|
|
│ ├── agents/ # Agent and MCP guides
|
|
│ ├── get-started/ # Getting started guides
|
|
│ ├── tutorials/ # Langflow tutorials
|
|
│ ├── components/ # Component documentation
|
|
│ ├── flows/ # Guides to build, run, and test flows
|
|
│ ├── deployment/ # Guides for deploying and hosting a Langflow server
|
|
│ ├── develop/ # Guides for developing apps with Langflow
|
|
│ ├── support/ # Help and release notes
|
|
│ ├── contributing/ # Contribution guidelines
|
|
│ └── api-reference/ # API documentation
|
|
├── src/ # Custom React components
|
|
├── static/ # Static assets (images, etc.)
|
|
├── sidebars.js # Sidebar configuration
|
|
├── docusaurus.config.js # Main configuration
|
|
└── package.json # Dependencies
|
|
```
|
|
|
|
### Content Types
|
|
- **Guides:** Step-by-step tutorials (`docs/getting-started/`)
|
|
- **Reference:** API and component reference (`docs/api-reference/`)
|
|
- **How-to:** Problem-solving articles (`docs/components/`)
|
|
- **Concepts:** Explanatory articles about Langflow concepts
|
|
- **Blog:** Release notes, announcements (`blog/`)
|
|
|
|
---
|
|
|
|
## 3. Writing Documentation
|
|
|
|
### Markdown Conventions
|
|
```markdown
|
|
---
|
|
title: Page Title
|
|
description: Brief description for SEO
|
|
sidebar_position: 1
|
|
---
|
|
|
|
# Page Title
|
|
|
|
Brief introduction paragraph.
|
|
|
|
## Section Header
|
|
|
|
Content with proper formatting.
|
|
|
|
### Subsection
|
|
|
|
More detailed content.
|
|
|
|
:::tip
|
|
Use admonitions for important information.
|
|
:::
|
|
|
|
:::warning
|
|
Use warnings for potential issues.
|
|
:::
|
|
|
|
:::danger
|
|
Use danger for critical warnings.
|
|
:::
|
|
```
|
|
|
|
### Code Blocks
|
|
````markdown
|
|
```python title="component_example.py"
|
|
from langflow.components.base import Component
|
|
|
|
class MyComponent(Component):
|
|
display_name = "My Component"
|
|
description = "Example component"
|
|
|
|
def run(self):
|
|
return "Hello, World!"
|
|
```
|
|
````
|
|
|
|
### Images and Assets
|
|
```markdown
|
|
<!-- Images go in static/img/ -->
|
|
|
|
|
|
<!-- Use descriptive alt text -->
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Component Documentation
|
|
|
|
### Component Page Template
|
|
```markdown
|
|
---
|
|
title: Component Name
|
|
description: Brief description of what the component does
|
|
sidebar_position: 1
|
|
---
|
|
|
|
# Component Name
|
|
|
|
Brief overview of the component's purpose.
|
|
|
|
## Overview
|
|
|
|
What this component does and when to use it.
|
|
|
|
## Configuration
|
|
|
|
### Inputs
|
|
|
|
| Input | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `input_text` | String | Yes | The text to process |
|
|
| `model_name` | String | No | Model to use (default: gpt-3.5-turbo) |
|
|
|
|
### Outputs
|
|
|
|
| Output | Type | Description |
|
|
|--------|------|-------------|
|
|
| `result` | Message | Processed result |
|
|
|
|
## Usage Example
|
|
|
|
```python
|
|
# Example of using the component
|
|
component = MyComponent(
|
|
input_text="Hello, world!",
|
|
model_name="gpt-4"
|
|
)
|
|
result = component.run()
|
|
```
|
|
|
|
## Common Issues
|
|
|
|
### Issue: Component not loading
|
|
|
|
**Solution:** Check that all required inputs are provided.
|
|
|
|
### Issue: API key errors
|
|
|
|
**Solution:** Ensure your API key is properly configured.
|
|
```
|
|
|
|
### API Documentation
|
|
```markdown
|
|
---
|
|
title: API Endpoint
|
|
description: REST API endpoint documentation
|
|
---
|
|
|
|
# API Endpoint Name
|
|
|
|
## Endpoint
|
|
|
|
`POST /api/v1/endpoint`
|
|
|
|
## Request
|
|
|
|
### Headers
|
|
```json
|
|
{
|
|
"Authorization": "Bearer <token>",
|
|
"Content-Type": "application/json"
|
|
}
|
|
```
|
|
|
|
### Body
|
|
```json
|
|
{
|
|
"parameter": "value",
|
|
"optional_param": "optional_value"
|
|
}
|
|
```
|
|
|
|
## Response
|
|
|
|
### Success (200)
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"result": "success"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Error (400)
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Error message"
|
|
}
|
|
```
|
|
|
|
## Example
|
|
|
|
```bash
|
|
curl -X POST http://localhost:7860/api/v1/endpoint \
|
|
-H "Authorization: Bearer your-token" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"parameter": "value"}'
|
|
```
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Blog Posts and Announcements
|
|
|
|
### Blog Post Template
|
|
```markdown
|
|
---
|
|
title: "Release: Langflow v1.1.0"
|
|
description: "New features and improvements in Langflow v1.1.0"
|
|
authors: [author-name]
|
|
date: 2024-01-15
|
|
tags: [release, features]
|
|
---
|
|
|
|
# Release: Langflow v1.1.0
|
|
|
|
Brief introduction to the release.
|
|
|
|
## New Features
|
|
|
|
### Feature 1
|
|
Description of the feature and how to use it.
|
|
|
|
### Feature 2
|
|
Another feature description.
|
|
|
|
## Improvements
|
|
|
|
- List of improvements
|
|
- Bug fixes
|
|
- Performance enhancements
|
|
|
|
## Breaking Changes
|
|
|
|
:::warning
|
|
List any breaking changes that require user action.
|
|
:::
|
|
|
|
## Migration Guide
|
|
|
|
Steps to migrate from previous versions.
|
|
```
|
|
|
|
### Announcement Posts
|
|
```markdown
|
|
---
|
|
title: "Announcement: New Integration"
|
|
description: "Langflow now supports integration with XYZ service"
|
|
authors: [author-name]
|
|
date: 2024-01-15
|
|
tags: [announcement, integration]
|
|
---
|
|
|
|
Brief announcement content with clear call-to-action.
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Configuration
|
|
|
|
### Sidebar Configuration (`sidebars.js`)
|
|
```javascript
|
|
module.exports = {
|
|
docs: [
|
|
'introduction',
|
|
{
|
|
type: 'category',
|
|
label: 'Getting Started',
|
|
items: [
|
|
'getting-started/installation',
|
|
'getting-started/quickstart',
|
|
'getting-started/first-flow',
|
|
],
|
|
},
|
|
{
|
|
type: 'category',
|
|
label: 'Components',
|
|
items: [
|
|
'components/overview',
|
|
'components/inputs',
|
|
'components/outputs',
|
|
'components/processing',
|
|
],
|
|
},
|
|
],
|
|
};
|
|
```
|
|
|
|
### Site Configuration (`docusaurus.config.js`)
|
|
```javascript
|
|
module.exports = {
|
|
title: 'Langflow Documentation',
|
|
tagline: 'Build AI flows visually',
|
|
url: 'https://docs.langflow.org',
|
|
baseUrl: '/',
|
|
|
|
themeConfig: {
|
|
navbar: {
|
|
title: 'Langflow',
|
|
logo: {
|
|
alt: 'Langflow Logo',
|
|
src: 'img/logo.svg',
|
|
},
|
|
items: [
|
|
{
|
|
type: 'doc',
|
|
docId: 'introduction',
|
|
position: 'left',
|
|
label: 'Docs',
|
|
},
|
|
{
|
|
to: '/blog',
|
|
label: 'Blog',
|
|
position: 'left'
|
|
},
|
|
],
|
|
},
|
|
},
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Documentation Testing
|
|
|
|
### Link Checking
|
|
```bash
|
|
# Check for broken internal links
|
|
npm run build
|
|
npm run serve
|
|
# Manual testing or use link checker tools
|
|
```
|
|
|
|
### Content Review
|
|
- **Accuracy:** Verify all code examples work
|
|
- **Completeness:** Ensure all features are documented
|
|
- **Clarity:** Review for clear, concise language
|
|
- **Navigation:** Test sidebar and cross-references
|
|
|
|
### Screenshots
|
|
- Keep screenshots up-to-date with current UI
|
|
- Use consistent browser/OS for screenshots
|
|
- Highlight relevant UI elements
|
|
- Use descriptive file names
|
|
|
|
---
|
|
|
|
## 8. Style Guide
|
|
|
|
### Writing Style
|
|
- **Tone:** Professional but approachable
|
|
- **Voice:** Second person ("you") for instructions
|
|
- **Tense:** Present tense for current features
|
|
- **Length:** Keep paragraphs short and scannable
|
|
|
|
### Formatting
|
|
- **Headers:** Use sentence case
|
|
- **Code:** Inline code with `backticks`
|
|
- **Emphasis:** Use **bold** for UI elements, *italic* for emphasis
|
|
- **Lists:** Use parallel structure
|
|
|
|
### Terminology
|
|
- **Langflow:** Always capitalize
|
|
- **Component:** Capitalize when referring to Langflow components
|
|
- **Flow:** Capitalize when referring to Langflow flows
|
|
- **API:** Always uppercase
|
|
- **JSON:** Always uppercase
|
|
|
|
---
|
|
|
|
## 9. Deployment
|
|
|
|
### Local Testing
|
|
```bash
|
|
npm run build # Build static site
|
|
npm run serve # Serve built site locally
|
|
```
|
|
|
|
### Production Deployment
|
|
- Documentation is automatically deployed on commit to main branch
|
|
- Build artifacts go to `build/` directory
|
|
- Static site is served via CDN
|
|
|
|
---
|
|
|
|
## Documentation Development Checklist
|
|
- [ ] Documentation service running with `npm run start`
|
|
- [ ] Content follows markdown conventions
|
|
- [ ] Code examples are tested and working
|
|
- [ ] Images have descriptive alt text
|
|
- [ ] Internal links are functional
|
|
- [ ] Sidebar navigation is updated
|
|
- [ ] Content follows style guide
|
|
- [ ] Screenshots are current and properly formatted
|
|
- [ ] Cross-references between related topics
|
|
- [ ] Build succeeds with `npm run build`
|