kogral/docs

KOGRAL Documentation

Welcome to the KOGRAL documentation! This directory contains comprehensive documentation for KOGRAL (KOwledge GRAphs, Local-first), built with 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:

# 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:

# 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 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

# Serve documentation locally (recommended)
just docs::serve

# Build static HTML
just docs::build

# Watch and rebuild on file changes
just docs::watch

Validation

# Test code examples in documentation
just docs::test

# Check for broken links
just docs::check-links

Cleanup

# Remove build artifacts
just docs::clean

View All Documentation Commands

just docs::help

📦 Installing mdBook

mdBook is required to build and serve the documentation.

Install via Cargo

cargo install mdbook

Install Optional Tools

For enhanced functionality:

# 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

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 - Complete system architecture
• core-concepts.svg - Node types and relationships
• config-composition.svg - Configuration flow (Nickel → JSON → Rust)
• 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 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

just docs::test

This runs all Rust code examples in the documentation to ensure they compile.

Check Links

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:

just docs::build
just docs::test
just docs::check-links

💡 Tips

Live Reload While Writing

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

# Install mdBook
cargo install mdbook

# Verify installation
mdbook --version

Port 3000 already in use

# Serve on different port
cd docs
mdbook serve --port 3001

Links broken after moving files

# Check all links
just docs::check-links

# Update internal links in affected files
# Then rebuild
just docs::build

📚 Resources

• mdBook User Guide
• GitHub Flavored Markdown Spec
• Markdown Guide

🤝 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 for detailed guidelines.

---

Happy documenting! 📖

If you have questions or need help, please open an issue or reach out to the maintainers.