chore: cleaning up the docs (#837)

* chore: fix indents in diff code blocks

* chore: replace patch by diff code blocks

* chore: fix missed punctuation in docs

* chore: fix markdownlint-enable comment indent in docs/tls.md

* chore: fix typos in docs

Author: 7-zete-7

docs/alpine.md

@@ -10,7 +10,7 @@ To switch to Alpine-based images, apply the following changes to the `Dockerfile
 
 <!-- markdownlint-disable MD010 -->
 
-```patch
+```diff
 -FROM dunglas/frankenphp:1-php8.4 AS frankenphp_upstream
 +FROM dunglas/frankenphp:1-php8.4-alpine AS frankenphp_upstream
 

docs/extra-services.md

@@ -22,4 +22,4 @@ The currently supported packages are:
 > [!WARNING]
 >
 > We recommend that you use the `composer require` command inside the container
-> in development mode so that recipes can be applied correctly
+> in development mode so that recipes can be applied correctly.

docs/makefile.md

@@ -19,12 +19,16 @@ You can also find a more complete example in this [snippet](https://www.strangeb
 If you want to run make from within the `php` container, in the [Dockerfile](/Dockerfile),
 add:
 
+<!-- markdownlint-disable MD010 -->
+
 ```diff
-gettext \
-git \
-+make \
+ 	gettext \
+ 	git \
++	make \
 ```
 
+<!-- markdownlint-enable MD010 -->
+
 And rebuild the PHP image.
 
 > [!NOTE]

docs/mysql.md

@@ -18,37 +18,37 @@ Change the database image to use MySQL instead of PostgreSQL in `compose.yaml`:
 <!-- markdownlint-disable MD013 -->
 
 ```diff
-###> doctrine/doctrine-bundle ###
--   image: postgres:${POSTGRES_VERSION:-16}-alpine
-+   image: mysql:${MYSQL_VERSION:-8}
-    environment:
--     POSTGRES_DB: ${POSTGRES_DB:-app}
-+     MYSQL_DATABASE: ${MYSQL_DATABASE:-app}
-      # You should definitely change the password in production
-+     MYSQL_RANDOM_ROOT_PASSWORD: "true"
--     POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-!ChangeMe!}
-+     MYSQL_PASSWORD: ${MYSQL_PASSWORD:-!ChangeMe!}
--     POSTGRES_USER: ${POSTGRES_USER:-app}
-+     MYSQL_USER: ${MYSQL_USER:-app}
-    healthcheck:
--     test: ["CMD", "pg_isready", "-d", "${POSTGRES_DB:-app}", "-U", "${POSTGRES_USER:-app}"]
-+     test: ["CMD", "mysqladmin" ,"ping", "-h", "localhost"]
-      timeout: 5s
-      retries: 5
-      start_period: 60s
-    volumes:
--     - database_data:/var/lib/postgresql/data:rw
-+     - database_data:/var/lib/mysql:rw
-      # You may use a bind-mounted host directory instead, so that it is harder to accidentally remove the volume and lose all your data!
--     # - ./docker/db/data:/var/lib/postgresql/data:rw
-+     # - ./docker/db/data:/var/lib/mysql:rw
-###< doctrine/doctrine-bundle ###
+ ###> doctrine/doctrine-bundle ###
+-    image: postgres:${POSTGRES_VERSION:-16}-alpine
++    image: mysql:${MYSQL_VERSION:-8}
+     environment:
+-      POSTGRES_DB: ${POSTGRES_DB:-app}
++      MYSQL_DATABASE: ${MYSQL_DATABASE:-app}
+       # You should definitely change the password in production
++      MYSQL_RANDOM_ROOT_PASSWORD: "true"
+-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-!ChangeMe!}
++      MYSQL_PASSWORD: ${MYSQL_PASSWORD:-!ChangeMe!}
+-      POSTGRES_USER: ${POSTGRES_USER:-app}
++      MYSQL_USER: ${MYSQL_USER:-app}
+     healthcheck:
+-      test: ["CMD", "pg_isready", "-d", "${POSTGRES_DB:-app}", "-U", "${POSTGRES_USER:-app}"]
++      test: ["CMD", "mysqladmin" ,"ping", "-h", "localhost"]
+       timeout: 5s
+       retries: 5
+       start_period: 60s
+     volumes:
+-      - database_data:/var/lib/postgresql/data:rw
++      - database_data:/var/lib/mysql:rw
+       # You may use a bind-mounted host directory instead, so that it is harder to accidentally remove the volume and lose all your data!
+-      # - ./docker/db/data:/var/lib/postgresql/data:rw
++      # - ./docker/db/data:/var/lib/mysql:rw
+ ###< doctrine/doctrine-bundle ###
 ```
 
 <!-- markdownlint-enable MD013 -->
 
 Depending on the database configuration,
-modify the environment in the same file at `services.php.environment.DATABASE_URL`
+modify the environment in the same file at `services.php.environment.DATABASE_URL`:
 
 ```yaml
 DATABASE_URL: mysql://${MYSQL_USER:-app}:${MYSQL_PASSWORD:-!ChangeMe!}@database:3306/${MYSQL_DATABASE:-app}?serverVersion=${MYSQL_VERSION:-8}&charset=${MYSQL_CHARSET:-utf8mb4}
@@ -57,21 +57,21 @@ DATABASE_URL: mysql://${MYSQL_USER:-app}:${MYSQL_PASSWORD:-!ChangeMe!}@database:
 Since we changed the port, we also have to define this in the `compose.override.yaml`:
 
 ```diff
-###> doctrine/doctrine-bundle ###
-  database:
-    ports:
--     - "5432"
-+     - "3306"
-###< doctrine/doctrine-bundle ###
+ ###> doctrine/doctrine-bundle ###
+   database:
+     ports:
+-      - "5432"
++      - "3306"
+ ###< doctrine/doctrine-bundle ###
 ```
 
 Last but not least, we need to install the MySQL driver in `Dockerfile`:
 
 ```diff
-###> doctrine/doctrine-bundle ###
+ ###> doctrine/doctrine-bundle ###
 -RUN install-php-extensions pdo_pgsql
 +RUN install-php-extensions pdo_mysql
-###< doctrine/doctrine-bundle ###
+ ###< doctrine/doctrine-bundle ###
 ```
 
 ## Change Environment

docs/options.md

@@ -71,7 +71,7 @@ to inject options block, directive or configuration.
 > [!TIP]
 >
 > All the following environment variables can be defined in your `.env` file
-> at the root of the project to keep them persistent at each startup
+> at the root of the project to keep them persistent at each startup.
 
 <!-- markdownlint-disable MD013 -->
 

docs/tls.md

@@ -53,7 +53,7 @@ do as follows:
    mkcert -cert-file frankenphp/certs/tls.pem -key-file frankenphp/certs/tls.key "server-name.localhost"
    ```
 
-     <!-- markdownlint-enable MD013 -->
+   <!-- markdownlint-enable MD013 -->
 
 4. Add these lines to the `./compose.override.yaml` file about `CADDY_SERVER_EXTRA_DIRECTIVES`
    environment and volume for the `php` service:

docs/troubleshooting.md

@@ -73,7 +73,7 @@ This means you have to run the following command in order to build your image:
 docker compose -f compose.yaml -f compose.prod.yaml build --pull --no-cache
 ```
 
-> [!WARINING]
+> [!WARNING]
 >
 > The order of `-f` arguments matters.
 

docs/xdebug.md

@@ -79,7 +79,7 @@ You can now use the debugger!
    ```
 
 3. Use [Run and Debug](https://code.visualstudio.com/docs/debugtest/debugging#_start-a-debugging-session)
-   options and run `Listen for Xdebug` command to listen for upcomming connections
+   options and run `Listen for Xdebug` command to listen for upcoming connections
    with [the **Xdebug extension**](https://xdebug.org/docs/step_debug#browser-extensions)
    installed and active.