329 lines
7.6 KiB
Markdown
329 lines
7.6 KiB
Markdown
# KOGRAL Web Assets
|
||
|
||
Web-based landing page and static content for KOGRAL.
|
||
|
||
## Directory Structure
|
||
|
||
```text
|
||
assets/web/
|
||
├── src/
|
||
│ ├── index.html # Source HTML (readable)
|
||
│ └── kogral.svg # Logo for landing page
|
||
├── index.html # Minified/Production HTML
|
||
├── kogral.svg # Logo for landing page
|
||
├── minify.sh # Minification script
|
||
└── README.md # This file
|
||
```
|
||
|
||
## Files
|
||
|
||
### `src/index.html` - Source Version
|
||
|
||
- **Purpose**: Development and maintenance
|
||
- **Content**:
|
||
- Full formatting and indentation
|
||
- Inline CSS and JavaScript
|
||
- Bilingual (English/Spanish) content
|
||
- Language-aware dynamic switching
|
||
- Knowledge graph showcase
|
||
- Technology stack display
|
||
- Core components grid
|
||
|
||
**Use for:**
|
||
|
||
- Editing content
|
||
- Understanding structure
|
||
- Version control
|
||
- Making translation updates
|
||
|
||
### `index.html` - Production Version
|
||
|
||
- **Purpose**: Served to browsers (fast loading)
|
||
- **Optimizations**:
|
||
- Removed all comments
|
||
- Compressed CSS (removed spaces, combined rules)
|
||
- Minified JavaScript (single line)
|
||
- Removed whitespace between tags
|
||
- Preserved all functionality
|
||
|
||
**Use for:**
|
||
|
||
- Production web server
|
||
- CDN distribution
|
||
- Browser caching
|
||
- Fast load times
|
||
|
||
### `kogral.svg` - Logo
|
||
|
||
- **Purpose**: Landing page branding
|
||
- **Source**: Copy of `../logos/kogral-h.svg` (horizontal logo)
|
||
- **Dimensions**: 610×200px (viewBox 0 0 610 200)
|
||
- **Features**: Animated knowledge graph nodes, connections, and text
|
||
|
||
## How to Use
|
||
|
||
### Development
|
||
|
||
Edit `src/index.html`:
|
||
|
||
```bash
|
||
# Edit source file
|
||
nano assets/web/src/index.html
|
||
|
||
# Regenerate minified version (see below)
|
||
./assets/web/minify.sh
|
||
```
|
||
|
||
### Update Minified Version
|
||
|
||
When you update `src/index.html`, regenerate `index.html`:
|
||
|
||
```bash
|
||
# Using minify.sh script
|
||
cd /path/to/kogral
|
||
./assets/web/minify.sh
|
||
|
||
# Or manually
|
||
cd /path/to/kogral
|
||
perl -e '
|
||
use strict;
|
||
use warnings;
|
||
|
||
open(my $fh, "<", "assets/web/src/index.html") or die $!;
|
||
my $content = do { local $/; <$fh> };
|
||
close($fh);
|
||
|
||
# Remove comments
|
||
$content =~ s/<!--.*?-->//gs;
|
||
|
||
# Compress whitespace in style tags
|
||
$content =~ s/(<style[^>]*>)(.*?)(<\/style>)/
|
||
my $before = $1;
|
||
my $style = $2;
|
||
my $after = $3;
|
||
$style =~ s{\/\*.*?\*\/}{}gs;
|
||
$style =~ s{\s+}{ }gs;
|
||
$style =~ s{\s*([{}:;,>+~])\s*}{$1}gs;
|
||
$before . $style . $after;
|
||
/gies;
|
||
|
||
# Compress whitespace in script tags
|
||
$content =~ s/(<script[^>]*>)(.*?)(<\/script>)/
|
||
my $before = $1;
|
||
my $script = $2;
|
||
my $after = $3;
|
||
$script =~ s{\/\/.*$}{}gm;
|
||
$script =~ s{\s+}{ }gs;
|
||
$script =~ s{\s*([{}();,])\s*}{$1}gs;
|
||
$before . $script . $after;
|
||
/gies;
|
||
|
||
# Remove whitespace between tags
|
||
$content =~ s/>\s+</></gs;
|
||
$content =~ s/\s+/ /gs;
|
||
$content =~ s/^\s+|\s+$//g;
|
||
|
||
open(my $out, ">", "assets/web/index.html") or die $!;
|
||
print $out $content;
|
||
close($out);
|
||
|
||
print "✅ Minified version created\n";
|
||
'
|
||
```
|
||
|
||
### Deployment
|
||
|
||
Serve `index.html` from your web server:
|
||
|
||
```bash
|
||
# Using Rust
|
||
cargo install static-web-server
|
||
static-web-server -d assets/web/
|
||
|
||
# Using Python
|
||
python3 -m http.server --directory assets/web
|
||
|
||
# Using Node.js
|
||
npx http-server assets/web
|
||
|
||
# Using nginx
|
||
# Point root to assets/web/
|
||
# Serve index.html as default
|
||
```
|
||
|
||
## Features
|
||
|
||
### Responsive Design
|
||
|
||
- Mobile-first approach
|
||
- Flexbox and Grid layouts
|
||
- Media queries for mobile
|
||
- Touch-friendly navigation
|
||
|
||
### Performance
|
||
|
||
- Inline CSS (no separate requests)
|
||
- Inline JavaScript (no blocking external scripts)
|
||
- Minimal dependencies (no frameworks)
|
||
- Optimized minified size
|
||
|
||
### Bilingual
|
||
|
||
- English and Spanish
|
||
- LocalStorage persistence
|
||
- Data attributes for translations
|
||
- Dynamic language switching
|
||
|
||
### Modern CSS
|
||
|
||
- CSS Gradients
|
||
- Animations (fadeInUp)
|
||
- Hover effects
|
||
- Grid and Flexbox layouts
|
||
|
||
### Styling
|
||
|
||
- KOGRAL color scheme (Blue #4a9eff, Green #3dd68d, Gold #fbbf24)
|
||
- Gradient backgrounds
|
||
- Inter font family
|
||
- Smooth transitions
|
||
|
||
## Content Sections
|
||
|
||
1. **Hero** - Title, tagline, logo, version badge
|
||
2. **Problems** - 4 knowledge management problems KOGRAL solves
|
||
- Scattered documentation
|
||
- No version control for decisions
|
||
- Lost context over time
|
||
- Isolated team knowledge
|
||
3. **How It Works** - Feature overview (Markdown-native, Semantic Search, Config-driven, Claude Code)
|
||
4. **Technology Stack** - Tech badges (Rust, Nickel, SurrealDB, fastembed, MCP, Logseq, etc.)
|
||
5. **Core Components** - Component showcase (kogral-core, kogral-cli, kogral-mcp, etc.)
|
||
6. **CTA** - Call-to-action button linking to GitHub
|
||
7. **Footer** - Credits and tagline
|
||
|
||
## Translations
|
||
|
||
All text content is bilingual. Edit data attributes in `src/index.html`:
|
||
|
||
```html
|
||
<!-- English/Spanish example -->
|
||
<span data-en="Knowledge Graphs" data-es="Grafos de Conocimiento">Knowledge Graphs</span>
|
||
```
|
||
|
||
The JavaScript automatically updates based on selected language.
|
||
|
||
## Color Scheme
|
||
|
||
KOGRAL branding colors:
|
||
|
||
- **Primary Blue**: `#4a9eff` - Main brand color
|
||
- **Secondary Green**: `#3dd68d` - Highlights and active states
|
||
- **Gold Accent**: `#fbbf24` - Gradient accents
|
||
- **Slate**: `#64748b` - Secondary text
|
||
- **Dark Background**: `#0a0a14` - Main background
|
||
|
||
## Maintenance
|
||
|
||
- Source edits go in `src/index.html`
|
||
- Regenerate `index.html` when source changes
|
||
- Both files are versioned in git
|
||
- Keep them in sync
|
||
|
||
## Git Workflow
|
||
|
||
```bash
|
||
# Edit source
|
||
nano assets/web/src/index.html
|
||
|
||
# Regenerate minified version
|
||
./assets/web/minify.sh
|
||
|
||
# Commit changes
|
||
git add assets/web/src/index.html
|
||
git add assets/web/index.html
|
||
git commit -m "Update landing page content"
|
||
git push
|
||
```
|
||
|
||
## File Sizes
|
||
|
||
Source and production versions:
|
||
|
||
| File | Type |
|
||
|------|------|
|
||
| `src/index.html` | Source (readable, formatted) |
|
||
| `index.html` | Production (minified, optimized) |
|
||
| `kogral.svg` | ~15KB (animated horizontal logo) |
|
||
|
||
## Version Information
|
||
|
||
- **Last Updated**: 2026-01-23
|
||
- **Version**: 0.1.0
|
||
- **Format**: HTML5 + CSS3 + ES6
|
||
- **Compatibility**: All modern browsers
|
||
- **Languages**: English, Spanish
|
||
|
||
## Technology Focus
|
||
|
||
**KOGRAL** landing page emphasizes:
|
||
|
||
- 📝 Git-native knowledge management
|
||
- 🔍 Semantic search with embeddings
|
||
- ⚙️ Config-driven architecture (Nickel)
|
||
- 🤖 Claude Code integration (MCP)
|
||
- 📊 6 node types, 6 relationships
|
||
- 🗄️ Multi-backend storage (Filesystem, SurrealDB, Memory)
|
||
|
||
## Features Highlighted
|
||
|
||
### 4 Core Problems Solved
|
||
|
||
1. **Scattered Documentation** - Unifies notes, decisions, guidelines across tools
|
||
2. **No Version Control** - Git-tracked ADRs with full history
|
||
3. **Lost Context** - Semantic search and relationship tracking
|
||
4. **Isolated Knowledge** - Multi-graph architecture with inheritance
|
||
|
||
### How It Works
|
||
|
||
1. **Markdown-Native** - YAML frontmatter, wikilinks, code references
|
||
2. **Semantic Search** - Vector embeddings, local or cloud
|
||
3. **Config-Driven** - Nickel schemas, 3 modes (dev/prod/test)
|
||
4. **Claude Code** - MCP server with 7 tools, 6 resources, 2 prompts
|
||
|
||
### Technology Stack
|
||
|
||
- Rust Edition 2021
|
||
- Nickel Config
|
||
- SurrealDB
|
||
- fastembed (local embeddings)
|
||
- rig-core (cloud embeddings)
|
||
- MCP Protocol
|
||
- Logseq Compatible
|
||
- Nushell Scripts
|
||
|
||
### Core Components
|
||
|
||
- **kogral-core** - Core library
|
||
- **kogral-cli** - 13 commands
|
||
- **kogral-mcp** - MCP server
|
||
- **Config System** - Nickel schemas
|
||
- **3 Storage Backends** - Filesystem, SurrealDB, Memory
|
||
- **2 Embedding Providers** - FastEmbed, rig-core
|
||
- **6 Node Types** - Note, Decision, Guideline, Pattern, Journal, Execution
|
||
- **6 Relationships** - relates_to, depends_on, implements, extends, supersedes, explains
|
||
|
||
## Quality Metrics
|
||
|
||
- 3 Rust crates
|
||
- 56 tests passing
|
||
- 15K lines of code
|
||
- 0 unsafe blocks
|
||
- 100% documentation coverage
|
||
- 0 clippy warnings
|
||
|
||
---
|
||
|
||
**Last Updated**: 2026-01-23
|
||
**Version**: 0.1.0 (matches KOGRAL release)
|