PG-798 Restructured docs 13 (#606)

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

.vscode/settings.json

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

CONTRIBUTING.md

@@ -5,16 +5,24 @@ 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/PG/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 
 
 Percona Distribution for PostgreSQL documentation is written in [Markdown](https://www.markdownguide.org/basic-syntax/) language, so you can 
 [edit it online via GitHub](#edit-documentation-online-vi-github). If you wish to have more control over the doc process, jump to how to [edit documentation locally](#edit-documentation-locally). 
 
 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,12 +35,13 @@ Each version has a branch in the repository named accordingly:
 - 13
 - 14
 - 15
+- 16
 
 The source .md files are in the ``docs`` directory. 
 
 ### Edit documentation online via GitHub
 
-1. Click the **Edit this page** icon next to the page title. The Markdown file of the page opens in GitHub editor in your browser. If you haven’t worked with the repository before, GitHub creates a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you.
+1. Click the **Edit this page** link on the sidebar. The Markdown file of the page opens in GitHub editor in your browser. If you haven’t worked with the repository before, GitHub creates a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you.
 
 2. Edit the page. You can check your changes on the **Preview** tab.
 
@@ -125,15 +134,16 @@ The PDF document is in the ``site/pdf`` folder.
 2. Install [MkDocs](https://www.mkdocs.org/getting-started/#installation).
 3. While in the root directory of the doc project, run the following command to build the documentation:
 
-```sh
-mkdocs build 
-```
+    ```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:
 
-```sh
-mkdocs serve 
-```
+    ```sh
+    mkdocs serve 
+    ```
 
 6. To build the PDF documentation, do the following:
    - Install [mkdocs-with-pdf plugin](https://pypi.org/project/mkdocs-with-pdf/)

docs/apt.md

@@ -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,8 +40,8 @@ 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