Restructure sidebar for guides (#20)

cybermaggedon · web-flow · commit 388facfb7a03 · 2026-01-12T23:24:23.000Z
diff --git a/_includes/guide/guide-category-section.html b/_includes/guide/guide-category-section.html
@@ -3,7 +3,7 @@
 <h2>{{ include.section_title }}</h2>
 
 <div style="display: flex; flex-wrap: wrap; gap: 10px; margin-top: 10px;">
-{% assign pages_filtered = site.pages | where: "parent", include.parent_page | sort: "guide_category_order" %}
+{% assign pages_filtered = site.pages | sort: "guide_category_order" %}
 {% for guide in pages_filtered %}
 {% if guide.guide_category contains include.category_name %}
 <div style="border: 1px solid {{ include.card_border_color }}; background-color: {{ include.card_bg_color }}; padding: 0; border-radius: 4px; flex: 1 1 200px; overflow: hidden;">
diff --git a/guides/advanced-index.md b/guides/advanced-index.md
@@ -0,0 +1,10 @@
+---
+title: Advanced knowledge management
+parent: How-to Guides
+nav_order: 3
+has_children: true
+---
+
+# Advanced knowledge management
+
+Advanced techniques for structured data processing, custom ontologies, and specialized knowledge extraction.
diff --git a/guides/agents-index.md b/guides/agents-index.md
@@ -0,0 +1,10 @@
+---
+title: Agentic systems
+parent: How-to Guides
+nav_order: 4
+has_children: true
+---
+
+# Agentic systems
+
+Guides for building and deploying agentic workflows, multi-agent systems, and autonomous reasoning applications.
diff --git a/guides/building-index.md b/guides/building-index.md
@@ -0,0 +1,10 @@
+---
+title: Building with TrustGraph
+parent: How-to Guides
+nav_order: 2
+has_children: true
+---
+
+# Building with TrustGraph
+
+Guides for integrating TrustGraph into your applications using Python, TypeScript, command-line tools, and custom processing components.
diff --git a/guides/building/advanced-cli-config.md b/guides/building/advanced-cli-config.md
@@ -1,9 +1,9 @@
 ---
 published: false
 title: Command-line advanced configuration
-nav_order: 2.7
-parent: How-to Guides
-grand_parent: TrustGraph Documentation
+nav_order: 7
+parent: Building with TrustGraph
+grand_parent: How-to Guides
 review_date: 2026-08-01
 guide_category:
   - Building with TrustGraph
diff --git a/guides/building/cli-tools.md b/guides/building/cli-tools.md
@@ -1,8 +1,8 @@
 ---
 title: Introduction to command-line tools
-nav_order: 2.2
-parent: How-to Guides
-grand_parent: TrustGraph Documentation
+nav_order: 2
+parent: Building with TrustGraph
+grand_parent: How-to Guides
 review_date: 2026-08-01
 guide_category:
   - Building with TrustGraph
diff --git a/guides/building/custom-processing.md b/guides/building/custom-processing.md
@@ -1,9 +1,9 @@
 ---
 published: false
 title: Adding your own processing
-nav_order: 2.9
-parent: How-to Guides
-grand_parent: TrustGraph Documentation
+nav_order: 9
+parent: Building with TrustGraph
+grand_parent: How-to Guides
 review_date: 2026-08-01
 guide_category:
   - Building with TrustGraph
diff --git a/guides/building/document-management-cli.md b/guides/building/document-management-cli.md
@@ -1,8 +1,8 @@
 ---
 title: Command-line document management
-nav_order: 2.3
-parent: How-to Guides
-grand_parent: TrustGraph Documentation
+nav_order: 3
+parent: Building with TrustGraph
+grand_parent: How-to Guides
 review_date: 2026-08-01
 guide_category:
   - Building with TrustGraph
diff --git a/guides/building/document-processing-python.md b/guides/building/document-processing-python.md
@@ -1,8 +1,8 @@
 ---
 title: Document processing with Python API
-nav_order: 2.5
-parent: How-to Guides
-grand_parent: TrustGraph Documentation
+nav_order: 5
+parent: Building with TrustGraph
+grand_parent: How-to Guides
 review_date: 2026-08-01
 guide_category:
   - Building with TrustGraph
diff --git a/guides/building/introduction.md b/guides/building/introduction.md
@@ -1,8 +1,8 @@
 ---
 title: Introduction to building with TrustGraph
-nav_order: 2.1
-parent: How-to Guides
-grand_parent: TrustGraph Documentation
+nav_order: 1
+parent: Building with TrustGraph
+grand_parent: How-to Guides
 review_date: 2026-10-01
 guide_category:
   - Building with TrustGraph
diff --git a/guides/building/python-api.md b/guides/building/python-api.md
@@ -1,8 +1,8 @@
 ---
 title: Building with the Python API
-nav_order: 2.4
-parent: How-to Guides
-grand_parent: TrustGraph Documentation
+nav_order: 4
+parent: Building with TrustGraph
+grand_parent: How-to Guides
 review_date: 2026-08-01
 guide_category:
   - Building with TrustGraph
diff --git a/guides/building/react-app.md b/guides/building/react-app.md
@@ -1,8 +1,8 @@
 ---
 title: Building with React and Typescript
-nav_order: 2.8
-parent: How-to Guides
-grand_parent: TrustGraph Documentation
+nav_order: 8
+parent: Building with TrustGraph
+grand_parent: How-to Guides
 review_date: 2026-08-01
 guide_category:
   - Building with TrustGraph
diff --git a/guides/building/typescript-libraries.md b/guides/building/typescript-libraries.md
@@ -1,8 +1,8 @@
 ---
 title: Introduction to the TypeScript libraries
-nav_order: 2.6
-parent: How-to Guides
-grand_parent: TrustGraph Documentation
+nav_order: 6
+parent: Building with TrustGraph
+grand_parent: How-to Guides
 review_date: 2026-08-01
 guide_category:
   - Building with TrustGraph
diff --git a/guides/document-rag/index.md b/guides/document-rag/index.md
@@ -1,8 +1,8 @@
 ---
 title: Document RAG
 nav_order: 4
-parent: How-to Guides
-grand_parent: TrustGraph Documentation
+parent: Common knowledge management tasks
+grand_parent: How-to Guides
 review_date: 2026-08-01
 guide_category:
   - Common knowledge management tasks
@@ -20,6 +20,21 @@ guide_labels:
 
 # Document RAG Guide
 
+{% capture requirements %}
+<ul style="margin: 0; padding-left: 20px;">
+<li>TrustGraph deployed (<a href="../getting-started/quickstart">Quick Start</a>)</li>
+<li>Understanding of <a href="../getting-started/concepts">Core Concepts</a></li>
+</ul>
+{% endcapture %}
+
+{% include guide/guide-intro-box.html
+   description=page.guide_description
+   difficulty=page.guide_difficulty
+   duration=page.guide_time
+   you_will_need=requirements
+   goal="Load documents into TrustGraph, create Document RAG flows, and query using vector similarity search while understanding its limitations."
+%}
+
 **Query documents using vector embeddings and semantic search**
 
 Document RAG (also called "basic RAG", "naive RAG", or simply "RAG") is the
diff --git a/guides/graph-rag/index.md b/guides/graph-rag/index.md
@@ -1,8 +1,8 @@
 ---
 title: Graph RAG
 nav_order: 2
-parent: How-to Guides
-grand_parent: TrustGraph Documentation
+parent: Common knowledge management tasks
+grand_parent: How-to Guides
 review_date: 2026-08-01
 guide_category:
   - Common knowledge management tasks
@@ -20,6 +20,21 @@ guide_labels:
 
 # Graph RAG Guide
 
+{% capture requirements %}
+<ul style="margin: 0; padding-left: 20px;">
+<li>TrustGraph deployed (<a href="../getting-started/quickstart">Quick Start</a>)</li>
+<li>Understanding of <a href="../getting-started/concepts">Core Concepts</a></li>
+</ul>
+{% endcapture %}
+
+{% include guide/guide-intro-box.html
+   description=page.guide_description
+   difficulty=page.guide_difficulty
+   duration=page.guide_time
+   you_will_need=requirements
+   goal="Extract entities and relationships from documents, create Graph RAG flows, and query knowledge graphs using semantic search and graph traversal."
+%}
+
 **Query documents using graph embeddings and knowledge graph relationships**
 
 GraphRAG is a technique which uses automated extraction of relationships
diff --git a/guides/knowledge-graphs/index.md b/guides/knowledge-graphs/index.md
@@ -1,6 +1,7 @@
 ---
 title: Knowledge graph basics
-parent: How-to Guides
+parent: Common knowledge management tasks
+grand_parent: How-to Guides
 nav_order: 1
 review_date: 2026-10-01
 guide_category:
@@ -19,6 +20,20 @@ guide_labels:
 
 # Crash course in knowledge graph concepts
 
+{% capture requirements %}
+<ul style="margin: 0; padding-left: 20px;">
+<li>Basic understanding of data structures</li>
+</ul>
+{% endcapture %}
+
+{% include guide/guide-intro-box.html
+   description=page.guide_description
+   difficulty=page.guide_difficulty
+   duration=page.guide_time
+   you_will_need=requirements
+   goal="Understand knowledge graph fundamentals including triples (subject-predicate-object), RDF, and URI concepts."
+%}
+
 ## Facts
 
 The knowledge graph represents a collection of assertions of facts.
diff --git a/guides/knowledge-index.md b/guides/knowledge-index.md
@@ -0,0 +1,10 @@
+---
+title: Common knowledge management tasks
+parent: How-to Guides
+nav_order: 1
+has_children: true
+---
+
+# Common knowledge management tasks
+
+Guides for working with documents, querying knowledge graphs, and retrieving information using RAG techniques.
diff --git a/guides/mcp-integration/index.md b/guides/mcp-integration/index.md
@@ -1,13 +1,14 @@
 ---
 title: MCP Integration
-parent: How-to Guides
-nav_order: 5
+parent: Agentic systems
+grand_parent: How-to Guides
+nav_order: 1
 review_date: 2026-03-06
 guide_category:
   - Agentic systems
 guide_category_order: 3
 guide_description: Integrate Model Context Protocol servers to extend agent workflows with custom tools
-guide_difficulty: advanced
+guide_difficulty: intermediate
 guide_time: 60 min
 guide_emoji: 🔌
 guide_banner: mcp-integration.jpg
@@ -19,6 +20,23 @@ guide_labels:
 
 # MCP Integration
 
+{% capture requirements %}
+<ul style="margin: 0; padding-left: 20px;">
+<li>TrustGraph deployed (<a href="../../getting-started/installation">Installation Guide</a>)</li>
+<li>TrustGraph 1.1+ (MCP introduced in 1.1)</li>
+<li>Python 3.8+ for MCP server development</li>
+<li>Understanding of agent workflows</li>
+</ul>
+{% endcapture %}
+
+{% include guide/guide-intro-box.html
+   description=page.guide_description
+   difficulty=page.guide_difficulty
+   duration=page.guide_time
+   you_will_need=requirements
+   goal="Create a basic MCP server with custom tools, configure TrustGraph to use MCP services, and enable agents to use MCP tools in workflows."
+%}
+
 Learn how to integrate Model Context Protocol (MCP) servers with TrustGraph to extend your agent workflows with custom tools and capabilities.
 
 This is a feature which began release in TrustGraph 1.1.
diff --git a/guides/monitoring/index.md b/guides/monitoring/index.md
@@ -1,7 +1,8 @@
 ---
 title: Monitoring
-parent: How-to Guides
-nav_order: 6
+parent: Managing operations
+grand_parent: How-to Guides
+nav_order: 1
 review_date: 2026-04-17
 guide_category:
   - Managing operations
diff --git a/guides/ontology-rag/index.md b/guides/ontology-rag/index.md
@@ -1,7 +1,8 @@
 ---
 title: Ontology RAG
 nav_order: 3
-parent: How-to Guides
+parent: Common knowledge management tasks
+grand_parent: How-to Guides
 review_date: 2026-08-01
 guide_category:
   - Common knowledge management tasks
@@ -19,8 +20,23 @@ guide_labels:
 
 # Ontology RAG Guide
 
+{% capture requirements %}
+<ul style="margin: 0; padding-left: 20px;">
+<li>TrustGraph deployed (<a href="../getting-started/quickstart">Quick Start</a>)</li>
+<li>Understanding of <a href="../getting-started/concepts">Core Concepts</a></li>
+<li>Familiarity with ontologies and schemas</li>
+</ul>
+{% endcapture %}
+
+{% include guide/guide-intro-box.html
+   description=page.guide_description
+   difficulty=page.guide_difficulty
+   duration=page.guide_time
+   you_will_need=requirements
+   goal="Import OWL ontologies, extract structured knowledge using schemas, and query ontology-based knowledge graphs."
+%}
+
 **Extract knowledge using language definition**
-**Query documents using graph embeddings and knowledge graph relationships**
 
 Ontology RAG is a technique which uses automated extraction of relationships
 from unstructured text, which is stored in a knowledge graph.
diff --git a/guides/operations-index.md b/guides/operations-index.md
@@ -0,0 +1,10 @@
+---
+title: Managing operations
+parent: How-to Guides
+nav_order: 5
+has_children: true
+---
+
+# Managing operations
+
+Guides for monitoring, maintaining, and operating TrustGraph deployments in production.
diff --git a/guides/structured-processing/index.md b/guides/structured-processing/index.md
@@ -1,6 +1,7 @@
 ---
 title: Structured data processing
-parent: How-to Guides
+parent: Advanced knowledge management
+grand_parent: How-to Guides
 nav_order: 7
 review_date: 2026-02-01
 guide_category:
@@ -19,6 +20,22 @@ guide_labels:
 
 # Structured Data Processing
 
+{% capture requirements %}
+<ul style="margin: 0; padding-left: 20px;">
+<li>TrustGraph deployed (<a href="../getting-started/quickstart">Quick Start</a>)</li>
+<li>TrustGraph 1.2+ (introduced in 1.2, querying in 1.3)</li>
+<li>Understanding of schemas and structured data</li>
+</ul>
+{% endcapture %}
+
+{% include guide/guide-intro-box.html
+   description=page.guide_description
+   difficulty=page.guide_difficulty
+   duration=page.guide_time
+   you_will_need=requirements
+   goal="Extract and query structured data from documents and files using schema-based extraction, working with XML, JSON, CSV, and integrating with agents."
+%}
+
 Learn how to process documents and extract structured data using TrustGraph's
 schema-based extraction capabilities.
 
