355 lines
7.9 KiB
Markdown
355 lines
7.9 KiB
Markdown
# KOGRAL Documentation
|
|
|
|
<div align="center"> <img src="../assets/kogral-logo.svg" alt="KoGraL Logo" width="600" /> </div>
|
|
|
|
Welcome to the KOGRAL documentation! This directory contains comprehensive documentation for KOGRAL (**KO**wledge **GRA**phs, **L**ocal-first), built with [mdBook](https://rust-lang.github.io/mdBook/).
|
|
|
|
## 📚 Reading the Documentation
|
|
|
|
You have several options for reading the documentation:
|
|
|
|
### Option 1: Serve Locally with mdBook (Recommended)
|
|
|
|
The best reading experience with navigation, search, and live reload:
|
|
|
|
```bash
|
|
# Serve documentation at http://localhost:3000
|
|
just docs::serve
|
|
```
|
|
|
|
This will:
|
|
- Build the mdBook
|
|
- Start a local web server on port 3000
|
|
- Open your browser automatically
|
|
- Watch for changes and auto-reload
|
|
|
|
### Option 2: Build Static HTML
|
|
|
|
Generate static HTML files you can browse offline:
|
|
|
|
```bash
|
|
# Build mdBook to docs/book/
|
|
just docs::build
|
|
```
|
|
|
|
Then open `docs/book/index.html` in your browser.
|
|
|
|
### Option 3: Read Markdown Files Directly
|
|
|
|
All documentation is written in Markdown and can be read directly:
|
|
|
|
- Browse via GitHub/GitLab web interface
|
|
- Use your editor's Markdown preview
|
|
- Read from terminal with `bat`, `glow`, or similar tools
|
|
|
|
**Navigation**: See [SUMMARY.md](SUMMARY.md) for the complete table of contents.
|
|
|
|
## 🛠️ Documentation Commands
|
|
|
|
We use `just` recipes for documentation tasks. All commands assume you're in the project root directory.
|
|
|
|
### Build and Serve
|
|
|
|
```bash
|
|
# Serve documentation locally (recommended)
|
|
just docs::serve
|
|
|
|
# Build static HTML
|
|
just docs::build
|
|
|
|
# Watch and rebuild on file changes
|
|
just docs::watch
|
|
```
|
|
|
|
### Validation
|
|
|
|
```bash
|
|
# Test code examples in documentation
|
|
just docs::test
|
|
|
|
# Check for broken links
|
|
just docs::check-links
|
|
```
|
|
|
|
### Cleanup
|
|
|
|
```bash
|
|
# Remove build artifacts
|
|
just docs::clean
|
|
```
|
|
|
|
### View All Documentation Commands
|
|
|
|
```bash
|
|
just docs::help
|
|
```
|
|
|
|
## 📦 Installing mdBook
|
|
|
|
mdBook is required to build and serve the documentation.
|
|
|
|
### Install via Cargo
|
|
|
|
```bash
|
|
cargo install mdbook
|
|
```
|
|
|
|
### Install Optional Tools
|
|
|
|
For enhanced functionality:
|
|
|
|
```bash
|
|
# Link checker (validates internal/external links)
|
|
cargo install mdbook-linkcheck
|
|
|
|
# Mermaid diagram support
|
|
cargo install mdbook-mermaid
|
|
|
|
# PlantUML diagram support
|
|
cargo install mdbook-plantuml
|
|
```
|
|
|
|
### Verify Installation
|
|
|
|
```bash
|
|
mdbook --version
|
|
# Should output: mdbook v0.4.x or later
|
|
```
|
|
|
|
## 📖 Documentation Structure
|
|
|
|
The documentation is organized into the following sections:
|
|
|
|
### 1. **KOGRAL Definition** (`kogral/`)
|
|
- What is KOGRAL and why it exists
|
|
- Core concepts (nodes, edges, graphs)
|
|
- Design philosophy
|
|
|
|
### 2. **Guides** (`guides/`)
|
|
- Quick start (5 minutes)
|
|
- Installation guide
|
|
- Use cases with examples
|
|
|
|
### 3. **Architecture** (`architecture/`)
|
|
- System overview with diagrams
|
|
- Config-driven architecture
|
|
- Graph model details
|
|
- ADRs (Architectural Decision Records)
|
|
|
|
### 4. **Setup** (`setup/`)
|
|
- Initial setup
|
|
- Development environment
|
|
- Production deployment
|
|
- Testing environment
|
|
- CI/CD integration
|
|
|
|
### 5. **Configuration** (`config/`)
|
|
- Configuration overview
|
|
- Nickel schema reference
|
|
- Runtime configuration
|
|
- Environment modes (dev/prod/test)
|
|
|
|
### 6. **Storage** (`storage/`)
|
|
- Storage architecture (hybrid strategy)
|
|
- Filesystem backend
|
|
- SurrealDB backend
|
|
- In-memory backend
|
|
- Sync mechanism
|
|
|
|
### 7. **AI & Embeddings** (`ai/`)
|
|
- Semantic search
|
|
- Embedding providers
|
|
- Provider comparison
|
|
- Configuration examples
|
|
|
|
### 8. **Templates** (`templates/`)
|
|
- Template system (Tera)
|
|
- Document templates
|
|
- Export templates
|
|
- Custom templates
|
|
|
|
### 9. **CLI Reference** (`cli/`)
|
|
- All kogral-cli commands
|
|
- Common workflows
|
|
- Advanced usage
|
|
- Troubleshooting
|
|
|
|
### 10. **Apps & Integrations** (`apps/`)
|
|
- MCP quick guide (Claude Code)
|
|
- Logseq integration
|
|
- Vapora integration
|
|
|
|
### 11. **API Reference** (`api/`)
|
|
- MCP tools specification
|
|
- Storage trait
|
|
- Embedding trait
|
|
- REST API (future)
|
|
|
|
### 12. **Contributing** (`contributing/`)
|
|
- Development setup
|
|
- Code guidelines
|
|
- Testing standards
|
|
- Documentation guidelines
|
|
|
|
## 🎨 Visual Diagrams
|
|
|
|
The documentation includes SVG diagrams for visual understanding:
|
|
|
|
- **[architecture-overview.svg](diagrams/architecture-overview.svg)** - Complete system architecture
|
|
- **[core-concepts.svg](diagrams/core-concepts.svg)** - Node types and relationships
|
|
- **[config-composition.svg](diagrams/config-composition.svg)** - Configuration flow (Nickel → JSON → Rust)
|
|
- **[storage-architecture.svg](diagrams/storage-architecture.svg)** - Hybrid storage strategy
|
|
|
|
These diagrams are embedded in relevant documentation pages and can be viewed standalone in a browser.
|
|
|
|
## 🔍 Searching the Documentation
|
|
|
|
When using `just docs::serve`, you get a built-in search feature:
|
|
|
|
1. Click the search icon (🔍) in the top-left corner
|
|
2. Type your query
|
|
3. Press Enter to navigate results
|
|
|
|
The search indexes all documentation content including:
|
|
- Page titles
|
|
- Headers
|
|
- Body text
|
|
- Code examples (optionally)
|
|
|
|
## ✏️ Editing Documentation
|
|
|
|
### File Format
|
|
|
|
All documentation is written in **GitHub Flavored Markdown** with mdBook extensions.
|
|
|
|
See [contributing/documentation.md](contributing/documentation.md) for detailed editing guidelines.
|
|
|
|
### Adding a New Page
|
|
|
|
1. Create the markdown file in the appropriate directory
|
|
2. Add it to `SUMMARY.md` for navigation
|
|
3. Build to verify: `just docs::build`
|
|
|
|
### Adding a New Section
|
|
|
|
1. Create the directory
|
|
2. Add a `README.md` for the section landing page
|
|
3. Add section to `SUMMARY.md`
|
|
|
|
## 🧪 Testing Documentation
|
|
|
|
### Test Code Examples
|
|
|
|
```bash
|
|
just docs::test
|
|
```
|
|
|
|
This runs all Rust code examples in the documentation to ensure they compile.
|
|
|
|
### Check Links
|
|
|
|
```bash
|
|
just docs::check-links
|
|
```
|
|
|
|
This validates all internal and external links.
|
|
|
|
## 📝 Documentation Standards
|
|
|
|
When contributing to documentation:
|
|
|
|
1. **Use clear, concise language** - Write for developers and AI agents
|
|
2. **Include code examples** - Show, don't just tell
|
|
3. **Add diagrams where helpful** - Visual aids improve understanding
|
|
4. **Link related concepts** - Help readers discover related content
|
|
5. **Test code examples** - Ensure code compiles and works
|
|
6. **Use consistent formatting** - Follow existing page structure
|
|
7. **Update SUMMARY.md** - New pages must be in navigation
|
|
8. **Run checks before committing**:
|
|
|
|
```bash
|
|
just docs::build
|
|
just docs::test
|
|
just docs::check-links
|
|
```
|
|
|
|
## 💡 Tips
|
|
|
|
### Live Reload While Writing
|
|
|
|
```bash
|
|
just docs::watch
|
|
```
|
|
|
|
This watches for changes and rebuilds automatically. Open <http://localhost:3000> in your browser to see updates in real-time.
|
|
|
|
### Markdown Preview in Editor
|
|
|
|
Most editors have Markdown preview:
|
|
|
|
- **VS Code**: `Ctrl+Shift+V` (Cmd+Shift+V on Mac)
|
|
- **IntelliJ/CLion**: Preview pane (right side)
|
|
- **Vim/Neovim**: Use plugins like `markdown-preview.nvim`
|
|
|
|
### Quick Reference
|
|
|
|
- **SUMMARY.md** - Table of contents (edit to add/remove pages)
|
|
- **book.toml** - mdBook configuration
|
|
- **theme/** - Custom CSS/JS (if needed)
|
|
- **diagrams/** - SVG diagrams
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### mdbook command not found
|
|
|
|
```bash
|
|
# Install mdBook
|
|
cargo install mdbook
|
|
|
|
# Verify installation
|
|
mdbook --version
|
|
```
|
|
|
|
### Port 3000 already in use
|
|
|
|
```bash
|
|
# Serve on different port
|
|
cd docs
|
|
mdbook serve --port 3001
|
|
```
|
|
|
|
### Links broken after moving files
|
|
|
|
```bash
|
|
# Check all links
|
|
just docs::check-links
|
|
|
|
# Update internal links in affected files
|
|
# Then rebuild
|
|
just docs::build
|
|
```
|
|
|
|
## 📚 Resources
|
|
|
|
- [mdBook User Guide](https://rust-lang.github.io/mdBook/)
|
|
- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
|
|
- [Markdown Guide](https://www.markdownguide.org/)
|
|
|
|
## 🤝 Contributing to Documentation
|
|
|
|
Documentation improvements are always welcome! To contribute:
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Test with `just docs::build` and `just docs::test`
|
|
5. Submit a pull request
|
|
|
|
See [contributing/documentation.md](contributing/documentation.md) for detailed guidelines.
|
|
|
|
---
|
|
|
|
**Happy documenting! 📖**
|
|
|
|
If you have questions or need help, please open an issue or reach out to the maintainers.
|