feat: update docs

Author: fiftin

src/administration-guide/api.md

@@ -72,6 +72,8 @@ The command should return something similar to:
 
 `[{"id":"`**`YOUR_ACCESS_TOKEN`**`","created":"2017-03-11T13:13:13Z","expired":false,"user_id":1}]`
 
+---
+
 ## Using token to make API requests
 
 Once you have your API token, include it in the **Authorization** header to authenticate your requests.
@@ -89,6 +91,8 @@ curl -v -XPOST \
 http://localhost:3000/api/project/1/tasks
 ```
 
+---
+
 ## Expiring an API token
 
 If you no longer need the token, you should expire it to keep your account secure.

src/administration-guide/configuration.md

@@ -72,8 +72,9 @@ Full list of available configuration options:
 | <br>`auth.totp.enabled`         <hr> `SEMAPHORE_TOTP_ENABLED` <br><br> |   |
 | <br>`auth.totp.allow_recovery`  <hr> `SEMAPHORE_TOTP_ALLOW_RECOVERY` <br><br> |   |
 
+## Frequently asked questions
 
-## Public URL
+### 1. How to configure a public URL for Semaphore UI
 
 If you use nginx or other web server before Semaphore, you should provide configuration option `web_host`.
 

src/administration-guide/configuration/config-file.md

@@ -26,8 +26,8 @@ Use the following commands to generate the configuration file interactively:
 ### Generate via Web
 
 Alternatively, you can use the web-based interactive configurator:
-* [Server Configurator](https://semaphoreui.com/install/binary/2_13/config)
-* [Runner Configurator](https://semaphoreui.com/install/binary/2_13/runner)
+* [Server configurator](https://semaphoreui.com/install/binary/2_13/config)
+* [Runner configurator](https://semaphoreui.com/install/binary/2_13/runner)
 
 ## Configuration file example
 

src/administration-guide/installation/docker.md

@@ -79,6 +79,4 @@ Run the following command to start Semaphore with configured database (MySQL or
 docker-compose up
 ```
 
- Semaphore will be available via the following URL [http://localhost:3000](http://localhost:3000).
-
-For more information about the Docker Compose, see the [Docker Compose reference](https://docs.docker.com/compose/).
+ Semaphore will be available via the following URL [http://localhost:3000](http://localhost:3000).

src/faq/troubleshooting.md

@@ -1,14 +1,14 @@
 # Troubleshooting
 
-## Renner prints error 404
+## 1. Renner prints error 404
 
 ### How to fix
 
 [Getting 401 error code from Runner](https://github.com/semaphoreui/semaphore/discussions/1873?converting=1)
 
 ---
 
-## Gathering Facts issue for localhost
+## 2. Gathering Facts issue for localhost
 
 The issue can occur on Semaphore UI installed via [Snap](https://snapcraft.io/semaphore) or [Docker](https://hub.docker.com/r/semaphoreui/semaphore).
 
@@ -44,7 +44,7 @@ There are two ways:
 127.0.0.1 ansible_connection=ssh ansible_ssh_user=your_localhost_user
 ```
 ---
-## panic: pq: SSL is not enabled on the server
+## 4. panic: pq: SSL is not enabled on the server
 
 This means that your Postgres doesn't work by SSL.
 
@@ -63,8 +63,12 @@ Add option `sslmode=disable` to the configuration file:
 		}
 	},
 ```
+
+
 ---
-## fatal: bad numeric config value '0' for 'GIT_TERMINAL_PROMPT': invalid unit
+
+
+## 5. fatal: bad numeric config value '0' for 'GIT_TERMINAL_PROMPT': invalid unit
 
 This means that you are trying to access a repository over HTTPS that requires authentication.
 
@@ -76,9 +80,12 @@ This means that you are trying to access a repository over HTTPS that requires a
 * Specify the password. You can't use your account password for GitHub/BitBucket, you should use a Personal Access Token (PAT) instead of it. Read more [here](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).
 * After creating the key, go to the **Repositories** screen, find your repository and specify the key.
 
+
 ---
 
-## unable to read LDAP response packet: unexpected EOF
+
+
+## 6. unable to read LDAP response packet: unexpected EOF
 
 Most likely, you are trying to connect to the LDAP server using an insecure method, although it expects a secure connection (via TLS).
 
@@ -94,7 +101,7 @@ Enable TLS in your `config.json` file:
 
 ---
 
-## LDAP Result Code 49 "Invalid Credentials"
+## 7. LDAP Result Code 49 "Invalid Credentials"
 
 You have the wrong password or `binddn`.
 
@@ -118,6 +125,6 @@ You also can read the following articles:
 
 ---
 
-## LDAP Result Code 32 "No Such Object"
+## 8. LDAP Result Code 32 "No Such Object"
 
 Coming soon.

src/user-guide/repositories.md

@@ -21,26 +21,32 @@ For Remote Repositories that do not have authentication, you can create a Key wi
 
 ## Creating a New Repository
 1. Make sure you have configured the key for the Repository you are about to add in the key store section.
+
 2. Go to the Repositories section of Semaphore, click the **New Repository** button in the upper right hand corner.
+
 3. Configure the Repository:
-  * Name Repository
-  * Add the URL. The URL must start with the following:
-    * `/path/to/the/repo` for a local folder on the file system
-    * `https://` for a remote Git Repository accessed over HTTPS
-    * `ssh://` for a remote Git Repository accessed over SSH
-    * `file://` for a local Git Repository
-    * `git://` for a remote Git Repository accessed over Git protocol
-  * Set the branch of the Repository, if you are not sure what it should be, it is probably master or main
-  * Select the **Access Key** you configured prior to setting up this Repository.
+    * Name Repository
+    * Add the URL. The URL must start with the following:
+        * `/path/to/the/repo` for a local folder on the file system
+        * `https://` for a remote Git Repository accessed over HTTPS
+        * `ssh://` for a remote Git Repository accessed over SSH
+        * `file://` for a local Git Repository
+        * `git://` for a remote Git Repository accessed over Git protocol
+    * Set the branch of the Repository, if you are not sure what it should be, it is probably master or main
+    * Select the **Access Key** you configured prior to setting up this Repository.
+
 4. Click Save once everything is configured.
 
 ## Editing an Existing Repository
 1. Go to the Repositories section of Semaphore.
+
 2. Click on the pencil icon next to the Repository you wish to change, then you will be presented with the Repository configuration.
 
 ## Deleting a Repository
 Make sure the Repository that is about to be delete is not in use by any Task Templates.
 A Repository cannot be deleted if it is used in any Task Templates:
 1. Go to the Repositories section of Semaphore.
+
 2. Click on the trash can icon on of the Repository you wish to delete.
+
 3. Click Yes on the confirmation pop-up if you are sure you want this Repository to be deleted.

src/user-guide/team.md

@@ -2,20 +2,36 @@
 
 In Semaphore UI, every project is associated with a **Team**. Only team members and admins can access the project. Each member of the team is assigned one of four predefined roles, which govern their level of access and the actions they can perform.
 
-> **Tip:** To avoid losing access to a project, it’s recommended to have at least two team members with the **Owner** role.
+<div class="warning">
+To avoid losing access to a project, it’s recommended to have at least two team members with the <b>Owner</b> role.
+</div>
 
 ---
 
 ## Team roles
 
-Every team member has exactly one of these four roles: **Owner**, **Manager**, **Task Runner**, or **Guest**. Below are detailed descriptions of each role and its permissions.
+Every team member has exactly one of these four roles:
+
+- **Owner**
+- **Manager**
+- **Task Runner**
+- **Guest**
+
+Below are detailed descriptions of each role and its permissions.
 
 ### Owner
 
-- **Full permissions:** Owners can do anything within the project, including managing roles, adding/removing members, and configuring any project settings.
-- **Multiple owners:** A project can have multiple Owners, ensuring there is more than one person with full privileges.
-- **Restrictions on self-removal:** An Owner cannot remove themselves if they are the only Owner of the project. This prevents the project from being left without an Owner.
-- **Managing other wwners:** Owners can manage (including remove or change roles of) all team members, including other Owners.
+- **Full permissions**<br>
+  Owners can do anything within the project, including managing roles, adding/removing members, and configuring any project settings.
+
+- **Multiple owners**<br>
+  A project can have multiple Owners, ensuring there is more than one person with full privileges.
+
+- **Restrictions on self-removal**<br>
+  An Owner cannot remove themselves if they are the only Owner of the project. This prevents the project from being left without an Owner.
+
+- **Managing other wwners**<br>
+  Owners can manage (including remove or change roles of) all team members, including other Owners.
 
 ### Manager
 
@@ -30,21 +46,27 @@ Every team member has exactly one of these four roles: **Owner**, **Manager**, *
 ### Task Runner
 
 - **Run tasks:** Task Runners can execute any task template that exists within the project.
+
 - **Read-only for other resources:** While they can run tasks, they only have read‐only access to other resources such as inventory, variables, repositories, etc.
+
 - **Typical use case:** Developers or QA engineers who need to trigger and monitor tasks but do not need the ability to modify project settings or manage team membership.
 
 ### Guest
 
 - **Read-only access:** Guests have read-only access to all project resources (e.g., viewing logs, inventories, dashboards).
+
 - **No write permissions:** They cannot modify settings, run tasks, or change roles.
+
 - **Typical use case:** Stakeholders or other collaborators who only need to view project status and details without making changes.
 
 ---
 
 ## Managing team members
 
 - **Inviting new members:** **Owners** and **Managers** can invite new users to join the team and assign them an initial role.
+
 - **Changing roles:** Owners can always change the roles of any team member. Managers can change the roles of **Task Runners** and **Guests**, but **not** other Managers or Owners.
+
 - **Removing members:** Owners and Managers can remove team members with lower roles.  
   - An Owner can remove anyone (including other Owners), but cannot remove themselves if they are the sole Owner.
   - A Manager can remove **Task Runners** and **Guests**, but **not** other Managers or Owners.
@@ -68,23 +90,17 @@ Every team member has exactly one of these four roles: **Owner**, **Manager**, *
 
 ## Frequently asked questions
 
-**1. Can an Owner remove another Owner?**  
+### 1. Can an Owner remove another Owner?
 Yes, an Owner can remove or change the role of any other Owner, unless they are the only remaining Owner in the project.
 
-**2. Who can delete the project?**  
+### 2. Who can delete the project?
 Only **Owners** can delete a project.
 
-**3. Can Managers add or remove other Managers?**  
+### 3. Can Managers add or remove other Managers?
 No. Managers can only add or remove users with **Task Runner** or **Guest** roles. To manage Owners or other Managers, you must be an Owner.
 
-**4. What happens if I remove all Owners by accident?**  
+### 4. What happens if I remove all Owners by accident?
 Semaphore UI prevents the removal of an Owner if it would leave the project with no Owners at all. There must be at least one Owner at all times.
 
-**5. Can Guests run tasks?**  
+### 5. Can Guests run tasks?
 No. Guests only have read‐only access and cannot trigger or manage tasks.
-
----
-
-## Conclusion
-
-Roles in Semaphore UI help you control access and manage permissions within each project. By choosing the appropriate role for every team member and following best practices, you ensure smooth collaboration, secure operations, and straightforward delegation of responsibilities.