docs: improved file structure

Author: marcinkrasowski

apps/docs/docs/guides/create-new-block/_category_.json

@@ -1,6 +1,6 @@
 {
     "label": "Create a new block",
-    "position": 900,
+    "position": 500,
     "link": {
         "type": "doc",
         "id": "overview"

apps/docs/docs/guides/deployment/_category_.json

@@ -1,10 +1,9 @@
 {
     "label": "Deployment",
-    "position": 6,
+    "position": 600,
     "link": {
-        "type": "generated-index",
-        "title": "Deployment",
-        "description": "How to deploy Open Self Service using Docker and Vercel."
+        "type": "doc",
+        "id": "overview"
     }
 }
 

apps/docs/docs/guides/deployment/docker.md

@@ -29,7 +29,7 @@ This will:
 - Build `apps/frontend/Dockerfile` and expose it on `http://localhost:3000`
 - Build `apps/api-harmonization/Dockerfile` and expose it on `http://localhost:3001`
 
-Environment variables
+## Environment variables
 
 The `docker-compose.yml` includes sane defaults. Adjust as needed (especially external API keys).
 
@@ -48,7 +48,7 @@ The `docker-compose.yml` includes sane defaults. Adjust as needed (especially ex
   - Optional logging: `LOG_LEVEL`, `LOG_FORMAT`, `LOG_COLORS_ENABLED`
   - Integrations: see `/docs/integrations` for provider-specific variables (e.g. `CMS_STRAPI_BASE_URL`, `ALGOLIA_*`, `MEDUSAJS_*`, `CACHE_*`, etc.)
 
-Useful commands
+## Useful commands
 
 ```bash
 # View logs
@@ -82,7 +82,7 @@ docker run --rm -p 3001:3001 --network app_network \
 
 **Note:** The Dockerfiles use Turborepo's `turbo prune` with `@dxp/frontend` and `@dxp/api-harmonization` package names internally. This is handled automatically by the build process.
 
-Example Dockerfiles
+## Example Dockerfiles
 
 See the repository for maintained examples:
 

apps/docs/docs/guides/deployment/vercel.md

@@ -5,7 +5,7 @@ description: Configure a monorepo deployment of the Next.js frontend to Vercel.
 
 This section covers deploying the Next.js `frontend` app to Vercel. The NestJS API is best deployed as a container (see [Deploy with Docker](./docker)).
 
-Project settings
+## Project settings
 
 1) Import the GitHub repository into Vercel.
 2) In Project Settings → General:
@@ -16,7 +16,7 @@ Project settings
    - Build Command (monorepo with Turborepo): `npx turbo run build --filter=frontend`
    - Output Directory: (handled by Next.js)
 
-Environment variables
+## Environment variables
 
 Add these variables in Project Settings → Environment Variables for Preview and Production:
 
@@ -27,13 +27,13 @@ Add these variables in Project Settings → Environment Variables for Preview an
 - Optional logging: `NEXT_PUBLIC_LOG_LEVEL`, `NEXT_PUBLIC_LOG_FORMAT`, `NEXT_PUBLIC_LOG_COLORS_ENABLED`
 - Auth (optional): `AUTH_GITHUB_ID`, `AUTH_GITHUB_SECRET`, `AUTH_GOOGLE_ID`, `AUTH_GOOGLE_SECRET`, `AUTH_SECRET`, `AUTH_DEFAULT_USER_ROLE`
 
-Notes
+## Notes
 
 - API hosting: Historically, Vercel Serverless was not recommended for the NestJS API in this repository. However, Vercel has recently added improved backend support (including NestJS). For now we recommend deploying the API as a container (Docker on VM/Kubernetes/Fly.io/Render/etc.) and exposing a public URL consumed by the frontend, but this is under evaluation and may change. We plan to investigate first-class Vercel API hosting and update this guide accordingly.
 - CORS: Ensure the API’s `FRONT_BASE_URLS` includes your Vercel domains (both Preview and Production), e.g. `https://your-app.vercel.app,https://your-branch-your-team.vercel.app`.
 - Images and headers: If you use custom headers or remote images, configure them in `apps/frontend/next.config.ts`.
 
-Production checks
+## Production checks
 
 After the first deployment: