docs: uv-first onboarding and SEO groundwork

.github/workflows/docs.yml

@@ -111,7 +111,7 @@ jobs:
         env:
           HUGO_ENVIRONMENT: production
           PR_NUMBER: ${{ github.event.number }}
-        run: hugo --minify --gc --baseURL "https://rayakame.github.io/sqlc-gen-better-python/pr-preview/pr-${PR_NUMBER}/"
+        run: hugo --minify --gc --baseURL "https://sqlc-gen-better-python.rayakame.dev/pr-preview/pr-${PR_NUMBER}/"
 
       - name: Deploy preview
         uses: rossjrw/pr-preview-action@ffa7509e91a3ec8dfc2e5536c4d5c1acdf7a6de9 # v1.8.1

README.md

@@ -16,17 +16,17 @@ aliases and generics, and `enum.StrEnum`).
 > Besides the [official installation methods](https://docs.sqlc.dev/en/latest/overview/install.html),
 > the `sqlc` CLI itself is also pip-installable via
 > [`sqlc-bin`](https://pypi.org/project/sqlc-bin/), which ships the unmodified
-> official binaries - no Go toolchain required: `pip install sqlc-bin` (or
-> `uv add --dev sqlc-bin`) puts `sqlc` on your PATH, pinnable like any other
+> official binaries - no Go toolchain required: `uv add --dev sqlc-bin` (or
+> `pip install sqlc-bin`) puts `sqlc` on your PATH, pinnable like any other
 > Python dependency.
 
 ## Documentation
 
-**https://rayakame.github.io/sqlc-gen-better-python/**
+**https://sqlc-gen-better-python.rayakame.dev/**
 
-- [Getting Started](https://rayakame.github.io/sqlc-gen-better-python/docs/getting-started/) - install the plugin and generate your first models.
-- [Guide](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/) - configuration, drivers, model types, writing queries, and every feature, each with real generated output.
-- [Reference](https://rayakame.github.io/sqlc-gen-better-python/docs/reference/) - all configuration options, SQL-to-Python type mappings, and per-driver feature support.
+- [Getting Started](https://sqlc-gen-better-python.rayakame.dev/docs/getting-started/) - install the plugin and generate your first models.
+- [Guide](https://sqlc-gen-better-python.rayakame.dev/docs/guide/) - configuration, drivers, model types, writing queries, and every feature, each with real generated output.
+- [Reference](https://sqlc-gen-better-python.rayakame.dev/docs/reference/) - all configuration options, SQL-to-Python type mappings, and per-driver feature support.
 
 Questions or feedback? Join the [Discord](https://discord.gg/hikari).
 
@@ -75,33 +75,33 @@ sql:
 
 More options at the [`sqlc` config reference](https://docs.sqlc.dev/en/stable/reference/config.html),
 and the full plugin option list in the
-[configuration reference](https://rayakame.github.io/sqlc-gen-better-python/docs/reference/configuration-options/).
+[configuration reference](https://sqlc-gen-better-python.rayakame.dev/docs/reference/configuration-options/).
 
 ## Features
 
 - **Four model types** - `dataclass`, `attrs`, `msgspec`, or `pydantic`
-  ([docs](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/model-types/)).
+  ([docs](https://sqlc-gen-better-python.rayakame.dev/docs/guide/model-types/)).
 - **Seven drivers** - `asyncpg`, `psycopg_async`, and `psycopg_sync` for
   PostgreSQL, `aiosqlite` and `sqlite3` for SQLite, plus experimental
   `turso_async` and `turso_sync` for [Turso](https://github.com/tursodatabase/turso)
-  ([docs](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/drivers/)).
+  ([docs](https://sqlc-gen-better-python.rayakame.dev/docs/guide/drivers/)).
 - **Typed query functions** - one module per query file, one function per query
-  ([docs](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/writing-queries/)).
+  ([docs](https://sqlc-gen-better-python.rayakame.dev/docs/guide/writing-queries/)).
 - **PostgreSQL enums** as `enum.StrEnum` classes
-  ([docs](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/enums/)).
+  ([docs](https://sqlc-gen-better-python.rayakame.dev/docs/guide/enums/)).
 - **Type overrides and converters** - swap a column's Python type, or plug in your
   own encode/decode functions
-  ([overrides](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/type-overrides/),
-  [converters](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/converters/)).
+  ([overrides](https://sqlc-gen-better-python.rayakame.dev/docs/guide/type-overrides/),
+  [converters](https://sqlc-gen-better-python.rayakame.dev/docs/guide/converters/)).
 - **Typed JSON columns** via msgspec structs
-  ([docs](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/working-with-json/)).
+  ([docs](https://sqlc-gen-better-python.rayakame.dev/docs/guide/working-with-json/)).
 - **Optional docstrings** in `google`, `numpy`, or `pep257` convention
-  ([docs](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/docstrings/)).
+  ([docs](https://sqlc-gen-better-python.rayakame.dev/docs/guide/docstrings/)).
 - Generated code passes **pyright strict** and **ruff**.
 
 Every [sqlc macro](https://docs.sqlc.dev/en/latest/reference/macros.html) is
 supported. Which query commands are available depends on the driver - see the
-[feature support matrix](https://rayakame.github.io/sqlc-gen-better-python/docs/reference/feature-support/).
+[feature support matrix](https://sqlc-gen-better-python.rayakame.dev/docs/reference/feature-support/).
 
 ## Development
 

docs/content/_index.md

@@ -1,5 +1,7 @@
 ---
 title: sqlc-gen-better-python
+description: >-
+  A sqlc plugin that generates type-safe Python from SQL: dataclass, attrs, msgspec, or pydantic models plus fully typed query functions for asyncpg, psycopg, sqlite3, aiosqlite, and turso.
 layout: hextra-home
 ---
 
@@ -183,32 +185,11 @@ Generated code is held to the same standard as hand-written code:
   Set up in three steps
 {{< /hextra/hero-section >}}
 
-Point `sqlc` at the plugin, pick a driver and a model type, and generate:
-
-```yaml
-# sqlc.yaml
-version: "2"
-plugins:
-  - name: python
-    wasm:
-      url: https://github.com/rayakame/sqlc-gen-better-python/releases/download/v0.7.0/sqlc-gen-better-python.wasm
-      sha256: 64ac923cf5f14ebc05bdeb2d1827f14d89a6f3b7180ac08964ef44ff065af5f9
-sql:
-  - engine: "postgresql"
-    queries: "query.sql"
-    schema: "schema.sql"
-    codegen:
-      - out: "app/db"
-        plugin: python
-        options:
-          package: "db"
-          emit_init_file: true
-          sql_driver: "asyncpg"
-```
-
-```bash
-sqlc generate
-```
+1. **Install** the `sqlc` CLI (`uv add --dev sqlc-bin`) and your database driver.
+2. **Configure** a `sqlc.yaml` pointing at the plugin's release wasm, your
+   schema, and your queries.
+3. **Generate** - `sqlc generate` writes typed models and one query module per
+   query file.
 
 <div class="hx:mt-6"></div>
 

docs/content/docs/_index.md

@@ -1,5 +1,7 @@
 ---
 title: Documentation
+description: >-
+  Documentation for sqlc-gen-better-python, the sqlc plugin that turns your SQL schema and queries into modern, fully typed Python database code.
 weight: 1
 prev: /
 next: getting-started

docs/content/docs/getting-started.md

@@ -1,5 +1,7 @@
 ---
 title: Getting Started
+description: >-
+  Install sqlc and a database driver, configure sqlc.yaml, and generate your first typed Python queries - step-by-step setup for every supported driver.
 weight: 1
 prev: /docs
 next: /docs/guide
@@ -12,26 +14,47 @@ below and the whole page follows your choice.
 
 ## Prerequisites
 
-You need [`sqlc`](https://docs.sqlc.dev/en/latest/overview/install.html) on your
-`PATH` and **Python 3.12 or newer** (the generated code uses PEP 695 type aliases
-and generics, and `enum.StrEnum`).
+You need **Python 3.12 or newer** (the generated code uses PEP 695 type aliases
+and generics, and `enum.StrEnum`) and the `sqlc` CLI on your `PATH` - pick
+either way to install it:
 
-{{< callout type="info" >}}
-  Besides the official installation methods, sqlc is also pip-installable via
-  [sqlc-bin](https://pypi.org/project/sqlc-bin/), which ships the unmodified
-  official binaries - no Go toolchain required. `uv add --dev sqlc-bin` (or
-  `pip install sqlc-bin`) puts `sqlc` on your PATH, and the package version
-  tracks the sqlc version, so you can pin it like any other dependency.
-{{< /callout >}}
+{{< tabs >}}
+
+  {{< tab name="sqlc-bin (recommended)" >}}
+
+[sqlc-bin](https://pypi.org/project/sqlc-bin/) ships the unmodified official
+`sqlc` binaries as a Python package - no Go toolchain needed, pinnable like
+any other dependency:
+
+```bash
+uv add --dev sqlc-bin
+```
+
+  {{< /tab >}}
 
-Then install the database driver you want to use:
+  {{< tab name="official installation" >}}
+
+Any of the [official methods](https://docs.sqlc.dev/en/latest/overview/install.html)
+works just as well:
+
+```bash
+brew install sqlc
+# or
+go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
+```
+
+  {{< /tab >}}
+
+{{< /tabs >}}
+
+Then add the database driver you want to use:
 
 {{< tabs >}}
 
   {{< tab name="asyncpg" >}}
 
 ```bash
-pip install asyncpg asyncpg-stubs
+uv add asyncpg asyncpg-stubs
 ```
 
 asyncpg has no strict typing of its own; [asyncpg-stubs](https://pypi.org/project/asyncpg-stubs/)
@@ -42,23 +65,23 @@ makes the generated annotations work under pyright and mypy.
   {{< tab name="psycopg_async" >}}
 
 ```bash
-pip install "psycopg[binary]>=3.2"
+uv add "psycopg[binary]>=3.2"
 ```
 
   {{< /tab >}}
 
   {{< tab name="psycopg_sync" >}}
 
 ```bash
-pip install "psycopg[binary]>=3.2"
+uv add "psycopg[binary]>=3.2"
 ```
 
   {{< /tab >}}
 
   {{< tab name="aiosqlite" >}}
 
 ```bash
-pip install aiosqlite
+uv add aiosqlite
 ```
 
   {{< /tab >}}
@@ -73,6 +96,8 @@ Nothing to install - sqlite3 is in the standard library.
 
 {{< /tabs >}}
 
+Using pip instead of uv? Swap `uv add` for `pip install` in any command above.
+
 ## 1. Configure the plugin
 
 The plugin is a WASM binary that `sqlc generate` downloads and runs. Create a

docs/content/docs/guide/_index.md

@@ -1,5 +1,7 @@
 ---
 title: Guide
+description: >-
+  Feature guides for sqlc-gen-better-python: drivers, model types, writing queries, enums, type overrides, converters, JSON, docstrings, and naming.
 weight: 2
 prev: /docs/getting-started
 next: /docs/guide/configuration

docs/content/docs/guide/configuration.md

@@ -1,5 +1,7 @@
 ---
 title: Configuration
+description: >-
+  How the plugin is wired into sqlc.yaml and how its options are structured, with a full annotated example configuration.
 weight: 10
 prev: /docs/guide
 next: /docs/guide/drivers

docs/content/docs/guide/converters.md

@@ -1,5 +1,7 @@
 ---
 title: Converters
+description: >-
+  Plug your own encode/decode functions into the generated code to map columns onto custom Python types that a plain override cannot express.
 weight: 70
 prev: /docs/guide/type-overrides
 next: /docs/guide/working-with-json

docs/content/docs/guide/docstrings.md

@@ -1,5 +1,7 @@
 ---
 title: Docstrings
+description: >-
+  Emit google, numpy, or pep257 docstrings on every generated model, enum, and query function.
 weight: 80
 prev: /docs/guide/working-with-json
 next: /docs/guide/sqlite-type-conversion

docs/content/docs/guide/drivers.md

@@ -1,5 +1,7 @@
 ---
 title: Drivers
+description: >-
+  Pick between asyncpg, psycopg_async, psycopg_sync, aiosqlite, sqlite3, and the experimental turso drivers - connection examples and per-driver behavior.
 weight: 20
 prev: /docs/guide/configuration
 next: /docs/guide/model-types
@@ -152,7 +154,7 @@ user = queries.get_field_naming(conn, id_=1)
 
 [Turso](https://github.com/tursodatabase/turso) is an SQLite-compatible
 database engine; its [pyturso](https://pypi.org/project/pyturso/) package
-(`pip install pyturso`) mirrors the `sqlite3` module's API and adds a native
+(`uv add pyturso`) mirrors the `sqlite3` module's API and adds a native
 asyncio variant.
 
 - `turso_sync` targets the `turso` module, `turso_async` the `turso.aio` module.

docs/content/docs/guide/enums.md

@@ -1,5 +1,7 @@
 ---
 title: Enums
+description: >-
+  PostgreSQL enum types become Python enum.StrEnum classes, wired through the generated models and query parameters.
 weight: 50
 prev: /docs/guide/writing-queries
 next: /docs/guide/type-overrides

docs/content/docs/guide/model-types.md

@@ -1,5 +1,7 @@
 ---
 title: Model types
+description: >-
+  Generate dataclass, attrs, msgspec, or pydantic models from your SQL schema - what each model type looks like and how to choose one.
 weight: 30
 prev: /docs/guide/drivers
 next: /docs/guide/writing-queries

docs/content/docs/guide/naming.md

@@ -1,5 +1,7 @@
 ---
 title: Naming and identifiers
+description: >-
+  How SQL identifiers become Python names: singularized model classes, field naming, initialisms, and reserved-word escaping.
 weight: 100
 prev: /docs/guide/sqlite-type-conversion
 ---

docs/content/docs/guide/sqlite-type-conversion.md

@@ -1,5 +1,7 @@
 ---
 title: SQLite type conversion
+description: >-
+  How the SQLite drivers convert dates, decimals, booleans, and blobs: adapters, converters, PARSE_DECLTYPES, speedups, and how turso differs.
 weight: 90
 prev: /docs/guide/docstrings
 next: /docs/guide/naming

docs/content/docs/guide/type-overrides.md

@@ -1,5 +1,7 @@
 ---
 title: Type overrides
+description: >-
+  Replace the Python type of a specific column or of every column of a SQL type, including nullable handling and custom imports.
 weight: 60
 prev: /docs/guide/enums
 next: /docs/guide/converters

docs/content/docs/guide/working-with-json.md

@@ -1,5 +1,7 @@
 ---
 title: Working with JSON
+description: >-
+  Turn untyped json/jsonb string columns into fully typed, validated Python objects with converters and msgspec structs.
 weight: 75
 prev: /docs/guide/converters
 next: /docs/guide/docstrings

docs/content/docs/guide/writing-queries.md

@@ -1,5 +1,7 @@
 ---
 title: Writing queries
+description: >-
+  How sqlc query annotations become typed Python functions: :one, :many, :exec, :execrows, :execlastid, :execresult, and :copyfrom, shown with generated code.
 weight: 40
 prev: /docs/guide/model-types
 next: /docs/guide/enums

docs/content/docs/reference/_index.md

@@ -1,5 +1,7 @@
 ---
 title: Reference
+description: >-
+  Canonical reference for sqlc-gen-better-python: every configuration option, SQL-to-Python type mappings, and per-driver feature support.
 weight: 3
 prev: /docs/guide
 sidebar:

docs/content/docs/reference/configuration-options.md

@@ -1,5 +1,7 @@
 ---
 title: Configuration options
+description: >-
+  Every plugin option in one place: its type, default, and meaning, from sql_driver and model_type to overrides and speedups.
 weight: 10
 prev: /docs/reference
 next: /docs/reference/type-mappings

docs/content/docs/reference/feature-support.md

@@ -1,5 +1,7 @@
 ---
 title: Feature support
+description: >-
+  Which sqlc macros, query commands, and features each driver supports - the full compatibility matrix.
 weight: 30
 prev: /docs/reference/type-mappings
 ---

docs/content/docs/reference/type-mappings.md

@@ -1,5 +1,7 @@
 ---
 title: Type mappings
+description: >-
+  The built-in SQL-to-Python type mappings for PostgreSQL and SQLite, and what nullable columns and arrays map to.
 weight: 20
 prev: /docs/reference/configuration-options
 next: /docs/reference/feature-support