reorganize tutorials into guides

dmitrii-ubskii · dmitrii-ubskii · commit 76540f53059e · 2025-12-09T18:24:51.000Z
diff --git a/core-concepts/modules/ROOT/pages/typeql/index.adoc b/core-concepts/modules/ROOT/pages/typeql/index.adoc
@@ -67,10 +67,4 @@ A deeper look at invalid patterns involving disjoint variable reuse
 ****
 Short definitions of terms used throughout the guide, with links to the section which introduces them.
 ****
-
-.xref:{page-version}@core-concepts::typeql/sql-vs-typeql.adoc[]
-[.clickable]
-****
-A guide of relational constructs in SQL compared to similar concepts in TypeQL.
-****
 --
diff --git a/guides/antora.yml b/guides/antora.yml
@@ -1,5 +1,5 @@
-name: tutorials
-title: Tutorials
+name: guides
+title: Guides
 version: '3.x'
 nav:
   - modules/ROOT/nav.adoc 
diff --git a/guides/modules/ROOT/attachments/bookstore-data.tql b/guides/modules/ROOT/attachments/bookstore-data.tql
diff --git a/guides/modules/ROOT/attachments/bookstore-schema.tql b/guides/modules/ROOT/attachments/bookstore-schema.tql
diff --git a/guides/modules/ROOT/nav.adoc b/guides/modules/ROOT/nav.adoc
diff --git a/guides/modules/ROOT/pages/index.adoc b/guides/modules/ROOT/pages/index.adoc
@@ -0,0 +1,25 @@
+= Guides
+
+In this section, you will find guides for accomplishing specific TypeDB tasks.
+
+**New users** - We recommend new users begin with the xref:{page-version}@home::get-started/index.adoc[get started] guide
+in the home section.
+
+[cols-2]
+--
+.xref:{page-version}@guides::integrations/index.adoc[]
+[.clickable]
+****
+Integrate TypeDB into your application or platform
+****
+
+.xref:{page-version}@guides::typeql/index.adoc[]
+[.clickable]
+****
+Learn how to write TypeQL queries
+****
+--
+
+Got other guides you'd like to see?
+Get in touch at link:mailto:community@typedb.com?subject=Request%20new%20guide[community@typedb.com]
+or link:https://typedb.com/discord[join our discord server].
diff --git a/guides/modules/ROOT/pages/integrations/deploy-through-api.adoc b/guides/modules/ROOT/pages/integrations/deploy-through-api.adoc
@@ -1,11 +1,11 @@
 = Deploy TypeDB via the Cloud API
-:keywords: typedb, typeql, tutorial, api, cloud, cluster, deploy
+:keywords: typedb, typeql, tutorial, guide, api, cloud, cluster, deploy
 :pageTitle: Deploy TypeDB via the Cloud API
-:summary: A tutorial on deploying TypeDB through the API
+:summary: A guide on deploying TypeDB through the API
 :page-toclevels: 2
 :tabs-sync-option:
 
-This tutorial will walk you through the creation of a script
+This guide will walk you through the creation of a script
 to automate deployment of a TypeDB cluster on TypeDB Cloud.
 
 We're going to build a script that authenticates with the API,
@@ -653,7 +653,7 @@ If successful, TypeDB Cloud will deploy your cluster, and the script will poll i
 
 == Conclusion
 
-This tutorial has shown you how to set up a script to deploy TypeDB through the Cloud API.
+This guide has shown you how to set up a script to deploy TypeDB through the Cloud API.
 
 Similar approaches can be used for other common actions,
 such as pausing or resuming your clusters when not in use.
diff --git a/guides/modules/ROOT/pages/integrations/index.adoc b/guides/modules/ROOT/pages/integrations/index.adoc
@@ -0,0 +1,18 @@
+= Integrations
+
+In this section, you will find guides for integrating TypeDB with other tools and platforms.
+
+[cols-2]
+--
+.xref:{page-version}@guides::integrations/deploy-through-api.adoc[]
+[.clickable]
+****
+Set up a script for launching TypeDB from the TypeDB Cloud API
+****
+
+.xref:{page-version}@guides::integrations/use-github-actions.adoc[]
+[.clickable]
+****
+Run TypeDB from your GitHub Actions CI pipeline
+****
+--
diff --git a/guides/modules/ROOT/pages/integrations/use-github-actions.adoc b/guides/modules/ROOT/pages/integrations/use-github-actions.adoc
@@ -1,10 +1,10 @@
 = Use TypeDB in GitHub Actions
-:keywords: typedb, typeql, tutorial, github actions, ci
+:keywords: typedb, typeql, tutorial, guide, github actions, ci
 :pageTitle: Use TypeDB in GitHub Actions
-:summary: A tutorial on using the TypeDB in GitHub Actions
+:summary: A guide on using the TypeDB in GitHub Actions
 :page-toclevels: 2
 
-This tutorial shows you how to get a running instance of TypeDB into your GitHub Actions CI pipeline
+This guide shows you how to get a running instance of TypeDB into your GitHub Actions CI pipeline
 using the TypeDB GitHub Action.
 
 == Step 1. Install and run TypeDB
diff --git a/guides/modules/ROOT/pages/typeql/advanced-pipelines.adoc b/guides/modules/ROOT/pages/typeql/advanced-pipelines.adoc
@@ -1,5 +1,5 @@
 = Advanced query pipelines
-:keywords: typedb, typeql, tutorial, console
+:keywords: typedb, typeql, tutorial, guide, console
 :pageTitle: 
 :summary: 
 :page-toclevels: 2
@@ -8,19 +8,19 @@
 
 == Overview
 
-In this tutorial, we will explore some more complex pipelines and patterns in TypeQL.
+In this guide, we will explore some more complex pipelines and patterns in TypeQL.
 
 == Prerequisites
 
-This tutorial assumes you have access to a running TypeDB instance, as well as a TypeDB Console.
+This guide assumes you have access to a running TypeDB instance, as well as a TypeDB Console.
 
 We recommend xref:{page-version}@home::install/ce.adoc[installing TypeDB Community Edition] as it is distributed bundled with Console for easy setup.
 
-This is a continuation of xref:{page-version}@tutorials::read-data.adoc[] and xref:{page-version}@tutorials::insert-update-data.adoc[], though you don't need to have completed them to follow along.
+This is a continuation of xref:{page-version}@guides::typeql/read-data.adoc[] and xref:{page-version}@guides::typeql/insert-update-data.adoc[], though you don't need to have completed them to follow along.
 
 == Example schema and data
 
-We are using the https://github.com/typedb/typedb-examples/tree/master/use-cases/bookstore[bookstore example] schema and data throughout this tutorial.
+We are using the https://github.com/typedb/typedb-examples/tree/master/use-cases/bookstore[bookstore example] schema and data throughout this guide.
 You can load the example into your TypeDB instance using the following Console command:
 
 [,console]
@@ -34,12 +34,12 @@ database create-init bookstore https://github.com/typedb/typedb-examples/release
 [,typeql]
 ----
 #!test[schema, commit]
-include::{page-version}@tutorials::attachment$bookstore-schema.tql[lines=20..]
+include::{page-version}@guides::attachment$bookstore-schema.tql[lines=20..]
 ----
 [,typeql]
 ----
 #!test[write, commit]
-include::{page-version}@tutorials::attachment$bookstore-data.tql[lines=18..]
+include::{page-version}@guides::attachment$bookstore-data.tql[lines=18..]
 ----
 ====
 
@@ -119,7 +119,7 @@ Finished. Total answers: 8
 Imagine we want to update a user's loyalty tier based on their total spending.
 After a user has paid for an order, we want to update their total spending and, if their spending has crossed some threshold, we want to increase their loyalty tier as well.
 
-We've covered in xref:{page-version}@tutorials::read-data.adoc#_fetch_discounted_price_with_optionals[Reading data] how to use a `try` pattern to assign a variable based on whether the data
+We've covered in xref:{page-version}@guides::typeql/read-data.adoc#_fetch_discounted_price_with_optionals[Reading data] how to use a `try` pattern to assign a variable based on whether the data
 exists in the database.
 This extends to all kinds of patterns, including comparisons.
 All patterns in a `try` block must succeed, otherwise the new variables defined in it will not be assigned.
diff --git a/guides/modules/ROOT/pages/typeql/index.adoc b/guides/modules/ROOT/pages/typeql/index.adoc
@@ -0,0 +1,30 @@
+= TypeQL
+
+This section contains guides for TypeQL, TypeDB query language.
+
+[cols-2]
+--
+.xref:{page-version}@guides::typeql/read-data.adoc[]
+[.clickable]
+****
+Read data from TypeDB
+****
+
+.xref:{page-version}@guides::typeql/insert-update-data.adoc[]
+[.clickable]
+****
+Write and update data in TypeDB
+****
+
+.xref:{page-version}@guides::typeql/advanced-pipelines.adoc[]
+[.clickable]
+****
+Advanced TypeDB pipelines and patterns
+****
+
+.xref:{page-version}@guides::typeql/sql-vs-typeql.adoc[]
+[.clickable]
+****
+A guide of relational constructs in SQL compared to similar concepts in TypeQL.
+****
+--
diff --git a/guides/modules/ROOT/pages/typeql/insert-update-data.adoc b/guides/modules/ROOT/pages/typeql/insert-update-data.adoc
@@ -1,5 +1,5 @@
 = Inserting and updating data
-:keywords: typedb, typeql, tutorial, console, crud
+:keywords: typedb, typeql, tutorial, guide, console, crud
 :pageTitle: 
 :summary: 
 :page-toclevels: 2
@@ -8,19 +8,19 @@
 
 == Overview
 
-This tutorial covers the basics of inserting and updating data in TypeDB.
+This guide covers the basics of inserting and updating data in TypeDB.
 
 == Prerequisites
 
-This tutorial assumes you have access to a running TypeDB instance, as well as a TypeDB Console.
+This guide assumes you have access to a running TypeDB instance, as well as a TypeDB Console.
 
 We recommend xref:{page-version}@home::install/ce.adoc[installing TypeDB Community Edition] as it is distributed bundled with Console for easy setup.
 
-This is a continuation of xref:{page-version}@tutorials::read-data.adoc[], though you don't need to have completed it to follow along.
+This is a continuation of xref:{page-version}@guides::typeql/read-data.adoc[], though you don't need to have completed it to follow along.
 
 == Example schema and data
 
-We are using the https://github.com/typedb/typedb-examples/tree/master/use-cases/bookstore[bookstore example] schema and data throughout this tutorial.
+We are using the https://github.com/typedb/typedb-examples/tree/master/use-cases/bookstore[bookstore example] schema and data throughout this guide.
 You can load the example into your TypeDB instance using the following Console command:
 
 [,console]
@@ -34,12 +34,12 @@ database create-init bookstore https://github.com/typedb/typedb-examples/release
 [,typeql]
 ----
 #!test[schema, commit]
-include::{page-version}@tutorials::attachment$bookstore-schema.tql[lines=20..]
+include::{page-version}@guides::attachment$bookstore-schema.tql[lines=20..]
 ----
 [,typeql]
 ----
 #!test[write, commit]
-include::{page-version}@tutorials::attachment$bookstore-data.tql[lines=18..]
+include::{page-version}@guides::attachment$bookstore-data.tql[lines=18..]
 ----
 ====
 
@@ -282,10 +282,10 @@ insert
 
 [cols-2]
 --
-.xref:{page-version}@tutorials::advanced-pipelines.adoc[]
+.xref:{page-version}@guides::typeql/advanced-pipelines.adoc[]
 [.clickable]
 ****
-Learn about complex pipelines in the next tutorial
+Learn about complex pipelines in the next guide
 ****
 
 .xref:{page-version}@core-concepts::typeql/index.adoc[]
diff --git a/guides/modules/ROOT/pages/typeql/read-data.adoc b/guides/modules/ROOT/pages/typeql/read-data.adoc
@@ -1,5 +1,5 @@
 = Reading data
-:keywords: typedb, typeql, tutorial, console
+:keywords: typedb, typeql, tutorial, guide, console
 :pageTitle: 
 :summary: 
 :page-toclevels: 2
@@ -8,17 +8,17 @@
 
 == Overview
 
-This tutorial covers the common patterns of read queries in TypeQL. 
+This guide covers the common patterns of read queries in TypeQL. 
 
 == Prerequisites
 
-This tutorial assumes you have access to a running TypeDB instance, as well as a TypeDB Console.
+This guide assumes you have access to a running TypeDB instance, as well as a TypeDB Console.
 
 We recommend xref:{page-version}@home::install/ce.adoc[installing TypeDB Community Edition] as it is distributed bundled with Console for easy setup.
 
 == Example schema and data
 
-We are using the https://github.com/typedb/typedb-examples/tree/master/use-cases/bookstore[bookstore example] schema and data throughout this tutorial.
+We are using the https://github.com/typedb/typedb-examples/tree/master/use-cases/bookstore[bookstore example] schema and data throughout this guide.
 You can load the example into your TypeDB instance using the following Console command:
 
 [,console]
@@ -32,12 +32,12 @@ database create-init bookstore https://github.com/typedb/typedb-examples/release
 [,typeql]
 ----
 #!test[schema, commit]
-include::{page-version}@tutorials::attachment$bookstore-schema.tql[lines=20..]
+include::{page-version}@guides::attachment$bookstore-schema.tql[lines=20..]
 ----
 [,typeql]
 ----
 #!test[write, commit]
-include::{page-version}@tutorials::attachment$bookstore-data.tql[lines=18..]
+include::{page-version}@guides::attachment$bookstore-data.tql[lines=18..]
 ----
 ====
 
@@ -372,10 +372,10 @@ fetch {
 
 [cols-2]
 --
-.xref:{page-version}@tutorials::insert-update-data.adoc[]
+.xref:{page-version}@guides::typeql/insert-update-data.adoc[]
 [.clickable]
 ****
-Learn how to modify data in the next tutorial
+Learn how to modify data in the next guide
 ****
 
 .xref:{page-version}@core-concepts::typeql/index.adoc[]
diff --git a/guides/modules/ROOT/pages/typeql/sql-vs-typeql.adoc b/guides/modules/ROOT/pages/typeql/sql-vs-typeql.adoc
diff --git a/guides/modules/ROOT/partials/nav.adoc b/guides/modules/ROOT/partials/nav.adoc
@@ -0,0 +1,10 @@
+.xref:{page-version}@guides::index.adoc[]
+
+* xref:{page-version}@guides::integrations/index.adoc[]
+** xref:{page-version}@guides::integrations/deploy-through-api.adoc[]
+** xref:{page-version}@guides::integrations/use-github-actions.adoc[]
+
+* xref:{page-version}@guides::typeql/index.adoc[]
+** xref:{page-version}@guides::typeql/read-data.adoc[]
+** xref:{page-version}@guides::typeql/insert-update-data.adoc[]
+** xref:{page-version}@guides::typeql/advanced-pipelines.adoc[]
diff --git a/home/modules/ROOT/pages/learning-journey.adoc b/home/modules/ROOT/pages/learning-journey.adoc
@@ -37,7 +37,7 @@ skip to the next section and come back to the examples afterward!
 
 == Step 5: Tutorials
 
-Look at our xref:{page-version}@tutorials::index.adoc[tutorials] for accomplishing specific TypeDB tasks,
+Look at our xref:{page-version}@guides::index.adoc[guides] for accomplishing specific TypeDB tasks,
 such as using TypeDB in CI, or deploying TypeDB through our Cloud API.
 
 == Step 6: Core concepts
diff --git a/home/modules/ROOT/partials/nav-main.adoc b/home/modules/ROOT/partials/nav-main.adoc
@@ -2,7 +2,7 @@ include::{page-version}@home::partial$nav.adoc[]
 
 include::{page-version}@examples::partial$nav.adoc[]
 
-include::{page-version}@tutorials::partial$nav.adoc[]
+include::{page-version}@guides::partial$nav.adoc[]
 
 include::{page-version}@core-concepts::partial$nav.adoc[]
 
diff --git a/test/code/main.py b/test/code/main.py
@@ -23,6 +23,7 @@
 
     "home": os.path.join(os.path.dirname(__file__), "../../home/modules/ROOT"),
     "examples": os.path.join(os.path.dirname(__file__), "../../examples/modules/ROOT"),
+    "guides": os.path.join(os.path.dirname(__file__), "../../guides/modules/ROOT"),
     "maintenance-operation": os.path.join(os.path.dirname(__file__), "../../maintenance-operation/modules/ROOT"),
     "core-concepts": os.path.join(os.path.dirname(__file__), "../../core-concepts/modules/ROOT"),
     "tools": os.path.join(os.path.dirname(__file__), "../../tools/modules/ROOT"),
diff --git a/tutorials/modules/ROOT/pages/index.adoc b/tutorials/modules/ROOT/pages/index.adoc
diff --git a/tutorials/modules/ROOT/partials/nav.adoc b/tutorials/modules/ROOT/partials/nav.adoc
