PG-798 Restructured docs for 12 (#607)

* Restructured docs
* Reworked the What's in it section
* Added power number
* Added icons

.python-version

@@ -0,0 +1 @@
+3.11.1

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "cSpell.words": [
+        "Quickstart"
+    ]
+}

CONTRIBUTING.md

@@ -5,7 +5,15 @@ Thank you for deciding to contribute and help us improve Percona Distribution fo
 
 We welcome contributors from all users and community. By contributing, you agree to the [Percona Community code of conduct](https://github.com/percona/community/blob/main/content/contribute/coc.md).
 
-This repository contains the source file for `pg_stat_monitor` documentation and this document explains how you can contribute to it. 
+You can contribute to documentation in the following ways:
+
+1. **Request a doc change through a Jira issue**. If you’ve spotted a doc issue (a typo, broken links, inaccurate instructions, etc.) but don’t have time nor desire to fix it yourself - let us know about it.
+
+	- Click the **Submit DOC bug** link on the sidebar. This opens the [Jira issue tracker](https://jira.percona.com/projects/DISTPG/issues) for the doc project.
+	- Sign in (create a Jira account if you don’t have one) and click **Create** to create an issue.
+	- Describe the issue you have detected in the Summary, Description, Steps To Reproduce, Affects Version fields.
+
+2. **[Contribute to documentation yourself](#contribute-to-documentation-yourself)**. There is the **Edit this page** link that leads you to the source file of the page on GitHub. There you make changes, create a pull request that we review and add to the doc project. For details how to do it, read on.
 
 ## Contribute to documentation 
 
@@ -14,7 +22,8 @@ Percona Distribution for PostgreSQL documentation is written in [Markdown](https
 
 To contribute to the documentation, you should be familiar with the following technologies:
 
-- [MkDocs](https://www.mkdocs.org/getting-started/) documentation generator. We use it to convert source ``.md`` files to .html and PDF documents.
+- [Markdown](https://www.markdownguide.org/basic-syntax/) markup language. It is used to write the documentation.
+- [MkDocs](https://www.mkdocs.org/getting-started/) documentation generator. We use it to convert source ``.md`` files to html and PDF documents.
 - [git](https://git-scm.com/) and [GitHub](https://guides.github.com/activities/hello-world/)
 - [Docker](https://docs.docker.com/get-docker/). It allows you to run MkDocs in a virtual environment instead of installing it and its dependencies on your machine.
 
@@ -27,6 +36,7 @@ Each version has a branch in the repository named accordingly:
 - 13
 - 14
 - 15
+- 16
 
 The source .md files are in the ``docs`` directory. 
 
@@ -128,6 +138,7 @@ The PDF document is in the ``site/pdf`` folder.
 ```sh
 mkdocs build 
 ```
+
 4. Go to the ``site`` directory and open the ``index.html`` file in your web browser to see the documentation.
 5. To automatically rebuild the documentation and reload the browser as you make changes, run the following command:
 

docs/apt.md

@@ -1,6 +1,6 @@
 # Install Percona Distribution for PostgreSQL on Debian and Ubuntu
 
-This document describes how to install Percona Distribution for PostgreSQL from Percona repositories on DEB-based distributions such as Debian and Ubuntu.  [Read more about Percona repositories :material-arrow-top-right:](repo-overview.md).
+This document describes how to install Percona Distribution for PostgreSQL from Percona repositories on DEB-based distributions such as Debian and Ubuntu.  [Read more about Percona repositories](repo-overview.md).
 
 ## Preconditions
 
@@ -11,7 +11,7 @@ This document describes how to install Percona Distribution for PostgreSQL from
 
 Run all the commands in the following sections as root or using the `sudo` command:
 
-### Configure Percona repository
+### Configure Percona repository {.power-number}
 
 1. Install the `percona-release` repository management tool to subscribe to Percona repositories:
 
@@ -53,6 +53,9 @@ Run all the commands in the following sections as root or using the `sudo` comma
 
 === "Install packages individually"
 
+    Run the following commands:
+    {.power-number}
+
      1. Install the PostgreSQL server package:
 
          ```{.bash data-prompt="$"}
@@ -146,33 +149,10 @@ The installation process automatically initializes and starts the default databa
 $ sudo systemctl status postgresql.service
 ```
 
-### Connect to the PostgreSQL server
-
-By default, `postgres` user and `postgres` database are created in PostgreSQL upon its installation and initialization. This allows you to connect to the database as the `postgres` user.
-
-```{.bash data-prompt="$"}
-$ sudo su postgres
-```
-
-Open the PostgreSQL interactive terminal:
-
-```{.bash data-prompt="$"}
-$ psql
-```
-
-!!! hint
-
-    You can connect to `psql` as the `postgres` user in one go:
-
-    ```{.bash data-prompt="$"}
-    $ sudo su - postgres -c psql
-    ```
-
-To exit the `psql` terminal, use the following command:
-
-```{.bash data-prompt="$"}
-$ \q
-```
+Congratulations! Your Percona Distribution for PostgreSQL is up and running.
 
+## Next steps
 
+[Enable extensions :material-arrow-right:](enable-extensions.md){.md-button}
 
+[Connect to PostgreSQL :material-arrow-right:](connect.md){.md-button}

docs/connect.md

@@ -0,0 +1,73 @@
+# Connect to the PostgreSQL server
+
+With PostgreSQL server up and running, let's connect to it.
+
+By default, the `postgres` user and the `postgres` database are created in PostgreSQL upon its installation and initialization. This allows you to connect to the database as the `postgres` user.
+{.power-number}
+
+1. Switch to the `postgres` user.
+
+    ```{.bash data-prompt="$"}
+    $ sudo su postgres
+    ```
+
+2. Open the PostgreSQL interactive terminal `psql`:
+
+    ```{.bash data-prompt="$"}
+    $ psql
+    ```
+
+    <i info>:material-information: Hint:</i> You can connect to `psql` as the `postgres` user in one go: 
+
+    ```{.bash data-prompt="$"}
+    $ sudo su - postgres -c psql
+    ```
+
+
+## Basic `psql` commands
+
+While connected to PostgreSQL, let's practice some basic `psql` commands to interact with the database:
+
+1. List databases:
+
+    ```{.bash data-prompt="$"}
+    $ \l
+    ```
+
+2. Display tables in the current database:
+
+    ```{.bash data-prompt="$"}
+    $ \dt
+    ```
+
+3. Display columns in a table
+
+    ```{.bash data-prompt="$"}
+    $ \d <table_name>
+    ```
+
+4. Switch databases
+
+    ```{.bash data-prompt="$"}
+    $ \c <database_name>
+    ```
+
+5. Display users and roles
+
+    ```{.bash data-prompt="$"}
+    $ \du
+    ```
+
+6. Exit the `psql` terminal:
+
+    ```{.bash data-prompt="$"}
+    $ \q
+    ```
+
+To learn more about using `psql`, see [`psql` :octicons-link-external-16:](https://www.postgresql.org/docs/current/app-psql.html) documentation.
+
+Congratulations! You have connected to PostgreSQL and learned some essential `psql` commands. 
+
+## Next steps
+
+[Manipulate data in PostgreSQL :material-arrow-right:](crud.md){.md-button}

docs/crud.md

@@ -0,0 +1,112 @@
+# Manipulate data in PostgreSQL
+
+On the previous step, you have [connected to PostgreSQL](connect.md) as the superuser `postgres`. Now, let's insert some sample data and operate with it in PostgreSQL.
+
+## Create a database
+
+Let's create the database `test`. Use the CREATE DATABASE command:
+
+```sql
+CREATE DATABASE test;
+```
+
+## Create a table
+
+Let's create a sample table `Customers` in the `test` database using the following command:
+
+```sql
+CREATE TABLE customers (
+    id SERIAL PRIMARY KEY,  -- 'id' is an auto-incrementing integer
+    first_name VARCHAR(50), -- 'first_name' is a string with a maximum length of 50 characters
+    last_name VARCHAR(50),  -- 'last_name' is a string with a maximum length of 50 characters
+    email VARCHAR(100)      -- 'email' is a string with a maximum length of 100 characters
+);
+```
+
+<i info>:material-information: Hint:</i>Having issues with table creation? Check our [Troubleshooting guide](troubleshooting.md)
+
+## Insert the data
+
+Populate the table with the sample data as follows:
+
+```sql
+INSERT INTO customers (first_name, last_name, email)
+VALUES 
+    ('John', 'Doe', '[email protected]'),  -- Insert a new row
+    ('Jane', 'Doe', '[email protected]');
+    ('Alice', 'Smith', '[email protected]');
+```
+
+## Query data
+
+Let's verify the data insertion by querying it:
+
+```sql
+SELECT * FROM customers;
+```
+
+??? example "Expected output"
+
+    ```{.sql .no-copy}
+    id | first_name | last_name |          email
+    ----+------------+-----------+-------------------------
+      1 | John       | Doe       | [email protected]
+      2 | Jane       | Doe       | [email protected]
+      3 | Alice      | Smith     | [email protected]
+    (3 rows)
+    ```
+
+## Update data
+
+Let's update John Doe's record with a new email address.
+
+1. Use the UPDATE command for that:
+
+    ```sql
+    UPDATE customers 
+    SET email = '[email protected]'
+    WHERE first_name = 'John' AND last_name = 'Doe';
+    ```
+
+2. Query the table to verify the updated data:
+
+    ```sql
+    SELECT * FROM customers WHERE first_name = 'John' AND last_name = 'Doe';
+    ```
+
+    ??? example "Expected output"   
+
+        ```{.sql .no-copy}
+         id | first_name | last_name |          email
+        ----+------------+-----------+-------------------------
+          2 | Jane       | Doe       | [email protected]
+          3 | Alice      | Smith     | [email protected]
+          1 | John       | Doe       | [email protected]
+        (3 rows)
+        ```
+
+## Delete data
+
+Use the DELETE command to delete rows. For example, delete the record of Alice Smith:
+
+```sql
+DELETE FROM Customers WHERE first_name = 'Alice' AND last_name = 'Smith';
+```
+
+If you wish to delete the whole table, use the `DROP TABLE` command instead as follows:
+
+```sql
+DROP TABLE customers;
+```
+
+To delete the whole database, use the DROP DATABASE command:
+
+```sql
+DROP DATABASE test;
+```
+
+Congratulations! You have used basic create, read, update and delete (CRUD) operations to manipulate data in Percona Distribution for PostgreSQL. To deepen your knowledge, see the [data manipulation :octicons-link-external-16:](https://www.postgresql.org/docs/{{pgversion}}/dml.html) section in PostgreSQL documentation.
+
+## Next steps
+
+[What's next?](whats-next.md)(.md-button)

docs/docker.md

@@ -1,12 +1,12 @@
 # Run Percona Distribution for PostgreSQL in a Docker container
 
-Docker images of Percona Distribution for PostgreSQL are hosted publicly on [Docker Hub](https://hub.docker.com/r/percona/percona-distribution-postgresql/).
+Docker images of Percona Distribution for PostgreSQL are hosted publicly on [Docker Hub :octicons-link-external-16:](https://hub.docker.com/r/percona/percona-distribution-postgresql/).
 
-For more information about using Docker, see the [Docker Docs](https://docs.docker.com/).
+For more information about using Docker, see the [Docker Docs :octicons-link-external-16:](https://docs.docker.com/).
 
 !!! note ""
 
-    Make sure that you are using the latest version of Docker. The ones provided via `apt` and `yum` may be outdated and cause errors.
+    Make sure that you are using [the latest version of Docker :octicons-link-external-16:](https://docs.docker.com/get-docker/). The ones provided via `apt` and `yum` may be outdated and cause errors.
 
     By default, Docker pulls the image from Docker Hub if it is not available locally.
 
@@ -28,7 +28,7 @@ For more information about using Docker, see the [Docker Docs](https://docs.dock
     | `percona-pg_repack{{pgversion}}`| rebuilds PostgreSQL database objects.| 
     | `percona-wal2json{{pgversion}}` | a PostgreSQL logical decoding JSON output plugin.|
 
-## Start the container
+## Start the container {.power-number}
 
 1. Start a Percona Distribution for PostgreSQL container as follows:
 
@@ -40,7 +40,7 @@ For more information about using Docker, see the [Docker Docs](https://docs.dock
 
     * `container-name` is the name you assign to your container
     * `POSTGRES_PASSWORD` is the superuser password 
-    * `tag-multi` is the tag specifying the version you need. For example, `{{dockertag}}-multi`. The `multi` part of the tag serves to identify the architecture (x86_64 or ARM64) and pull the respective image. See the [full list of tags](https://hub.docker.com/r/percona/percona-distribution-postgresql/tags/).    
+    * `tag-multi` is the tag specifying the version you need. For example, `{{dockertag}}-multi`. The `multi` part of the tag serves to identify the architecture (x86_64 or ARM64) and pull the respective image. See the [full list of tags :octicons-link-external-16:](https://hub.docker.com/r/percona/percona-distribution-postgresql/tags/).     
 
 
     !!! tip     

docs/enable-extensions.md

@@ -12,18 +12,18 @@ While setting up a high availability PostgreSQL cluster with Patroni, you will n
 
 - Distributed Configuration Store (DCS). Patroni supports such DCSs as etcd, zookeeper, Kubernetes though [etcd](https://etcd.io/) is the most popular one. It is available within Percona Distribution for PostgreSQL for all supported operating systems.
 
-- [HAProxy](http://www.haproxy.org/).
+- [HAProxy :octicons-link-external-16:](http://www.haproxy.org/).
 
 See the configuration guidelines for [Debian and Ubuntu](solutions/ha-setup-apt.md) and [RHEL and CentOS](solutions/ha-setup-yum.md). 
 
 
 !!! admonition "See also"
 
-    - [Patroni documentation](https://patroni.readthedocs.io/en/latest/SETTINGS.html#settings)
+    - [Patroni documentation :octicons-link-external-16:](https://patroni.readthedocs.io/en/latest/SETTINGS.html#settings)
 
     - Percona Blog: 
 
-        - [PostgreSQL HA with Patroni: Your Turn to Test Failure Scenarios](https://www.percona.com/blog/2021/06/11/postgresql-ha-with-patroni-your-turn-to-test-failure-scenarios/) 
+        - [PostgreSQL HA with Patroni: Your Turn to Test Failure Scenarios :octicons-link-external-16:](https://www.percona.com/blog/2021/06/11/postgresql-ha-with-patroni-your-turn-to-test-failure-scenarios/) 
         
 **pgBadger**
 
@@ -41,19 +41,19 @@ log_autovacuum_min_duration = 0
 log_error_verbosity = default
 ```
 
-For details about each option, see [pdBadger documentation](https://github.com/darold/pgbadger/#POSTGRESQL-CONFIGURATION).
+For details about each option, see [pdBadger documentation :octicons-link-external-16:](https://github.com/darold/pgbadger/#POSTGRESQL-CONFIGURATION).
 
 **pgAudit set-user**
 
-Add the `set-user` to `shared_preload_libraries` in `postgresql.conf`. The recommended way is to use the [ALTER SYSTEM](https://www.postgresql.org/docs/14/sql-altersystem.html) command. [Connect to psql](#connect-to-the-postgresql-server) and use the following command:
+Add the `set-user` to `shared_preload_libraries` in `postgresql.conf`. The recommended way is to use the [ALTER SYSTEM :octicons-link-external-16:](https://www.postgresql.org/docs/12/sql-altersystem.html) command. [Connect to psql](connect.md) and use the following command:
 
 ```sql
 ALTER SYSTEM SET shared_preload_libraries = 'set-user';
 ```
 
 Start / restart the server to apply the configuration.
 
-You can fine-tune user behavior with the [custom parameters](https://github.com/pgaudit/set_user#configuration-options) supplied with the extension.
+You can fine-tune user behavior with the [custom parameters :octicons-link-external-16:](https://github.com/pgaudit/set_user#configuration-options) supplied with the extension.
 
 **wal2json**
 
@@ -62,3 +62,7 @@ After the installation, enable the following option in `postgresql.conf` configu
 ```
 wal_level = logical
 ```
+
+## Next steps 
+
+[Connect to PostgreSQL :material-arrow-right:](connect.md){.md-button}