docs: fix admonition syntax, improve build instructions, and add --parallel flag (#628)

* docs: fix admonition syntax, improve build instructions, and add --parallel flag

* docs: add libglfw3 to Debian dependencies per author note

README.md

@@ -5,6 +5,8 @@
 - [Download](https://github.com/MihailRis/VoxelCore/releases/latest) | [Скачать](https://github.com/MihailRis/VoxelCore/releases/latest)
 - [Documentation](https://github.com/MihailRis/VoxelCore/blob/release-0.28/doc/en/main-page.md) | [Документация](https://github.com/MihailRis/VoxelCore/blob/release-0.28/doc/ru/main-page.md)
 
+---
+
 ## Build project in Linux
 
 ### Install libraries
@@ -13,13 +15,14 @@
 
 ```sh
 git clone https://github.com/skypjack/entt.git
-cd entt/build
+cd entt
-cmake -DCMAKE_BUILD_TYPE=Release -DENTT_INSTALL=on ..
+mkdir build && cd build
+cmake -DCMAKE_BUILD_TYPE=Release -DENTT_INSTALL=ON ..
 sudo make install
 ```
 
 > [!WARNING]
-> If you are using ALT Linux, you should not use this EnTT installation method
+> If you are using ALT Linux, do **not** use this EnTT installation method.
 
 #### ALT Linux based distros
 
@@ -31,11 +34,11 @@ apt-get install entt-devel libglfw3-devel libGLEW-devel libglm-devel libpng-deve
 #### Debian based distros
 
 ```sh
-sudo apt install libglfw3-dev libglfw3 libglew-dev libglm-dev libpng-dev libopenal-dev libluajit-5.1-dev libvorbis-dev libcurl4-openssl-dev
+sudo apt install libglfw3 libglfw3-dev libglew-dev libglm-dev libpng-dev libopenal-dev libluajit-5.1-dev libvorbis-dev libcurl4-openssl-dev
 ```
 
 > [!TIP]
-> CMake missing LUA_INCLUDE_DIR and LUA_LIBRARIES fix:
+> CMake missing `LUA_INCLUDE_DIR` and `LUA_LIBRARIES` fix:
 >
 > ```sh
 > sudo ln -s /usr/lib/x86_64-linux-gnu/libluajit-5.1.a /usr/lib/x86_64-linux-gnu/liblua5.1.a
@@ -45,24 +48,24 @@ sudo apt install libglfw3-dev libglfw3 libglew-dev libglm-dev libpng-dev libopen
 #### RHEL based distros
 
 ```sh
-sudo dnf install glfw-devel glfw glew-devel glm-devel libpng-devel libvorbis-devel openal-soft-devel luajit-devel libcurl-devel
+sudo dnf install glfw-devel glew-devel glm-devel libpng-devel libvorbis-devel openal-soft-devel luajit-devel libcurl-devel
 ```
 
 #### Arch based distros
 
-If you use X11
+If you use X11:
 
 ```sh
 sudo pacman -S glfw-x11 glew glm libpng libvorbis openal luajit libcurl
 ```
 
-If you use Wayland
+If you use Wayland:
 
 ```sh
 sudo pacman -S glfw-wayland glew glm libpng libvorbis openal luajit libcurl
 ```
 
-And you need entt. In yay you can use
+And install EnTT:
 
 ```sh
 yay -S entt
@@ -76,9 +79,14 @@ cd VoxelCore
 mkdir build
 cd build
 cmake -DCMAKE_BUILD_TYPE=Release ..
-cmake --build .
+cmake --build . --parallel
 ```
 
+> [!TIP]
+> Use `--parallel` to utilize all CPU cores during build.
+
+---
+
 ## Building project in macOS
 
 ### Install libraries
@@ -88,9 +96,7 @@ brew install glfw3 glew glm libpng libvorbis lua luajit libcurl openal-soft skyp
 ```
 
 > [!TIP]
-> If homebrew for some reason could not install the necessary packages:
+> If Homebrew fails to install `lua`, `luajit`, or `openal-soft`, download, compile, and install them manually.
-> ```lua luajit openal-soft```, then download, install and compile them manually
-> (Lua, LuaJIT and OpenAL).
 
 ### Building engine with CMake
 
@@ -100,90 +106,109 @@ cd VoxelCore
 mkdir build
 cd build
 cmake -DCMAKE_BUILD_TYPE=Release ..
-cmake --build .
+cmake --build . --parallel
 ```
 
+---
+
 ## Building in Windows
 
 > [!NOTE]
-> Requirement:
+> Requirements: **vcpkg**, **CMake**, **Git**, and **Visual Studio** (with C++ tools).
->
+
-> vcpkg, CMake, Git
 There are two options to use vcpkg:
-1. If you have Visual Studio installed, most likely the **VCPKG_ROOT** environment variable will already exist in **Developer Command Prompt for VS**
+
-2. If you want use **vcpkg**, install **vcpkg** from git to you system:
+1. If you have Visual Studio installed, the **VCPKG_ROOT** environment variable is often already set in the **Developer Command Prompt for VS**.
-```PowerShell
+2. Otherwise, install **vcpkg** manually:
-cd C:/
+
+```powershell
+cd C:\
 git clone https://github.com/microsoft/vcpkg.git
 cd vcpkg
 .\bootstrap-vcpkg.bat
 ```
-After installing **vcpkg**, setup env variable **VCPKG_ROOT** and add it to **PATH**:
+
-```PowerShell
+Then set the `VCPKG_ROOT` environment variable and add it to `PATH`:
-$env:VCPKG_ROOT = "C:\path\to\vcpkg"
+
+```powershell
+$env:VCPKG_ROOT = "C:\vcpkg"
 $env:PATH = "$env:VCPKG_ROOT;$env:PATH"
 ```
->[!TIP]
->For troubleshooting you can read full [documentation](https://learn.microsoft.com/ru-ru/vcpkg/get_started/get-started?pivots=shell-powershell) for **vcpkg**
 
-After installing **vcpkg** you can build project:
+> [!TIP]
-```PowerShell
+> For troubleshooting, refer to the official [vcpkg documentation](https://learn.microsoft.com/ru-ru/vcpkg/get_started/get-started?pivots=shell-powershell).
+
+After installing **vcpkg**, build the project:
+
+```powershell
 git clone --recursive https://github.com/MihailRis/VoxelCore.git
 cd VoxelCore
 cmake --preset default-vs-msvc-windows
 cmake --build --preset default-vs-msvc-windows
 ```
 
+> [!NOTE]
+> Make sure your `CMakeUserPresets.json` (if used) contains the correct `VCPKG_ROOT` path.
+
+---
+
 ## Build using Docker
 
-### Step 0. Install docker on your system
+> [!NOTE]
+> First, install Docker Engine: [https://docs.docker.com/engine/install](https://docs.docker.com/engine/install)
 
-See <https://docs.docker.com/engine/install>
+### On Linux
 
-### Do you have Linux
+#### Step 1. Build Docker image
-
-### Step 1. Build docker container
 
 ```sh
 docker build -t voxel-engine .
 ```
 
-### Step 2. Build project using the docker container
+#### Step 2. Build project inside container
 
 ```sh
-docker run --rm -it -v$(pwd):/project voxel-engine bash -c "cmake -DCMAKE_BUILD_TYPE=Release -Bbuild && cmake --build build"
+docker run --rm -it -v "$(pwd):/project" voxel-engine bash -c "cmake -DCMAKE_BUILD_TYPE=Release -Bbuild && cmake --build build --parallel"
 ```
 
-### Step 3. Run project using the docker container
+#### Step 3. Run the application (requires X11 forwarding)
 
 ```sh
-docker run --rm -it -v$(pwd):/project -v/tmp/.X11-unix:/tmp/.X11-unix -v${XAUTHORITY}:/home/user/.Xauthority:ro -eDISPLAY --network=host voxel-engine ./build/VoxelEngine
+docker run --rm -it \
+  -v "$(pwd):/project" \
+  -v /tmp/.X11-unix:/tmp/.X11-unix \
+  -v "$XAUTHORITY:/home/user/.Xauthority:ro" \
+  -e DISPLAY="$DISPLAY" \
+  --network=host \
+  voxel-engine ./build/VoxelEngine
 ```
 
-### Do you have Windows
+### On Windows
 
-### Step 1. You need to install VcXsrv
+> [!NOTE]
+> You need an X server like **VcXsrv** to display the GUI.
 
-### Step 2. Run VcXsrv with the command
+#### Step 1. Install and run VcXsrv
 
+Launch with:
 ```powershell
 .\vcxsrv.exe :0 -multiwindow -ac
 ```
 
-### Step 3. Build docker container
+#### Step 2. Build Docker image
 
 ```powershell
 docker build -t voxel-engine .
 ```
 
-### Step 4. Build project using the docker container
+#### Step 3. Build project
 
 ```powershell
-docker run --rm -it -v "${PWD}:/project" voxel-engine bash -c "cmake -DCMAKE_BUILD_TYPE=Release -Bbuild && cmake --build build"
+docker run --rm -it -v "${PWD}:/project" voxel-engine bash -c "cmake -DCMAKE_BUILD_TYPE=Release -Bbuild && cmake --build build --parallel"
 ```
 
-### Step 5. Run project using the docker container
+#### Step 4. Run the application
 
 ```powershell
-docker run --rm -it -v "${PWD}:/project" -e DISPLAY=host.docker.internal:0.0 --network host voxel-engine ./build/VoxelEngine
+docker run --rm -it -v "${PWD}:/project" -e DISPLAY=host.docker.internal:0.0 --network=host voxel-engine ./build/VoxelEngine
 ```