505 lines
24 KiB
HTML
505 lines
24 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="rust sidebar-visible" dir="ltr">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>Introduction - KOGRAL Documentation</title>
|
|
|
|
|
|
<!-- Custom HTML head -->
|
|
|
|
<meta name="description" content="Complete documentation for KOGRAL - Git-native knowledge graphs for developer teams">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="theme-color" content="#ffffff">
|
|
|
|
<link rel="icon" href="favicon.svg">
|
|
<link rel="shortcut icon" href="favicon.png">
|
|
<link rel="stylesheet" href="css/variables.css">
|
|
<link rel="stylesheet" href="css/general.css">
|
|
<link rel="stylesheet" href="css/chrome.css">
|
|
<link rel="stylesheet" href="css/print.css" media="print">
|
|
|
|
<!-- Fonts -->
|
|
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
|
<link rel="stylesheet" href="fonts/fonts.css">
|
|
|
|
<!-- Highlight.js Stylesheets -->
|
|
<link rel="stylesheet" id="highlight-css" href="highlight.css">
|
|
<link rel="stylesheet" id="tomorrow-night-css" href="tomorrow-night.css">
|
|
<link rel="stylesheet" id="ayu-highlight-css" href="ayu-highlight.css">
|
|
|
|
<!-- Custom theme stylesheets -->
|
|
|
|
|
|
<!-- Provide site root and default themes to javascript -->
|
|
<script>
|
|
const path_to_root = "";
|
|
const default_light_theme = "rust";
|
|
const default_dark_theme = "navy";
|
|
</script>
|
|
<!-- Start loading toc.js asap -->
|
|
<script src="toc.js"></script>
|
|
</head>
|
|
<body>
|
|
<div id="mdbook-help-container">
|
|
<div id="mdbook-help-popup">
|
|
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
|
<div>
|
|
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
|
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
|
<p>Press <kbd>?</kbd> to show this help</p>
|
|
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="body-container">
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|
<script>
|
|
try {
|
|
let theme = localStorage.getItem('mdbook-theme');
|
|
let sidebar = localStorage.getItem('mdbook-sidebar');
|
|
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|
}
|
|
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|
}
|
|
} catch (e) { }
|
|
</script>
|
|
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|
<script>
|
|
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
|
let theme;
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|
const html = document.documentElement;
|
|
html.classList.remove('rust')
|
|
html.classList.add(theme);
|
|
html.classList.add("js");
|
|
</script>
|
|
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
|
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|
<script>
|
|
let sidebar = null;
|
|
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
|
if (document.body.clientWidth >= 1080) {
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|
sidebar = sidebar || 'visible';
|
|
} else {
|
|
sidebar = 'hidden';
|
|
}
|
|
sidebar_toggle.checked = sidebar === 'visible';
|
|
html.classList.remove('sidebar-visible');
|
|
html.classList.add("sidebar-" + sidebar);
|
|
</script>
|
|
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|
<!-- populated by js -->
|
|
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
|
<noscript>
|
|
<iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
|
|
</noscript>
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
|
<div class="sidebar-resize-indicator"></div>
|
|
</div>
|
|
</nav>
|
|
|
|
<div id="page-wrapper" class="page-wrapper">
|
|
|
|
<div class="page">
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|
<div id="menu-bar" class="menu-bar sticky">
|
|
<div class="left-buttons">
|
|
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|
<i class="fa fa-bars"></i>
|
|
</label>
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|
<i class="fa fa-paint-brush"></i>
|
|
</button>
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|
</ul>
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
|
<i class="fa fa-search"></i>
|
|
</button>
|
|
</div>
|
|
|
|
<h1 class="menu-title">KOGRAL Documentation</h1>
|
|
|
|
<div class="right-buttons">
|
|
<a href="print.html" title="Print this book" aria-label="Print this book">
|
|
<i id="print-button" class="fa fa-print"></i>
|
|
</a>
|
|
<a href="https://github.com/your-org/knowledge-base" title="Git repository" aria-label="Git repository">
|
|
<i id="git-repository-button" class="fa fa-github"></i>
|
|
</a>
|
|
<a href="https://github.com/your-org/knowledge-base/edit/main/docs/./README.md" title="Suggest an edit" aria-label="Suggest an edit">
|
|
<i id="git-edit-button" class="fa fa-edit"></i>
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="search-wrapper" class="hidden">
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|
</form>
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|
<ul id="searchresults">
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|
<script>
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|
});
|
|
</script>
|
|
|
|
<div id="content" class="content">
|
|
<main>
|
|
<h1 id="kogral-documentation"><a class="header" href="#kogral-documentation">KOGRAL Documentation</a></h1>
|
|
<p>Welcome to the KOGRAL documentation! This directory contains comprehensive documentation for KOGRAL (<strong>KO</strong>wledge <strong>GRA</strong>phs, <strong>L</strong>ocal-first), built with <a href="https://rust-lang.github.io/mdBook/">mdBook</a>.</p>
|
|
<h2 id="-reading-the-documentation"><a class="header" href="#-reading-the-documentation">📚 Reading the Documentation</a></h2>
|
|
<p>You have several options for reading the documentation:</p>
|
|
<h3 id="option-1-serve-locally-with-mdbook-recommended"><a class="header" href="#option-1-serve-locally-with-mdbook-recommended">Option 1: Serve Locally with mdBook (Recommended)</a></h3>
|
|
<p>The best reading experience with navigation, search, and live reload:</p>
|
|
<pre><code class="language-bash"># Serve documentation at http://localhost:3000
|
|
just docs::serve
|
|
</code></pre>
|
|
<p>This will:</p>
|
|
<ul>
|
|
<li>Build the mdBook</li>
|
|
<li>Start a local web server on port 3000</li>
|
|
<li>Open your browser automatically</li>
|
|
<li>Watch for changes and auto-reload</li>
|
|
</ul>
|
|
<h3 id="option-2-build-static-html"><a class="header" href="#option-2-build-static-html">Option 2: Build Static HTML</a></h3>
|
|
<p>Generate static HTML files you can browse offline:</p>
|
|
<pre><code class="language-bash"># Build mdBook to docs/book/
|
|
just docs::build
|
|
</code></pre>
|
|
<p>Then open <code>docs/book/index.html</code> in your browser.</p>
|
|
<h3 id="option-3-read-markdown-files-directly"><a class="header" href="#option-3-read-markdown-files-directly">Option 3: Read Markdown Files Directly</a></h3>
|
|
<p>All documentation is written in Markdown and can be read directly:</p>
|
|
<ul>
|
|
<li>Browse via GitHub/GitLab web interface</li>
|
|
<li>Use your editor's Markdown preview</li>
|
|
<li>Read from terminal with <code>bat</code>, <code>glow</code>, or similar tools</li>
|
|
</ul>
|
|
<p><strong>Navigation</strong>: See <a href="SUMMARY.html">SUMMARY.md</a> for the complete table of contents.</p>
|
|
<h2 id="-documentation-commands"><a class="header" href="#-documentation-commands">🛠️ Documentation Commands</a></h2>
|
|
<p>We use <code>just</code> recipes for documentation tasks. All commands assume you're in the project root directory.</p>
|
|
<h3 id="build-and-serve"><a class="header" href="#build-and-serve">Build and Serve</a></h3>
|
|
<pre><code class="language-bash"># Serve documentation locally (recommended)
|
|
just docs::serve
|
|
|
|
# Build static HTML
|
|
just docs::build
|
|
|
|
# Watch and rebuild on file changes
|
|
just docs::watch
|
|
</code></pre>
|
|
<h3 id="validation"><a class="header" href="#validation">Validation</a></h3>
|
|
<pre><code class="language-bash"># Test code examples in documentation
|
|
just docs::test
|
|
|
|
# Check for broken links
|
|
just docs::check-links
|
|
</code></pre>
|
|
<h3 id="cleanup"><a class="header" href="#cleanup">Cleanup</a></h3>
|
|
<pre><code class="language-bash"># Remove build artifacts
|
|
just docs::clean
|
|
</code></pre>
|
|
<h3 id="view-all-documentation-commands"><a class="header" href="#view-all-documentation-commands">View All Documentation Commands</a></h3>
|
|
<pre><code class="language-bash">just docs::help
|
|
</code></pre>
|
|
<h2 id="-installing-mdbook"><a class="header" href="#-installing-mdbook">📦 Installing mdBook</a></h2>
|
|
<p>mdBook is required to build and serve the documentation.</p>
|
|
<h3 id="install-via-cargo"><a class="header" href="#install-via-cargo">Install via Cargo</a></h3>
|
|
<pre><code class="language-bash">cargo install mdbook
|
|
</code></pre>
|
|
<h3 id="install-optional-tools"><a class="header" href="#install-optional-tools">Install Optional Tools</a></h3>
|
|
<p>For enhanced functionality:</p>
|
|
<pre><code class="language-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
|
|
</code></pre>
|
|
<h3 id="verify-installation"><a class="header" href="#verify-installation">Verify Installation</a></h3>
|
|
<pre><code class="language-bash">mdbook --version
|
|
# Should output: mdbook v0.4.x or later
|
|
</code></pre>
|
|
<h2 id="-documentation-structure"><a class="header" href="#-documentation-structure">📖 Documentation Structure</a></h2>
|
|
<p>The documentation is organized into the following sections:</p>
|
|
<h3 id="1-kogral-definition-kogral"><a class="header" href="#1-kogral-definition-kogral">1. <strong>KOGRAL Definition</strong> (<code>kogral/</code>)</a></h3>
|
|
<ul>
|
|
<li>What is KOGRAL and why it exists</li>
|
|
<li>Core concepts (nodes, edges, graphs)</li>
|
|
<li>Design philosophy</li>
|
|
</ul>
|
|
<h3 id="2-guides-guides"><a class="header" href="#2-guides-guides">2. <strong>Guides</strong> (<code>guides/</code>)</a></h3>
|
|
<ul>
|
|
<li>Quick start (5 minutes)</li>
|
|
<li>Installation guide</li>
|
|
<li>Use cases with examples</li>
|
|
</ul>
|
|
<h3 id="3-architecture-architecture"><a class="header" href="#3-architecture-architecture">3. <strong>Architecture</strong> (<code>architecture/</code>)</a></h3>
|
|
<ul>
|
|
<li>System overview with diagrams</li>
|
|
<li>Config-driven architecture</li>
|
|
<li>Graph model details</li>
|
|
<li>ADRs (Architectural Decision Records)</li>
|
|
</ul>
|
|
<h3 id="4-setup-setup"><a class="header" href="#4-setup-setup">4. <strong>Setup</strong> (<code>setup/</code>)</a></h3>
|
|
<ul>
|
|
<li>Initial setup</li>
|
|
<li>Development environment</li>
|
|
<li>Production deployment</li>
|
|
<li>Testing environment</li>
|
|
<li>CI/CD integration</li>
|
|
</ul>
|
|
<h3 id="5-configuration-config"><a class="header" href="#5-configuration-config">5. <strong>Configuration</strong> (<code>config/</code>)</a></h3>
|
|
<ul>
|
|
<li>Configuration overview</li>
|
|
<li>Nickel schema reference</li>
|
|
<li>Runtime configuration</li>
|
|
<li>Environment modes (dev/prod/test)</li>
|
|
</ul>
|
|
<h3 id="6-storage-storage"><a class="header" href="#6-storage-storage">6. <strong>Storage</strong> (<code>storage/</code>)</a></h3>
|
|
<ul>
|
|
<li>Storage architecture (hybrid strategy)</li>
|
|
<li>Filesystem backend</li>
|
|
<li>SurrealDB backend</li>
|
|
<li>In-memory backend</li>
|
|
<li>Sync mechanism</li>
|
|
</ul>
|
|
<h3 id="7-ai--embeddings-ai"><a class="header" href="#7-ai--embeddings-ai">7. <strong>AI & Embeddings</strong> (<code>ai/</code>)</a></h3>
|
|
<ul>
|
|
<li>Semantic search</li>
|
|
<li>Embedding providers</li>
|
|
<li>Provider comparison</li>
|
|
<li>Configuration examples</li>
|
|
</ul>
|
|
<h3 id="8-templates-templates"><a class="header" href="#8-templates-templates">8. <strong>Templates</strong> (<code>templates/</code>)</a></h3>
|
|
<ul>
|
|
<li>Template system (Tera)</li>
|
|
<li>Document templates</li>
|
|
<li>Export templates</li>
|
|
<li>Custom templates</li>
|
|
</ul>
|
|
<h3 id="9-cli-reference-cli"><a class="header" href="#9-cli-reference-cli">9. <strong>CLI Reference</strong> (<code>cli/</code>)</a></h3>
|
|
<ul>
|
|
<li>All kb-cli commands</li>
|
|
<li>Common workflows</li>
|
|
<li>Advanced usage</li>
|
|
<li>Troubleshooting</li>
|
|
</ul>
|
|
<h3 id="10-apps--integrations-apps"><a class="header" href="#10-apps--integrations-apps">10. <strong>Apps & Integrations</strong> (<code>apps/</code>)</a></h3>
|
|
<ul>
|
|
<li>MCP quick guide (Claude Code)</li>
|
|
<li>Logseq integration</li>
|
|
<li>Vapora integration</li>
|
|
</ul>
|
|
<h3 id="11-api-reference-api"><a class="header" href="#11-api-reference-api">11. <strong>API Reference</strong> (<code>api/</code>)</a></h3>
|
|
<ul>
|
|
<li>MCP tools specification</li>
|
|
<li>Storage trait</li>
|
|
<li>Embedding trait</li>
|
|
<li>REST API (future)</li>
|
|
</ul>
|
|
<h3 id="12-contributing-contributing"><a class="header" href="#12-contributing-contributing">12. <strong>Contributing</strong> (<code>contributing/</code>)</a></h3>
|
|
<ul>
|
|
<li>Development setup</li>
|
|
<li>Code guidelines</li>
|
|
<li>Testing standards</li>
|
|
<li>Documentation guidelines</li>
|
|
</ul>
|
|
<h2 id="-visual-diagrams"><a class="header" href="#-visual-diagrams">🎨 Visual Diagrams</a></h2>
|
|
<p>The documentation includes SVG diagrams for visual understanding:</p>
|
|
<ul>
|
|
<li><strong><a href="diagrams/architecture-overview.svg">architecture-overview.svg</a></strong> - Complete system architecture</li>
|
|
<li><strong><a href="diagrams/core-concepts.svg">core-concepts.svg</a></strong> - Node types and relationships</li>
|
|
<li><strong><a href="diagrams/config-composition.svg">config-composition.svg</a></strong> - Configuration flow (Nickel → JSON → Rust)</li>
|
|
<li><strong><a href="diagrams/storage-architecture.svg">storage-architecture.svg</a></strong> - Hybrid storage strategy</li>
|
|
</ul>
|
|
<p>These diagrams are embedded in relevant documentation pages and can be viewed standalone in a browser.</p>
|
|
<h2 id="-searching-the-documentation"><a class="header" href="#-searching-the-documentation">🔍 Searching the Documentation</a></h2>
|
|
<p>When using <code>just docs::serve</code>, you get a built-in search feature:</p>
|
|
<ol>
|
|
<li>Click the search icon (🔍) in the top-left corner</li>
|
|
<li>Type your query</li>
|
|
<li>Press Enter to navigate results</li>
|
|
</ol>
|
|
<p>The search indexes all documentation content including:</p>
|
|
<ul>
|
|
<li>Page titles</li>
|
|
<li>Headers</li>
|
|
<li>Body text</li>
|
|
<li>Code examples (optionally)</li>
|
|
</ul>
|
|
<h2 id="-editing-documentation"><a class="header" href="#-editing-documentation">✏️ Editing Documentation</a></h2>
|
|
<h3 id="file-format"><a class="header" href="#file-format">File Format</a></h3>
|
|
<p>All documentation is written in <strong>GitHub Flavored Markdown</strong> with mdBook extensions.</p>
|
|
<p>See <a href="contributing/documentation.html">contributing/documentation.md</a> for detailed editing guidelines.</p>
|
|
<h3 id="adding-a-new-page"><a class="header" href="#adding-a-new-page">Adding a New Page</a></h3>
|
|
<ol>
|
|
<li>Create the markdown file in the appropriate directory</li>
|
|
<li>Add it to <code>SUMMARY.md</code> for navigation</li>
|
|
<li>Build to verify: <code>just docs::build</code></li>
|
|
</ol>
|
|
<h3 id="adding-a-new-section"><a class="header" href="#adding-a-new-section">Adding a New Section</a></h3>
|
|
<ol>
|
|
<li>Create the directory</li>
|
|
<li>Add a <code>README.md</code> for the section landing page</li>
|
|
<li>Add section to <code>SUMMARY.md</code></li>
|
|
</ol>
|
|
<h2 id="-testing-documentation"><a class="header" href="#-testing-documentation">🧪 Testing Documentation</a></h2>
|
|
<h3 id="test-code-examples"><a class="header" href="#test-code-examples">Test Code Examples</a></h3>
|
|
<pre><code class="language-bash">just docs::test
|
|
</code></pre>
|
|
<p>This runs all Rust code examples in the documentation to ensure they compile.</p>
|
|
<h3 id="check-links"><a class="header" href="#check-links">Check Links</a></h3>
|
|
<pre><code class="language-bash">just docs::check-links
|
|
</code></pre>
|
|
<p>This validates all internal and external links.</p>
|
|
<h2 id="-documentation-standards"><a class="header" href="#-documentation-standards">📝 Documentation Standards</a></h2>
|
|
<p>When contributing to documentation:</p>
|
|
<ol>
|
|
<li><strong>Use clear, concise language</strong> - Write for developers and AI agents</li>
|
|
<li><strong>Include code examples</strong> - Show, don't just tell</li>
|
|
<li><strong>Add diagrams where helpful</strong> - Visual aids improve understanding</li>
|
|
<li><strong>Link related concepts</strong> - Help readers discover related content</li>
|
|
<li><strong>Test code examples</strong> - Ensure code compiles and works</li>
|
|
<li><strong>Use consistent formatting</strong> - Follow existing page structure</li>
|
|
<li><strong>Update SUMMARY.md</strong> - New pages must be in navigation</li>
|
|
<li><strong>Run checks before committing</strong>:</li>
|
|
</ol>
|
|
<pre><code class="language-bash">just docs::build
|
|
just docs::test
|
|
just docs::check-links
|
|
</code></pre>
|
|
<h2 id="-tips"><a class="header" href="#-tips">💡 Tips</a></h2>
|
|
<h3 id="live-reload-while-writing"><a class="header" href="#live-reload-while-writing">Live Reload While Writing</a></h3>
|
|
<pre><code class="language-bash">just docs::watch
|
|
</code></pre>
|
|
<p>This watches for changes and rebuilds automatically. Open http://localhost:3000 in your browser to see updates in real-time.</p>
|
|
<h3 id="markdown-preview-in-editor"><a class="header" href="#markdown-preview-in-editor">Markdown Preview in Editor</a></h3>
|
|
<p>Most editors have Markdown preview:</p>
|
|
<ul>
|
|
<li><strong>VS Code</strong>: <code>Ctrl+Shift+V</code> (Cmd+Shift+V on Mac)</li>
|
|
<li><strong>IntelliJ/CLion</strong>: Preview pane (right side)</li>
|
|
<li><strong>Vim/Neovim</strong>: Use plugins like <code>markdown-preview.nvim</code></li>
|
|
</ul>
|
|
<h3 id="quick-reference"><a class="header" href="#quick-reference">Quick Reference</a></h3>
|
|
<ul>
|
|
<li><strong>SUMMARY.md</strong> - Table of contents (edit to add/remove pages)</li>
|
|
<li><strong>book.toml</strong> - mdBook configuration</li>
|
|
<li><strong>theme/</strong> - Custom CSS/JS (if needed)</li>
|
|
<li><strong>diagrams/</strong> - SVG diagrams</li>
|
|
</ul>
|
|
<h2 id="-troubleshooting"><a class="header" href="#-troubleshooting">🐛 Troubleshooting</a></h2>
|
|
<h3 id="mdbook-command-not-found"><a class="header" href="#mdbook-command-not-found">mdbook command not found</a></h3>
|
|
<pre><code class="language-bash"># Install mdBook
|
|
cargo install mdbook
|
|
|
|
# Verify installation
|
|
mdbook --version
|
|
</code></pre>
|
|
<h3 id="port-3000-already-in-use"><a class="header" href="#port-3000-already-in-use">Port 3000 already in use</a></h3>
|
|
<pre><code class="language-bash"># Serve on different port
|
|
cd docs
|
|
mdbook serve --port 3001
|
|
</code></pre>
|
|
<h3 id="links-broken-after-moving-files"><a class="header" href="#links-broken-after-moving-files">Links broken after moving files</a></h3>
|
|
<pre><code class="language-bash"># Check all links
|
|
just docs::check-links
|
|
|
|
# Update internal links in affected files
|
|
# Then rebuild
|
|
just docs::build
|
|
</code></pre>
|
|
<h2 id="-resources"><a class="header" href="#-resources">📚 Resources</a></h2>
|
|
<ul>
|
|
<li><a href="https://rust-lang.github.io/mdBook/">mdBook User Guide</a></li>
|
|
<li><a href="https://github.github.com/gfm/">GitHub Flavored Markdown Spec</a></li>
|
|
<li><a href="https://www.markdownguide.org/">Markdown Guide</a></li>
|
|
</ul>
|
|
<h2 id="-contributing-to-documentation"><a class="header" href="#-contributing-to-documentation">🤝 Contributing to Documentation</a></h2>
|
|
<p>Documentation improvements are always welcome! To contribute:</p>
|
|
<ol>
|
|
<li>Fork the repository</li>
|
|
<li>Create a feature branch</li>
|
|
<li>Make your changes</li>
|
|
<li>Test with <code>just docs::build</code> and <code>just docs::test</code></li>
|
|
<li>Submit a pull request</li>
|
|
</ol>
|
|
<p>See <a href="contributing/documentation.html">contributing/documentation.md</a> for detailed guidelines.</p>
|
|
<hr />
|
|
<p><strong>Happy documenting! 📖</strong></p>
|
|
<p>If you have questions or need help, please open an issue or reach out to the maintainers.</p>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
|
|
<a rel="next prefetch" href="kogral/what-is-kogral.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
|
|
<div style="clear: both"></div>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|
|
|
<a rel="next prefetch" href="kogral/what-is-kogral.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
</nav>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<script>
|
|
window.playground_copyable = true;
|
|
</script>
|
|
|
|
|
|
<script src="elasticlunr.min.js"></script>
|
|
<script src="mark.min.js"></script>
|
|
<script src="searcher.js"></script>
|
|
|
|
<script src="clipboard.min.js"></script>
|
|
<script src="highlight.js"></script>
|
|
<script src="book.js"></script>
|
|
|
|
<!-- Custom JS scripts -->
|
|
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|