Add Algolia DocSearch integration with sitemap and enhanced documentation (#45)

Copilot · graknol · web-flow · commit b8fb20435d8b · 2025-10-01T11:41:08.000+02:00
* Initial plan

* Add explicit sitemap configuration for Algolia crawler efficiency

Co-authored-by: graknol &lt;1364029+graknol@users.noreply.github.com&gt;

* Add tasteful emojis to documentation for better readability

Co-authored-by: graknol &lt;1364029+graknol@users.noreply.github.com&gt;

* Add trailing slashes to all URLs to avoid redirects for Algolia crawler

Co-authored-by: graknol &lt;1364029+graknol@users.noreply.github.com&gt;

---------

Co-authored-by: copilot-swe-agent[bot] &lt;198982749+Copilot@users.noreply.github.com&gt;
Co-authored-by: graknol &lt;1364029+graknol@users.noreply.github.com&gt;
diff --git a/docs/ALGOLIA_SEARCH_SETUP.md b/docs/ALGOLIA_SEARCH_SETUP.md
@@ -26,6 +26,22 @@ algolia: {
 },
 ```
 
+### Sitemap Configuration
+
+A sitemap is automatically generated to help the Algolia crawler efficiently index the documentation. The sitemap configuration is in the preset options:
+
+```typescript
+sitemap: {
+  lastmod: 'date',
+  changefreq: 'weekly',
+  priority: 0.5,
+  ignorePatterns: ['/tags/**'],
+  filename: 'sitemap.xml',
+},
+```
+
+The generated sitemap is available at `https://declarative-sqlite.linden.no/sitemap.xml` after deployment. This helps Algolia's crawler discover and index all documentation pages more efficiently.
+
 ## Setup Steps
 
 To complete the Algolia search setup with your open source key:
diff --git a/docs/docs/core-library/data-modeling.md b/docs/docs/core-library/data-modeling.md
@@ -2,7 +2,7 @@
 sidebar_position: 4
 ---
 
-# Data Modeling with DbRecord
+# 🎯 Data Modeling with DbRecord
 
 While working with raw `Map<String, Object?>` objects is flexible, it's not type-safe and can be error-prone. `declarative_sqlite` provides a `DbRecord` base class to help you create strongly-typed data models that map directly to your database tables and work seamlessly with the query system.
 
diff --git a/docs/docs/core-library/data-synchronization.md b/docs/docs/core-library/data-synchronization.md
@@ -2,7 +2,7 @@
 sidebar_position: 6
 ---
 
-# Data Synchronization
+# 🔄 Data Synchronization
 
 `declarative_sqlite` provides a powerful, built-in framework for implementing offline-first data synchronization. This allows your application to work seamlessly offline and sync its data with a remote server whenever a network connection is available.
 
diff --git a/docs/docs/core-library/file-management.md b/docs/docs/core-library/file-management.md
@@ -2,7 +2,7 @@
 sidebar_position: 5
 ---
 
-# File Management
+# 📁 File Management
 
 `declarative_sqlite` provides a robust, integrated system for managing file attachments associated with your database records. This is useful for any application that needs to store user-generated content like images, documents, or other binary data.
 
diff --git a/docs/docs/core-library/intro.md b/docs/docs/core-library/intro.md
@@ -2,27 +2,27 @@
 sidebar_position: 1
 ---
 
-# Introduction
+# 💪 Introduction
 
 The core `declarative_sqlite` library is the powerhouse of the ecosystem. It contains all the essential tools for defining your schema, managing migrations, querying data, and handling Last-Writer-Wins conflict resolution.
 
 This section provides a deep dive into the advanced features of the core library.
 
-## Key Feature Areas
+## 🎯 Key Feature Areas
 
-### Querying
+### 🔍 Querying
 - **Query Builder**: A fluent, type-safe API for constructing complex SQL queries. It supports `SELECT`, `JOIN`, `WHERE`, `GROUP BY`, `ORDER BY`, and more, reducing the risk of syntax errors.
 - **Streaming Queries**: The foundation for building reactive applications. These queries return a `StreamingQuery` that automatically emits a new list of results whenever the underlying data changes. The library performs sophisticated dependency analysis to ensure that streams are only updated when relevant data is modified.
 
-### Data Modeling
+### 📊 Data Modeling
 - **`DbRecord` and Code Generation**: A pattern for creating typed data models that map directly to your database tables. The `declarative_sqlite_generator` package can be used to automatically generate typed getters for all columns and setters for LWW columns, eliminating boilerplate and improving code safety.
 - **File Management**: A robust system for associating files with your database records. The `fileset` column type allows you to manage collections of files, with built-in support for adding, retrieving, deleting, and garbage-collecting file assets.
 
-### LWW Conflict Resolution
+### 🔄 LWW Conflict Resolution
 - **Hybrid Logical Clock (HLC)**: Used for Last-Writer-Wins (LWW) columns, the HLC is a timestamping mechanism that combines physical time with a logical counter. This ensures consistent conflict resolution when the same data is modified from multiple sources.
 - **LWW Columns**: Special column type that automatically tracks the last modification time using HLC timestamps, enabling conflict-free data merging in distributed scenarios.
 
-## What You'll Learn
+## 📖 What You'll Learn
 
 In this section, you will learn how to:
 - Build complex, multi-table queries with the **Query Builder**.
diff --git a/docs/docs/core-library/query-builder.md b/docs/docs/core-library/query-builder.md
@@ -2,15 +2,15 @@
 sidebar_position: 2
 ---
 
-# Query Builder
+# 🔍 Query Builder
 
 The query builder provides a fluent, type-safe API for constructing SQL queries. It helps prevent syntax errors and makes your data access logic more readable and maintainable than raw SQL strings.
 
 You can access the query builder in two ways:
 1.  By passing a callback to `database.query()`.
 2.  By creating a `QueryBuilder` instance directly to generate a raw SQL string.
 
-## Selecting Columns (`select`)
+## 📝 Selecting Columns (`select`)
 
 The `select` method specifies which columns to return. You can pass simple column names, aliases, or even complex expressions.
 
@@ -25,7 +25,7 @@ q.select('u.name as author_name, p.title as post_title')
 q.select('COUNT(*) as total_tasks, AVG(priority) as avg_priority')
 ```
 
-## Specifying the Source (`from`)
+## 🗂️ Specifying the Source (`from`)
 
 The `from` method specifies the main table for the query. You can also provide an alias for the table, which is highly recommended, especially when performing joins.
 
@@ -37,7 +37,7 @@ q.from('tasks')
 q.from('tasks', 't')
 ```
 
-## Joining Tables (`join`)
+## 🔗 Joining Tables (`join`)
 
 You can join additional tables using the `join`, `leftJoin`, `rightJoin`, and `innerJoin` methods.
 
@@ -47,7 +47,7 @@ q.select('t.title, u.name as author')
   .innerJoin('users', col('t.user_id').eq(col('u.id')), 'u')
 ```
 
-## Filtering Results (`where`)
+## 🎯 Filtering Results (`where`)
 
 The `where` method filters the results. It accepts a `WhereClause` object, which can be constructed using helper functions.
 
diff --git a/docs/docs/core-library/streaming-queries.md b/docs/docs/core-library/streaming-queries.md
@@ -2,7 +2,7 @@
 sidebar_position: 3
 ---
 
-# Streaming Queries
+# 🌊 Streaming Queries
 
 Streaming queries are the cornerstone of building reactive applications with `declarative_sqlite`. Instead of fetching data just once, a streaming query returns a `Stream` that automatically emits a new, updated list of results whenever the underlying data changes.
 
diff --git a/docs/docs/flutter-integration/database-provider.md b/docs/docs/flutter-integration/database-provider.md
@@ -2,7 +2,7 @@
 sidebar_position: 2
 ---
 
-# DatabaseProvider
+# 🗄️ DatabaseProvider
 
 `DatabaseProvider` is an `InheritedWidget` that simplifies the management and accessibility of your `DeclarativeDatabase` instance within a Flutter application.
 
diff --git a/docs/docs/flutter-integration/intro.md b/docs/docs/flutter-integration/intro.md
@@ -2,19 +2,19 @@
 sidebar_position: 1
 ---
 
-# Introduction
+# 📱 Introduction
 
 The `declarative_sqlite_flutter` package provides a set of widgets and helpers specifically designed to bridge the gap between the core database library and a Flutter application. These tools simplify state management, database lifecycle, and UI updates, allowing you to build reactive, data-driven interfaces with minimal boilerplate.
 
-## Key Components
+## 🔧 Key Components
 
-### `DatabaseProvider`
+### 🗄️ `DatabaseProvider`
 A Flutter `InheritedWidget` that handles the initialization and lifecycle of your `DeclarativeDatabase` instance. It ensures that your database is opened when the widget is created, closed when it's disposed, and made available to all descendant widgets in the tree. This is the recommended way to manage your database instance in a Flutter app.
 
-### `QueryListView`
+### 📋 `QueryListView`
 A powerful, reactive `ListView` that is directly connected to a `StreamingQuery`. It automatically listens for data changes and rebuilds its list of items when the query results are updated. It handles all the complexities of stream subscriptions, state management, and efficient UI updates for lists of data.
 
-## What You'll Learn
+## 📖 What You'll Learn
 
 In this section, you will learn how to:
 -   Properly manage your database lifecycle using **`DatabaseProvider`**.
diff --git a/docs/docs/flutter-integration/query-list-view.md b/docs/docs/flutter-integration/query-list-view.md
@@ -2,7 +2,7 @@
 sidebar_position: 3
 ---
 
-# QueryListView
+# 📋 QueryListView
 
 `QueryListView` is a specialized Flutter widget that simplifies the process of displaying a list of data from a `declarative_sqlite` streaming query. It's a reactive `ListView` that automatically updates its contents when the underlying data in the database changes.
 
diff --git a/docs/docs/generator/intro.md b/docs/docs/generator/intro.md
@@ -2,11 +2,11 @@
 sidebar_position: 1
 ---
 
-# Code Generation
+# ⚙️ Code Generation
 
 The `declarative_sqlite_generator` package is a powerful tool that uses `build_runner` to automate the creation of boilerplate code. By using code generation, you can significantly improve type safety, reduce manual coding, and make your data models more robust and easier to maintain.
 
-## Why Use Code Generation?
+## 🤔 Why Use Code Generation?
 
 When working with `DbRecord`, you could write typed getters and setters manually for each column. However, this has several drawbacks:
 -   It's tedious and repetitive.
@@ -15,17 +15,17 @@ When working with `DbRecord`, you could write typed getters and setters manually
 
 Code generation solves these problems by reading your schema directly and creating the necessary code for you.
 
-## What It Generates
+## ✨ What It Generates
 
 For each class annotated with `@GenerateDbRecord`, the generator produces a `.db.dart` part file containing a private extension. This extension includes:
 1.  **Typed Getters**: A getter for each column in the associated table, with the correct Dart type.
 2.  **Typed Setters**: A setter for each LWW (Last-Write-Wins) column, with type validation. Non-LWW columns only get getters to enforce data consistency in distributed systems.
 
 Additionally, it generates a single `sqlite_factory_registration.dart` file for your entire project, which allows the database to automatically map query results to your typed objects.
 
-## Setup and Configuration
+## 🛠️ Setup and Configuration
 
-### 1. Add Dependencies
+### 1️⃣ Add Dependencies
 
 Ensure you have `declarative_sqlite_generator` and `build_runner` in your `dev_dependencies`.
 
diff --git a/docs/docs/getting-started/crud-operations.md b/docs/docs/getting-started/crud-operations.md
@@ -2,11 +2,11 @@
 sidebar_position: 4
 ---
 
-# CRUD Operations
+# ✏️ CRUD Operations
 
 `DeclarativeDatabase` provides straightforward methods for Create, Read, Update, and Delete (CRUD) operations. These methods wrap the underlying `sqflite` calls with additional features like exception mapping and automatic change notifications for streaming queries.
 
-## Insert
+## ➕ Insert
 
 To add a new record to a table, use the `insert` method. It takes the table name and a `DbRecord` or `Map<String, Object?>` representing the data to be inserted.
 
@@ -21,7 +21,7 @@ await database.insert('tasks', {
 });
 ```
 
-## Query (Read)
+## 🔍 Query (Read)
 
 ### Query for DbRecord objects
 
diff --git a/docs/docs/getting-started/defining-a-schema.md b/docs/docs/getting-started/defining-a-schema.md
@@ -2,11 +2,11 @@
 sidebar_position: 2
 ---
 
-# Defining a Schema
+# 🏗️ Defining a Schema
 
 The schema is the blueprint for your database. In `declarative_sqlite`, you define your entire schema—including tables, columns, keys, and views—using a fluent Dart API. This declarative approach makes your schema easy to read, manage, and version control.
 
-## The Schema Builder Function
+## 📝 The Schema Builder Function
 
 Everything starts with a schema builder function. This is a top-level function that takes a `SchemaBuilder` instance and uses it to define the database structure.
 
@@ -21,11 +21,11 @@ void buildAppSchema(SchemaBuilder builder) {
 }
 ```
 
-## Defining Tables
+## 🗄️ Defining Tables
 
 You define a table using the `builder.table()` method. It takes the table name and a callback where you define the table's columns and keys.
 
-### Column Types
+### 🔤 Column Types
 
 The library provides methods for all standard SQLite column types:
 - `text(name)`
@@ -35,14 +35,14 @@ The library provides methods for all standard SQLite column types:
 - `guid(name)`: for UUIDs
 - `fileset(name)`: a special type for managing collections of files
 
-### Column Constraints
+### 🔒 Column Constraints
 
 Each column builder provides methods to add constraints:
 - `.notNull()`: Makes the column required.
 - `.defaultValue(value)`: Sets a default value for the column.
 - `.min(value)` / `.max(value)`: Adds validation constraints (for `integer` and `real` types).
 
-### Keys and Indexes
+### 🔑 Keys and Indexes
 
 You can define primary keys, unique constraints, and indexes using the `table.key()` method.
 - `key([...]).primary()`: Defines a primary key.
diff --git a/docs/docs/getting-started/initializing-the-database.md b/docs/docs/getting-started/initializing-the-database.md
@@ -2,11 +2,11 @@
 sidebar_position: 3
 ---
 
-# Initializing the Database
+# 🚀 Initializing the Database
 
 Once you have defined your schema, the next step is to create and initialize a `DeclarativeDatabase` instance using the `DatabaseProvider` widget. This process involves connecting to the database file, analyzing the existing schema, and automatically applying any necessary migrations.
 
-## Using `DatabaseProvider`
+## 🎯 Using `DatabaseProvider`
 
 In a Flutter application, the easiest way to manage the database lifecycle is with the `DatabaseProvider` widget. It handles initialization, closing the connection, and making the database instance available to the entire widget tree.
 
diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.md
@@ -2,11 +2,11 @@
 sidebar_position: 1
 ---
 
-# Installation
+# 📦 Installation
 
 Setting up `declarative_sqlite` for Flutter involves adding the required packages to your `pubspec.yaml`. The library uses the standard `sqflite` plugin for Android and iOS compatibility.
 
-## Add Dependencies
+## ➕ Add Dependencies
 
 For a Flutter application, you'll need the core library, the Flutter integration package, and the `sqflite` driver. If you plan to use code generation (recommended), you'll also need the generator and `build_runner`.
 
@@ -30,11 +30,11 @@ dev_dependencies:
 
 After adding the dependencies, run `flutter pub get` to install them.
 
-## Database Initialization
+## 🎯 Database Initialization
 
 Flutter projects using the `sqflite` package do **not** need any special initialization steps. The SQLite driver is automatically available on Android and iOS platforms.
 
-## Next Steps
+## ➡️ Next Steps
 
 With the installation complete, you're ready to define your first schema.
 
diff --git a/docs/docs/intro.md b/docs/docs/intro.md
@@ -2,40 +2,40 @@
 sidebar_position: 1
 ---
 
-# Introduction
+# 👋 Introduction
 
 Welcome to the official documentation for **Declarative SQLite**, a comprehensive ecosystem for declarative SQLite schema management, data operations, and real-time synchronization in Dart and Flutter.
 
-## What is Declarative SQLite?
+## 🤔 What is Declarative SQLite?
 
 Declarative SQLite provides a fluent, type-safe, and reactive API for interacting with SQLite databases. It is designed to abstract away the complexities of manual schema migrations, raw SQL queries, and change tracking, allowing you to focus on building your application's features.
 
 The ecosystem is built as a monorepo containing several key packages:
 
-- **`declarative_sqlite`**: The core library providing the foundational features.
-- **`declarative_sqlite_flutter`**: Flutter-specific widgets and helpers for seamless UI integration.
-- **`declarative_sqlite_generator`**: A code generator to reduce boilerplate and improve type safety.
-- **`demo`**: A complete Flutter application showcasing best practices and common use cases.
+- 📦 **`declarative_sqlite`**: The core library providing the foundational features.
+- 📱 **`declarative_sqlite_flutter`**: Flutter-specific widgets and helpers for seamless UI integration.
+- ⚙️ **`declarative_sqlite_generator`**: A code generator to reduce boilerplate and improve type safety.
+- 🚀 **`demo`**: A complete Flutter application showcasing best practices and common use cases.
 
-## Core Philosophy
+## 💡 Core Philosophy
 
 1.  **Declarative Schema Management**: Define your database schema using a fluent Dart API. The library handles schema creation and management automatically.
 2.  **Reactive Data Access**: Built around `Stream`s for reactive applications where UI updates automatically when data changes.
 3.  **Type Safety**: Query builder and code generation provide compile-time type checking and autocompletion.
 4.  **Simple Integration**: Easy integration with Flutter widgets for data-driven UIs.
 
-## Who is this for?
+## 👥 Who is this for?
 
 - **Flutter Developers** building data-driven applications that require a local database.
 - **Dart Developers** working on server-side or standalone applications needing a simple yet powerful database solution.
 - Developers who want to avoid writing raw SQL and manual migration scripts.
 - Teams looking for a structured, maintainable, and scalable way to manage their application's database.
 
-## How to Use These Docs
+## 📚 How to Use These Docs
 
 - **Getting Started**: This section will guide you through the initial setup, from installation to creating your first database and schema.
 - **Core Library**: A deep dive into the features of the main `declarative_sqlite` package, including advanced queries, synchronization, and file management.
 - **Flutter Integration**: Learn how to use the Flutter-specific widgets to quickly build reactive user interfaces.
 - **Generator**: Understand how to use code generation to automate boilerplate and improve your development workflow.
 
-Ready to get started? Head over to the [Installation](./getting-started/installation.md) guide.
+Ready to get started? Head over to the [Installation](./getting-started/installation.md) guide. 🎉
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
