Merge pull request #2 from intuit/oss-updates

Jekyll theme to just-the-docs & 'Why Infigraph' section

Author: sandeep-mewara

.github/workflows/pages.yml

@@ -52,6 +52,7 @@ jobs:
             echo "---"
             echo "layout: default"
             echo "title: $(extract_title ARCHITECTURE.md)"
+            echo "nav_order: 3"
             echo "---"
             echo ""
             cat ARCHITECTURE.md
@@ -62,6 +63,7 @@ jobs:
             echo "---"
             echo "layout: default"
             echo "title: $(extract_title CONTRIBUTING.md)"
+            echo "nav_order: 4"
             echo "---"
             echo ""
             cat CONTRIBUTING.md
@@ -72,6 +74,7 @@ jobs:
             echo "---"
             echo "layout: default"
             echo "title: Getting Started"
+            echo "nav_order: 2"
             echo "---"
             echo ""
             echo "# Getting Started with Infigraph"

README.md

@@ -16,6 +16,41 @@ AI agents are **structurally blind** to your codebase. When they need to answer
 
 **The cost:** 60–80% of AI agent tokens spent on code rediscovery instead of solving your problem.
 
+## Why Infigraph (What Makes It Unique)
+
+The market has two categories of solutions — neither solves this:
+
+**Cloud-based tools** (GitHub Copilot, Sourcegraph, Codeium, Tabnine):
+- ❌ Require sending your code to external APIs
+- ❌ Expensive per-query (token costs compound)
+- ❌ Latency-bound by network round-trips
+- ❌ Privacy concerns for proprietary code
+- ✅ Good AI integration
+
+**Local analysis tools** (ctags, Language Servers, ripgrep, CodeQL):
+- ✅ Run locally, offline-capable
+- ✅ No privacy/security concerns
+- ❌ No persistent knowledge graph
+- ❌ Limited language support (1-3 languages)
+- ❌ Not designed for AI agents
+- ❌ Scattered results, high token overhead for agents
+
+**The gap Infigraph fills:**
+| Feature | Cloud Tools | Local Tools | Infigraph |
+|---------|-------------|------------|-----------|
+| **Local-first operation** | ❌ | ✅ | ✅ |
+| **Persistent knowledge graph** | ❌ | ❌ | ✅ |
+| **62 language support** | ❌ | ❌ | ✅ |
+| **AI agent integration** (MCP) | Limited | ❌ | ✅ |
+| **Offline operation** | ❌ | ✅ | ✅ |
+| **No external APIs** | ❌ | ✅ | ✅ |
+| **Cypher queries on code** | ❌ | ❌ | ✅ |
+| **Cross-file resolution** | ❌ | Limited | ✅ |
+
+**No other product or OSS combines all of these.** Infigraph is the first AI-native, local-first knowledge graph engine for code.
+
+---
+
 ## The Solution
 
 Infigraph builds a **persistent knowledge graph** of your codebase before the agent runs. Structural questions that would cost hundreds of tokens to answer with raw file reads now resolve in milliseconds:
@@ -39,14 +74,17 @@ Examples:
 
 ## Table of Contents
 
+- [The Problem](#the-problem) — What Infigraph solves
+- [Why Infigraph](#why-infigraph-what-makes-it-unique) — Unique market position
+- [The Solution](#the-solution) — How it works
 - [Key Highlights](#key-highlights) — Core capabilities at a glance
 - [Quick Start](#quick-start) — Install and run in 2 minutes
 - [How It Works](#how-it-works) — Integration with AI coding agents
 - [Offline-First Design](#offline-first-design) — No APIs, no network calls
 - [Installation](#installation) — Setup for all platforms
 - [Usage Examples](#usage-examples) — CLI commands, Web UI, tasks
 - [Features & Architecture](#features--architecture) — Full capabilities list
-- [Supported Languages](#supported-languages-62) — All 62 languages
+- [Supported Languages (62)](#supported-languages-62) — All 62 languages
 - [Contributing](#contributing) — Build from source, add languages, contribute
 - [License](#license)
 

docs/Gemfile

@@ -1,7 +1,7 @@
 source "https://rubygems.org"
 
 gem "jekyll", "~> 4.3"
-gem "jekyll-theme-minimal"
+gem "just-the-docs"
 gem "jekyll-seo-tag"
 gem "kramdown-parser-gfm"
 gem "rouge"

docs/README.md

@@ -1,6 +1,6 @@
 # Infigraph Documentation
 
-This directory contains the source for the Infigraph documentation site, built with Jekyll and deployed to GitHub Pages.
+This directory contains the source for the Infigraph documentation site, built with [Just the Docs](https://just-the-docs.github.io/) theme and deployed to GitHub Pages.
 
 ## Local Development
 
@@ -36,46 +36,65 @@ Output goes to `docs/_site/`
 
 ```
 docs/
-├── _config.yml           Jekyll configuration
-├── assets/
-│   └── css/style.scss    Custom stylesheet
-├── index.md              Landing page
-├── getting-started.md    Getting started guide
-├── architecture.md       Architecture & design document
-├── contributing.md       Contributing guidelines
-└── Gemfile              Ruby dependencies
+├── _config.yml              Jekyll configuration (Just the Docs theme)
+├── index.md                 Landing page (nav_order: 1)
+├── getting-started.md       Getting started (auto-generated, nav_order: 2)
+├── architecture.md          Architecture (auto-generated, nav_order: 3)
+├── contributing.md          Contributing (auto-generated, nav_order: 4)
+├── Gemfile                  Ruby dependencies
+└── README.md                This file
 ```
 
+**Auto-generated files** (derived from root sources):
+- `getting-started.md` — Extracted from README.md Quick Start section
+- `architecture.md` — Auto-generated from ARCHITECTURE.md
+- `contributing.md` — Auto-generated from CONTRIBUTING.md
+
+These files are in `.gitignore` and regenerated on every deployment.
+
 ## Adding a New Page
 
 1. Create a new `.md` file in the `docs/` directory
-2. Add YAML frontmatter:
+2. Add YAML frontmatter with nav_order:
    ```yaml
    ---
    layout: default
    title: Page Title
+   nav_order: 5
    ---
    ```
 3. Write content in Markdown
-4. Link from other pages using `[text](/infigraph/page-slug)`
+4. Links use Jekyll's `link` filter: `[text]({% link page.md %})`
 
 ## Deployment
 
-Documentation is automatically deployed to GitHub Pages when changes are pushed to `main` (triggered by updates to `docs/**` files).
+Documentation is automatically deployed to GitHub Pages when changes are pushed to `main`:
+- Triggers on: changes to `docs/**`, `ARCHITECTURE.md`, `CONTRIBUTING.md`, or `.github/workflows/pages.yml`
+- Workflow: `.github/workflows/pages.yml`
+- Site URL: https://intuit.github.io/infigraph/
+
+## Theme Configuration
 
-Site URL: https://intuit.github.io/infigraph/
+Uses [Just the Docs](https://just-the-docs.github.io/) — professional documentation theme with:
+- Sidebar navigation
+- Built-in search
+- Dark/light mode toggle
+- Mobile responsive design
+- Syntax highlighting
 
-## Theme
+To customize:
+- Edit `_config.yml` for site metadata, color scheme, and navigation links
+- Theme styling is built-in; no custom CSS needed
 
-Uses [jekyll-theme-minimal](https://github.com/pages-themes/minimal) with custom styling in `assets/css/style.scss`.
+## Single Source of Truth Pattern
 
-To modify the theme:
-- Edit `_config.yml` for site metadata and navigation
-- Edit `assets/css/style.scss` for styling
-- Modify layouts in `_includes/` or `_layouts/` (copied from theme)
+README.md is the source of truth. Jekyll pages derive from it:
+- Root `README.md` → docs pages via auto-generation
+- No duplication: pages are ephemeral, regenerated on every build
+- Edit root sources; Jekyll updates automatically
 
 ## References
 
+- [Just the Docs Documentation](https://just-the-docs.github.io/)
 - [Jekyll Documentation](https://jekyllrb.com/docs/)
 - [GitHub Pages with Jekyll](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll)
-- [Minimal Theme](https://pages-themes.github.io/minimal/)

docs/_config.yml

@@ -1,24 +1,27 @@
 title: Infigraph
-description: AST-powered code intelligence engine
+description: AST-powered Local-first Code Intelligence Engine
 url: https://intuit.github.io/infigraph
 baseurl: /infigraph
 
-theme: jekyll-theme-minimal
+# Theme: Just the Docs (professional documentation theme)
+theme: just-the-docs
 plugins:
   - jekyll-seo-tag
 
-# Navigation
-nav:
-  - text: Home
-    url: /
-  - text: Getting Started
-    url: /getting-started
-  - text: Architecture
-    url: /architecture
-  - text: Contributing
-    url: /contributing
-  - text: GitHub
-    url: https://github.com/intuit/infigraph
+# Just the Docs configuration
+color_scheme: light
+search_enabled: true
+search_tokenizer_separator: /[\s/]+/
+heading_anchors: true
+
+# Navigation (sidebar)
+aux_links:
+  "GitHub": https://github.com/intuit/infigraph
+  "License": https://github.com/intuit/infigraph/blob/main/LICENSE
+aux_links_new_tab: true
+
+# Footer
+footer_content: "Built with ❤️ by <a href=\"https://intuit.com\">Intuit</a> • <a href=\"https://github.com/intuit/infigraph/blob/main/LICENSE\">Apache 2.0</a>"
 
 # Site metadata
 author:
@@ -31,6 +34,8 @@ repository: intuit/infigraph
 markdown: kramdown
 kramdown:
   syntax_highlighter: rouge
+  input: GFM
+  hard_wrap: false
 
 # Exclude from build
 exclude: