jesus/kogral
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
kogral/docs/README.md
Jesús Pérez 22e9473e69
chore: add docs
2026-01-23 16:11:07 +00:00

7.9 KiB
Raw Blame History

KOGRAL Documentation

KoGraL Logo

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:

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

🤝 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.