chore: Fix markdown lint issues (serverpod#283)

SandPod · web-flow · commit 232aa76794bb · 2025-05-27T11:23:46.000+02:00
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
@@ -2,4 +2,5 @@ MD001: false
 MD013: false
 MD014: false
 MD024: false
-MD033: false # Allow inline HTML
+MD033: false # Allow inline HTML
+MD059: false # Allow non descriptive link text
diff --git a/docs/06-concepts/06-database/01-connection.md b/docs/06-concepts/06-database/01-connection.md
@@ -4,7 +4,6 @@ In Serverpod the connection details and password for the database are stored ins
 
 The easiest way to get started is to use a Docker container to run your local Postgres server, and this is how Serverpod is set up out of the box. This page contains more detailed information if you want to connect to another database instance or run Postgres locally yourself.
 
-
 ### Connection details
 
 Each environment configuration contains a `database` keyword that specifies the connection details.
@@ -49,7 +48,6 @@ database:
 
 In this example, Postgres will look for tables in the `custom` schema first, and then fall back to `public` if needed. This gives you more control over where your data lives and how it’s accessed
 
-
 ### Database password
 
 The database password is stored in a separate file called `passwords.yaml` in the same `config` directory. The password for each environment is stored under the `database` keyword in the file.
@@ -102,7 +100,6 @@ To connect to a remote Postgres server (that you have installed on a VPS or VDS)
 - You may need to open the database port on the machine. This may include configuring its firewall.
 - Update your Serverpod `database` config to use the public network address, database name, port, user, and password.
 
-
 ### Connecting to Google Cloud SQL
 
 You can connect to a Google Cloud SQL Postgres instance in two ways:
@@ -114,13 +111,14 @@ The next step is to update the database password in `passwords.yaml` and the con
 
 :::info
 
-If you are using the `isUnixSocket` don't forget to add **"/.s.PGSQL.5432"** to the end of the `host` IP address. Otherwise, your Google Cloud Run instance will not be able to connect to the database.
+If you are using the `isUnixSocket` don't forget to add __"/.s.PGSQL.5432"__ to the end of the `host` IP address. Otherwise, your Google Cloud Run instance will not be able to connect to the database.
 
 :::
 
 ### Connecting to AWS RDS
 
 You can connect to an AWS RDS Instance in two ways:
+
 1. Enable public access to the database and configure VPC/Subnets to accept your Serverpod's IP address.
 2. Use the Endpoint `database-name.some-unique-id.server-location.rds.amazonaws.com` to connect to it from AWS ECS.
 
diff --git a/docs/06-concepts/06-database/03-relations/05-referential-actions.md b/docs/06-concepts/06-database/03-relations/05-referential-actions.md
@@ -21,6 +21,7 @@ relation(onUpdate=<ACTION>, onDelete=<ACTION>)
 ```
 
 ## Default values
+
 If no referential actions are specified, the default behavior will be applied.
 
 If the relation is defined as an [object relation](one-to-one#with-an-object), the default behavior is `NoAction` for both onUpdate and onDelete.
@@ -29,10 +30,8 @@ If the relation is defined as an [object relation](one-to-one#with-an-object), t
 parent: Model?, relation(onUpdate=NoAction, onDelete=NoAction)
 ```
 
-
 If the relation is defined as an [id relation](one-to-one#with-an-id-field), the default behavior is `NoAction` for onUpdate and `Cascade` for onDelete.
 
-
 ```yaml
 parentId: int?, relation(parent=model_table, onUpdate=NoAction, onDelete=Cascade)
 ```
diff --git a/docs/06-concepts/06-database/08-transactions.md b/docs/06-concepts/06-database/08-transactions.md
@@ -2,7 +2,7 @@
 
 The essential point of a database transaction is that it bundles multiple steps into a single, all-or-nothing operation. The intermediate states between the steps are not visible to other concurrent transactions, and if some failure occurs that prevents the transaction from completing, then none of the steps affect the database at all.
 
-Serverpod handles database transactions through the `session.db.transaction` method. The method takes a callback function that receives a transaction object. 
+Serverpod handles database transactions through the `session.db.transaction` method. The method takes a callback function that receives a transaction object.
 
 The transaction is committed when the callback function returns, and rolled back if an exception is thrown. Any return value of the callback function is returned by the `transaction` method.
 
@@ -63,6 +63,7 @@ A savepoint is a special mark inside a transaction that allows all commands that
 Read more about savepoints in the [PostgreSQL documentation](https://www.postgresql.org/docs/current/sql-savepoint.html).
 
 ### Creating savepoints
+
 To create a savepoint, call the `createSavepoint` method on the transaction object:
 
 ```dart
diff --git a/docs/06-concepts/06-database/10-raw-access.md b/docs/06-concepts/06-database/10-raw-access.md
@@ -33,7 +33,6 @@ Simple query mode is suitable for:
 * Queries containing multiple statements.
 * Situations where the extended query protocol is not available (e.g., replication mode or with proxies like PGBouncer).
 
-
 ```dart
   DatabaseResult result = await session.db.unsafeSimpleQuery(
       r'SELECT * FROM mytable WHERE id = 1; SELECT * FROM othertable;'
@@ -78,4 +77,3 @@ var result = await db.unsafeQuery(
 :::danger
 Always sanitize your input when using raw query methods. For the `unsafeQuery` and `unsafeExecute` methods, use query parameters to prevent SQL injection. Avoid using `unsafeSimpleQuery` and `unsafeSimpleExecute` unless the simple query protocol is strictly required.
 :::
-
diff --git a/docs/06-concepts/11-authentication/01-setup.md b/docs/06-concepts/11-authentication/01-setup.md
@@ -34,6 +34,7 @@ void run(List<String> args) async {
   ...
 }
 ```
+
 Optionally, add a nickname for the module in the `config/generator.yaml` file. This nickname will be used as the name of the module in the code.
 
 ```yaml
@@ -71,8 +72,8 @@ $ dart run bin/main.dart --role maintenance --apply-migrations
 The full migration instructions can be found in the [migration guide](../database/migrations).
 
 ### Configure Authentication
-Serverpod's auth module comes with a default Authentication Configuration. To customize it, go to your main `server.dart` file, import the `serverpod_auth_server` module and set up the authentication configuration:
 
+Serverpod's auth module comes with a default Authentication Configuration. To customize it, go to your main `server.dart` file, import the `serverpod_auth_server` module and set up the authentication configuration:
 
 ```dart
 import 'package:serverpod_auth_server/module.dart' as auth;  
@@ -185,22 +186,27 @@ void main() async {
 The `SessionManager` has useful methods for viewing and monitoring the user's current state.
 
 #### Check authentication state
+
 To check if the user is signed in:
 
 ```dart
 sessionManager.isSignedIn;
 ```
+
 Returns `true` if the user is signed in, or `false` otherwise.
 
 #### Access current user
+
 To retrieve information about the current user:
 
 ```dart
 sessionManager.signedInUser;
 ```
+
 Returns a `UserInfo` object if the user is currently signed in, or `null` if the user is not.
 
 #### Register authentication
+
 To register a signed in user in the session manager:
 
 ```dart
@@ -210,9 +216,11 @@ await sessionManager.registerSignedInUser(
   authKey,
 );
 ```
+
 This will persist the user information and refresh any open streaming connection, see [Custom Providers - Client Setup](providers/custom-providers#client-setup) for more details.
 
 #### Monitor authentication changes
+
 To add a listener that tracks changes in the user's authentication state, useful for updating the UI:
 
 ```dart
@@ -226,24 +234,28 @@ void initState() {
   });
 }
 ```
+
 The listener is triggered whenever the user's sign-in state changes.
 
 #### Sign out current device
+
 To sign the user out on from the current device:
 
 ```dart
 await sessionManager.signOutDevice();
 ```
+
 Returns `true` if the sign-out is successful, or `false` if it fails.
 
 #### Sign out all devices
+
 To sign the user out across all devices:
 
 ```dart
 await sessionManager.signOutAllDevices();
 ```
-Returns `true` if the user is successfully signed out from all devices, or `false` if it fails.
 
+Returns `true` if the user is successfully signed out from all devices, or `false` if it fails.
 
 :::info
 
@@ -252,4 +264,5 @@ The `signOut` method is deprecated. This method calls the deprecated `signOut` s
 ```dart
 await sessionManager.signOut();  // Deprecated
 ```
-::: 
+
+:::
diff --git a/docs/06-concepts/11-authentication/02-basics.md b/docs/06-concepts/11-authentication/02-basics.md
@@ -131,12 +131,12 @@ await client.modules.auth.status.signOutAllDevices();
 
 This status endpoint retrieves the user ID from session's authentication information, then revokes all authentication keys related to that user.
 
-:::info 
+:::info
 The `signOut` status endpoint is deprecated. Use `signOutDevice` or `signOutAllDevices` instead.
 
 ```dart
 await client.modules.auth.status.signOut();  // Deprecated
 ```
 
 The behavior of `signOut` is controlled by `legacyUserSignOutBehavior`, which you can adjust in the [configure authentication](setup#configure-authentication) section. This allows you to control the signout behaviour of already shipped clients.
-::: 
+:::
diff --git a/docs/06-concepts/11-authentication/04-providers/06-custom-providers.md b/docs/06-concepts/11-authentication/04-providers/06-custom-providers.md
@@ -193,6 +193,7 @@ await UserAuthentication.signOutUser(
   userId: 123,  // Optional: If omitted, the currently authenticated user will be signed out
 );
 ```
+
 This method deletes all authentication keys associated with the user.
 
 ##### Signing out a specific user
diff --git a/docs/06-concepts/11-authentication/05-custom-overrides.md b/docs/06-concepts/11-authentication/05-custom-overrides.md
@@ -50,7 +50,7 @@ List<String> scopes = extractScopes(token);
 Set<Scope> userScopes = scopes.map((scope) => Scope(scope)).toSet();
 ```
 
-### Handling revoked authentication 
+### Handling revoked authentication
 
 When a user's authentication is revoked, the server must be notified to respect the changes (e.g. to close method streams). Invoke the `session.messages.authenticationRevoked` method and raise the appropriate event to notify the server.
 
@@ -73,6 +73,7 @@ await session.messages.authenticationRevoked(
 - `message` - The revoked authentication event message. See below for the different type of messages.
 
 #### Revoked authentication messages
+
 There are three types of `RevokedAuthentication` messages that are used to specify the extent of the authentication revocation:
 
 | Message type | Description |
@@ -200,6 +201,7 @@ You will also need to implement the `AuthenticationHandler` accordingly, in orde
 
 The header value must be compliant with the HTTP header format defined in RFC 9110 HTTP Semantics, 11.6.2. Authorization.
 See:
+
 - [HTTP Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)
 - [RFC 9110, 11.6.2. Authorization](https://httpwg.org/specs/rfc9110.html#field.authorization)
 
diff --git a/docs/06-concepts/19-testing/01-get-started.md b/docs/06-concepts/19-testing/01-get-started.md
@@ -8,6 +8,7 @@ For Serverpod Mini projects, everything related to the database in this guide ca
 
 :::
 
+<!-- markdownlint-disable MD029 -->
 <details>
 <summary> Have an existing project? Follow these steps first!</summary>
 <p>
@@ -168,6 +169,7 @@ dev_dependencies:
 That's it, the project setup should be ready to start using the test tools!
 </p>
 </details>
+<!-- markdownlint-enable MD029 -->
 
 Go to the server directory and generate the test tools:
 
@@ -213,6 +215,7 @@ Before the test can be run the Postgres and Redis also have to be started:
 ```bash
 docker-compose up --build --detach
 ```
+
 Now the test is ready to be run:
 
 ```bash
diff --git a/docs/06-concepts/19-testing/02-the-basics.md b/docs/06-concepts/19-testing/02-the-basics.md
@@ -206,6 +206,7 @@ dart test -t integration --concurrency=1
 
 For the other cases this is not an issue, as each `withServerpod` has its own transaction and will therefore be isolated.
 
+<!-- markdownlint-disable MD029 -->
 3. **Database exceptions that are quelled**: There is a specific edge case where the test tools behavior deviates from production behavior. See example below:
 
 ```dart
@@ -225,6 +226,7 @@ await transactionFuture;
 ```
 
 In production, the transaction call will throw if any database exception happened during its execution, _even_ if the exception was first caught inside the transaction. However, in the test tools this will not throw an exception due to how the nested transactions are emulated. Quelling exceptions like this is not best practise, but if the code under test does this setting `rollbackDatabase` to `RollbackDatabse.disabled` will ensure the code behaves like in production.
+<!-- markdownlint-enable MD029 -->
 
 ## Test exceptions
 
diff --git a/docs/index.md b/docs/index.md
@@ -166,4 +166,4 @@ This will start the Flutter app in your browser. It should look like this:
 
 ## Next steps
 
-The quickest way to learn Serverpod is to follow our 30-minute __[Getting Started](01-get-started/01-creating-endpoints.md)__ guide. This will give you an excellent overview of creating endpoints and models and working with the database. You will create a fun app that magically creates recipes from the ingredients you have in your fridge.
+The quickest way to learn Serverpod is to follow our 30-minute **[Getting Started](01-get-started/01-creating-endpoints.md)** guide. This will give you an excellent overview of creating endpoints and models and working with the database. You will create a fun app that magically creates recipes from the ingredients you have in your fridge.
