revise and proofread project documentation (drizzle-team#2960)

Co-authored-by: Andrii Sherman <andreysherman11@gmail.com>

README.md

@@ -17,24 +17,24 @@
 
 ### What's Drizzle?
 Drizzle is a modern TypeScript ORM developers [wanna use in their next project](https://stateofdb.com/tools/drizzle). 
-It is [lightweight](https://bundlephobia.com/package/drizzle-orm) at only ~7.4kb minified+gzipped, it's tree shakeable with exactly 0 dependencies. 
+It is [lightweight](https://bundlephobia.com/package/drizzle-orm) at only ~7.4kb minified+gzipped, and it's tree shakeable with exactly 0 dependencies. 
 
-**Drizzle supports every PostgreSQL, MySQL and SQLite databases**, including serverless ones like [Turso](https://orm.drizzle.team/docs/get-started-sqlite#turso), [Neon](https://orm.drizzle.team/docs/get-started-postgresql#neon), [Xata](xata.io), [PlanetScale](https://orm.drizzle.team/docs/get-started-mysql#planetscale), [Cloudflare D1](https://orm.drizzle.team/docs/get-started-sqlite#cloudflare-d1), [FlyIO LiteFS](https://fly.io/docs/litefs/), [Vercel Postgres](https://orm.drizzle.team/docs/get-started-postgresql#vercel-postgres), [Supabase](https://orm.drizzle.team/docs/get-started-postgresql#supabase) and [AWS Data API](https://orm.drizzle.team/docs/get-started-postgresql#aws-data-api). No bells and whistles, no rust binaries, no serverless adapters, everything just works out of the box.
+**Drizzle supports every PostgreSQL, MySQL and SQLite database**, including serverless ones like [Turso](https://orm.drizzle.team/docs/get-started-sqlite#turso), [Neon](https://orm.drizzle.team/docs/get-started-postgresql#neon), [Xata](xata.io), [PlanetScale](https://orm.drizzle.team/docs/get-started-mysql#planetscale), [Cloudflare D1](https://orm.drizzle.team/docs/get-started-sqlite#cloudflare-d1), [FlyIO LiteFS](https://fly.io/docs/litefs/), [Vercel Postgres](https://orm.drizzle.team/docs/get-started-postgresql#vercel-postgres), [Supabase](https://orm.drizzle.team/docs/get-started-postgresql#supabase) and [AWS Data API](https://orm.drizzle.team/docs/get-started-postgresql#aws-data-api). No bells and whistles, no Rust binaries, no serverless adapters, everything just works out of the box.
 
-**Drizzle is serverless-ready by design**, it works in every major JavaScript runtime like NodeJS, Bun, Deno, Cloudflare Workers, Supabase functions, any Edge runtime and even in Browsers.  
-With Drizzle you can be [**fast out of the box**](https://orm.drizzle.team/benchmarks), save time and costs while never introducing any data proxies into your infrastructure. 
+**Drizzle is serverless-ready by design**. It works in every major JavaScript runtime like NodeJS, Bun, Deno, Cloudflare Workers, Supabase functions, any Edge runtime, and even in browsers.  
+With Drizzle you can be [**fast out of the box**](https://orm.drizzle.team/benchmarks) and save time and costs while never introducing any data proxies into your infrastructure. 
 
-While you can use Drizzle as a JavaScript library, it shines in the TypeScript. It lets you [**declare SQL schema**](https://orm.drizzle.team/docs/sql-schema-declaration) and build both [**relational**](https://orm.drizzle.team/docs/rqb) and [**SQL-like queries**](https://orm.drizzle.team/docs/select), while keeping the balance between type-safety and extensibility for toolmakers to build on top.  
+While you can use Drizzle as a JavaScript library, it shines with TypeScript. It lets you [**declare SQL schemas**](https://orm.drizzle.team/docs/sql-schema-declaration) and build both [**relational**](https://orm.drizzle.team/docs/rqb) and [**SQL-like queries**](https://orm.drizzle.team/docs/select), while keeping the balance between type-safety and extensibility for toolmakers to build on top.  
 
 ### Ecosystem
 While Drizzle ORM remains a thin typed layer on top of SQL, we made a set of tools for people to have best possible developer experience.  
 
-Drizzle comes with a powerful [**Drizzle Kit**](https://orm.drizzle.team/kit-docs/overview) CLI companion for you to have hasstle-free migrations. It can generate SQL migration files for you or apply schema changes directly to the database.  
+Drizzle comes with a powerful [**Drizzle Kit**](https://orm.drizzle.team/kit-docs/overview) CLI companion for you to have hassle-free migrations. It can generate SQL migration files for you or apply schema changes directly to the database.  
 
-And we have a [**Drizzle Studio**](https://orm.drizzle.team/drizzle-studio/overview) for you to effortlessly browse and manipulate data in your database of choice.
+We also have [**Drizzle Studio**](https://orm.drizzle.team/drizzle-studio/overview) for you to effortlessly browse and manipulate data in your database of choice.
 
 ### Documentation
-Check out the full documentation on [the website](https://orm.drizzle.team/docs/overview)
+Check out the full documentation on [the website](https://orm.drizzle.team/docs/overview).
 
 ### Our sponsors ❤️
 <p align="center">

docs/custom-types.lite.md

@@ -1,6 +1,7 @@
 # Common way of defining custom types
 
-> **Info**: For more advanced documentation about defining custom data types in PostgreSQL and MySQL please check [custom-types.md](https://github.com/drizzle-team/drizzle-orm/blob/main/docs/custom-types.md)
+> [!NOTE]
+> For more advanced documentation about defining custom data types in PostgreSQL and MySQL, please check [`custom-types.md`](custom-types.md).
 
 ## Examples
 

docs/custom-types.md

@@ -1,7 +1,6 @@
 # How to define custom types
 
 Drizzle ORM has a big set of predefined column types for different SQL databases. But still there are additional types that are not supported by Drizzle ORM (yet). That could be native pg types or extension types
-</br>
 
 Here are some instructions on how to create and use your own types with Drizzle ORM
 
@@ -13,14 +12,11 @@ Each type creation should use 2 classes:
 
 - `ColumnBuilder` - class, that is responsible for generating whole set of needed fields for column creation
 - `Column` - class, that is representing Columns itself, that is used in query generation, migration mapping, etc.
-  </br>
-  </br>
+
   Each module has it's own class, representing `ColumnBuilder` or `Column`:
 - For `pg` -> `PgColumnBuilder` and `PgColumn`
 - For `mysql` -> `MySqlColumnBuilder` and `MySqlColumn`
 - For `sqlite` -> `SQLiteColumnBuilder` and `SQLiteColumn`
-  </br>
-  </br>
 
 ### Builder class explanation - (postgresql text data type example)
 
@@ -44,7 +40,7 @@ export class PgTextBuilder<TData extends string = string>
 }
 ```
 
-> **Warning**
+> [!WARNING]
 > `$pgColumnBuilderBrand` should be changed and be equal to class name for new data type builder
 
 ### Column class explanation - (postgresql text data type example)
@@ -104,11 +100,8 @@ export class PgText<TTableName extends string, TData extends string>
 }
 ```
 
-> **Warning**
+> [!WARNING]
 > `$pgColumnBrand` should be changed and be equal to class name for new data type
----
-
-</br>
 
 ### Full text data type for PostgreSQL example
 
@@ -162,19 +155,13 @@ export function text<T extends string = string>(
 
 ## Custom data type example
 
----
-
-> **Note**
+> [!NOTE]
 > We will check example on pg module, but current pattern applies to all dialects, that are currently supported by Drizzle ORM
 
-</br>
-
 ### Setting up CITEXT datatype
 
----
-> **Note**
- This type is available only with extensions and used for example, just to show how you could setup any data type you want. Extension support will come soon
-</br>
+> [!NOTE]
+> This type is available only with extensions and used for example, just to show how you could setup any data type you want. Extension support will come soon
 
 ### CITEXT data type example
 
@@ -224,4 +211,4 @@ You could add your created custom data types to Drizzle ORM, so everyone can use
 
 Each data type should be placed in separate file in `columns` folder and PR open with tag `new-data-type:pg` | `new-data-type:sqlite` | `new-data-type:mysql`
 
-For more Contribution information - please check [CONTRIBUTING.md](https://github.com/drizzle-team/drizzle-orm/blob/main/CONTRIBUTING.md)
+For more Contribution information - please check [CONTRIBUTING.md](../CONTRIBUTING.md)

docs/joins.md

@@ -1,7 +1,7 @@
 # Drizzle ORM - Joins
 
 As with other parts of Drizzle ORM, the joins syntax is a balance between the SQL-likeness and type safety.
-Here's an example of how a common `1-to-many` relationship can be modelled.
+Here's an example of how a common "one-to-many" relationship can be modelled.
 
 ```typescript
 const users = pgTable('users', {
@@ -96,7 +96,7 @@ In that case, the ORM will use dark TypeScript magic (as if it wasn't already) a
 
 This is much more convenient! Now, you can just do a single check for `row.user !== null`, and all the user fields will become available.
 
-<hr />
+---
 
 Note that you can group any fields in a nested object however you like, but the single check optimization will only be applied to a certain nested object if all its fields belong to the same table.
 So, for example, you can group the city fields, too:
@@ -131,15 +131,16 @@ And the result type will look like this:
 }
 ```
 
-<hr />
+---
 
 If you just need all the fields from all the tables you're selecting and joining, you can simply omit the argument of the `.select()` method altogether:
 
 ```typescript
 const rows = await db.select().from(cities).leftJoin(users, eq(users.cityId, cities.id));
 ```
 
-> **Note**: in this case, the Drizzle table/column names will be used as the keys in the result object.
+> [!NOTE]
+> In this case, the Drizzle table/column names will be used as the keys in the result object.
 
 ```typescript
 {
@@ -156,7 +157,7 @@ const rows = await db.select().from(cities).leftJoin(users, eq(users.cityId, cit
 }[]
 ```
 
-<hr />
+---
 
 There are cases where you'd want to select all the fields from one table, but pick fields from others. In that case, instead of listing all the table fields, you can just pass a table:
 
@@ -181,7 +182,7 @@ There are cases where you'd want to select all the fields from one table, but pi
 }
 ```
 
-<hr />
+---
 
 But what happens if you group columns from multiple tables in the same nested object? Nothing, really - they will still be all individually nullable, just grouped under the same object (as you might expect!):
 

drizzle-kit/README.md

@@ -1,21 +1,21 @@
 ## Drizzle Kit
 
-DrizzleKit - is a CLI migrator tool for DrizzleORM. It is probably one and only tool that lets you completely automatically generate SQL migrations and covers ~95% of the common cases like deletions and renames by prompting user input.
+Drizzle Kit is a CLI migrator tool for Drizzle ORM. It is probably the one and only tool that lets you completely automatically generate SQL migrations and covers ~95% of the common cases like deletions and renames by prompting user input.
 <https://github.com/drizzle-team/drizzle-kit-mirror> - is a mirror repository for issues.
 
 ## Documentation
 
-Check the full documenation on [the website](https://orm.drizzle.team/kit-docs/overview)
+Check the full documentation on [the website](https://orm.drizzle.team/kit-docs/overview).
 
 ### How it works
 
-`drizzle-kit` will traverse `schema folder` or `schema file`, generate schema snapshot and compare it to the previous version, if there's one.
- Based on the difference it will generate all needed SQL migrations and if there are any `automatically unresolvable` cases like `renames` it will prompt user for input.
+Drizzle Kit traverses a schema module and generates a snapshot to compare with the previous version, if there is one.
+Based on the difference, it will generate all needed SQL migrations. If there are any cases that can't be resolved automatically, such as renames, it will prompt the user for input.
 
-For schema file:
+For example, for this schema module:
 
 ```typescript
-// ./src/db/schema.ts
+// src/db/schema.ts
 
 import { integer, pgTable, serial, text, varchar } from "drizzle-orm/pg-core";
 
@@ -63,7 +63,7 @@ CREATE INDEX IF NOT EXISTS users_full_name_index ON users (full_name);
 npm install -D drizzle-kit
 ```
 
-Running with CLI options
+Running with CLI options:
 
 ```jsonc
 // package.json

drizzle-orm/src/sqlite-core/README.md

@@ -8,7 +8,7 @@
 <hr />
 </div>
 
-DrizzleORM is a [tiny](https://twitter.com/_alexblokh/status/1594735880417472512), [blazingly fast](#️-performance-and-prepared-statements) TypeScript ORM library with a [drizzle-kit](#-migrations) CLI companion for automatic SQL migrations generation.
+Drizzle ORM is a [tiny](https://twitter.com/_alexblokh/status/1594735880417472512), [blazingly fast](#️-performance-and-prepared-statements) TypeScript ORM library with a [drizzle-kit](#-migrations) CLI companion for automatic SQL migrations generation.
 Here you can find extensive docs for SQLite module.
 
 | Driver                                                                | Support |                                    |
@@ -365,7 +365,8 @@ const sq = db.$with('sq').as(db.select().from(users).where(eq(users.id, 42)));
 const result = db.with(sq).select().from(sq).all();
 ```
 
-> **Note**: Keep in mind that if you need to select raw `sql` in a WITH subquery and reference that field in other queries, you must add an alias to it:
+> [!NOTE]
+> Keep in mind that if you need to select raw `sql` in a WITH subquery and reference that field in other queries, you must add an alias to it:
 
 ```typescript
 const sq = db.$with('sq').as(db.select({ name: sql<string>`upper(${users.name})`.as('name') }).from(users));
@@ -582,7 +583,8 @@ db
 
 ### Joins
 
-> **Note**: for in-depth partial select joins documentation, refer to [this page](/docs/joins.md).
+> [!NOTE]
+> For in-depth partial select joins documentation, refer to [this page](/docs/joins.md).
 
 ### Many-to-one
 
@@ -721,7 +723,8 @@ const { sql, params } = query.toSQL();
 
 ## Views (WIP)
 
-> **Warning**: views are currently only implemented on the ORM side. That means you can query the views that already exist in the database, but they won't be added to drizzle-kit migrations or `db push` yet.
+> [!WARNING]
+> views are currently only implemented on the ORM side. That means you can query the views that already exist in the database, but they won't be added to drizzle-kit migrations or `db push` yet.
 
 ### Creating a view
 
@@ -731,7 +734,8 @@ import { sqliteView } from 'drizzle-orm/sqlite-core';
 const newYorkers = sqliteView('new_yorkers').as((qb) => qb.select().from(users).where(eq(users.cityId, 1)));
 ```
 
-> **Warning**: All the parameters inside the query will be inlined, instead of replaced by `$1`, `$2`, etc.
+> [!WARNING]
+> All the parameters inside the query will be inlined, instead of replaced by `$1`, `$2`, etc.
 
 You can also use the [`queryBuilder` instance](#query-builder) directly instead of passing a callback, if you already have it imported.
 
@@ -794,8 +798,8 @@ q.all({ name: '%an%' }) // SELECT * FROM customers WHERE name ilike '%an%'
 
 ### Automatic SQL migrations generation with drizzle-kit
 
-[Drizzle Kit](https://www.npmjs.com/package/drizzle-kit) is a CLI migrator tool for Drizzle ORM. It is probably one and only tool that lets you completely automatically generate SQL migrations and covers ~95% of the common cases like deletions and renames by prompting user input.
-Check out the [docs for Drizzle Kit](https://github.com/drizzle-team/drizzle-kit-mirror)
+[Drizzle Kit](https://www.npmjs.com/package/drizzle-kit) is a CLI migrator tool for Drizzle ORM. It is probably the one and only tool that lets you completely automatically generate SQL migrations and covers ~95% of the common cases like deletions and renames by prompting user input.
+Check out the [docs for Drizzle Kit](https://github.com/drizzle-team/drizzle-kit-mirror).
 
 For schema file:
 

examples/mysql-proxy/README.md

@@ -30,7 +30,7 @@ This project has simple example of defining http proxy server, that will proxy a
 
 </br>
 
-> **Warning**:
+> [!WARNING]
 > You will be responsible for proper error handling in this part. Drizzle always waits for `{rows: string[][] | object[]}` so if any error was on http call(or any other call) - be sure, that you return at least empty array back
 >
 > For `all` method you should return `{rows: string[][]}`
@@ -72,7 +72,7 @@ In current MySQL Proxy version - drizzle don't handle transactions for migration
 
 </br>
 
-> **Warning**:
+> [!WARNING]
 > You will be responsible for proper error handling in this part. Drizzle just finds migrations, that need to be executed on this iteration and if finds some -> provide `queries` array to callback
 
 </br>
@@ -97,7 +97,7 @@ await migrate(db, async (queries) => {
 
 ---
 
-> **Note**:
+> [!WARNING]
 > It's just a suggestion on how proxy server could be set up and a simple example of params handling on `query` and `migration` calls
 
 ```typescript

examples/neon-cloudflare/readme.md

@@ -1,4 +1,4 @@
-### Example project for [DrizzleORM](https://driz.li/orm) + [Cloudflare Worker](https://workers.cloudflare.com) + [Neon Serverless](https://github.com/neondatabase/serverless)
+### Example project for [Drizzle ORM](https://driz.li/orm) + [Cloudflare Worker](https://workers.cloudflare.com) + [Neon Serverless](https://github.com/neondatabase/serverless)
 ---
 
 

examples/pg-proxy/README.md

@@ -30,7 +30,7 @@ This project has simple example of defining http proxy server, that will proxy a
 
 </br>
 
-> **Warning**:
+> [!WARNING]
 > You will be responsible for proper error handling in this part. Drizzle always waits for `{rows: string[][] | object[]}` so if any error was on http call(or any other call) - be sure, that you return at least empty array back
 >
 > For `all` method you should return `{rows: string[][]}`
@@ -72,7 +72,7 @@ In current Postgres Proxy version - drizzle don't handle transactions for migrat
 
 </br>
 
-> **Warning**:
+> [!WARNING]
 > You will be responsible for proper error handling in this part. Drizzle just finds migrations, that need to be executed on this iteration and if finds some -> provide `queries` array to callback
 
 </br>
@@ -97,7 +97,7 @@ await migrate(db, async (queries) => {
 
 ---
 
-> **Note**:
+> [!NOTE]
 > It's just a suggestion on how proxy server could be set up and a simple example of params handling on `query` and `migration` calls
 
 ```typescript

examples/sqlite-proxy/README.md

@@ -30,7 +30,7 @@ This project has simple example of defining http proxy server, that will proxy a
 
 </br>
 
-> **Warning**:
+> [!WARNING]
 > You will be responsible for proper error handling in this part. Drizzle always waits for `{rows: string[][]}` so if any error was on http call(or any other call) - be sure, that you return at least empty array back
 >
 > For `get` method you should return `{rows: string[]}`
@@ -71,7 +71,7 @@ In current SQLite Proxy version - drizzle don't handle transactions for migratio
 
 </br>
 
-> **Warning**:
+> [!WARNING]
 > You will be responsible for proper error handling in this part. Drizzle just finds migrations, that need to be executed on this iteration and if finds some -> provide `queries` array to callback
 
 </br>
@@ -96,7 +96,7 @@ await migrate(db, async (queries) => {
 
 ---
 
-> **Note**:
+> [!NOTE]
 > It's just a suggestion on how proxy server could be set up and a simple example of params handling on `query` and `migration` calls
 
 ```typescript