justrouting · Oct 7, 2026 · Oct 7, 2026 · Oct 7, 2026 · Oct 7, 2026
diff --git a/api-reference/directions.mdx b/api-reference/directions.mdx
@@ -1,8 +1,11 @@
 ---
-title: "Directions API"
+title: "Directions"
 description: "Get road-following routes between coordinates — distance, duration, geometry, and turn-by-turn steps."
+icon: "route"
 ---
 
+## Overview
+
 Directions API returns the real road route between two points (or ordered waypoints): distance (meters), estimated duration (seconds), route geometry (polyline or GeoJSON), and optional turn-by-turn steps.
 
 <Tip>

diff --git a/api-reference/distance-matrix.mdx b/api-reference/distance-matrix.mdx
@@ -1,8 +1,11 @@
 ---
-title: "Distance Matrix API"
+title: "Distance Matrix"
 description: "Compute travel times and distances between many points in a single request."
+icon: "table"
 ---
 
+## Overview
+
 Distance Matrix API returns an N×N matrix of driving times (seconds) and distances (meters) in a single request, powered by the `table` service. Ideal for nearest-store lookup, dispatch, and batch route planning.
 
 <Tip>

diff --git a/api-reference/fleet-optimization.mdx b/api-reference/fleet-optimization.mdx
@@ -1,8 +1,11 @@
 ---
-title: "Fleet Optimization API"
+title: "Fleet Optimization"
 description: "Multi-vehicle route optimization powered by VROOM — assign jobs, sequence stops, respect time windows and capacity."
+icon: "truck"
 ---
 
+## Overview
+
 Multi-vehicle route optimization (VRP) powered by [VROOM](https://github.com/VROOM-Project/vroom): you send JSON describing vehicles and tasks, you get back the optimal assignment and visit order. Distances come from the real OSRM road network — not straight lines.
 
 <Tip>

diff --git a/api-reference/geocode.mdx b/api-reference/geocode.mdx
@@ -1,8 +1,11 @@
 ---
-title: "Geocode API"
+title: "Geocode"
 description: "Convert a place name or address into coordinates — longitude, latitude, and address details."
+icon: "search"
 ---
 
+## Overview
+
 Geocode API converts a place name or address into coordinates. Send free-form text like `Marina Bay Sands, Singapore`, or a structured address with typed components; results come back ordered by relevance, each with `lon`/`lat` that plug directly into the `coordinates` of Directions and the other routing APIs.
 
 ## Endpoint

diff --git a/api-reference/map-matching.mdx b/api-reference/map-matching.mdx
@@ -1,8 +1,11 @@
 ---
-title: "Map Matching API"
+title: "Map Matching"
 description: "Snap noisy GPS traces to the real road network and get back the actual driven route."
+icon: "crosshairs"
 ---
 
+## Overview
+
 Map Matching API snaps a GPS trace to the real roads: send a timestamped coordinate sequence, get back the matched route (geometry, distance, duration) plus where each point landed on the network. Useful for cleaning delivery traces, analyzing actual driven paths, and mileage accounting.
 
 Powered by the OSRM Match service.

diff --git a/api-reference/nearest.mdx b/api-reference/nearest.mdx
@@ -1,8 +1,11 @@
 ---
-title: "Nearest API"
+title: "Nearest"
 description: "Snap a coordinate to the road network and get the nearest routable segments."
+icon: "map-pin"
 ---
 
+## Overview
+
 Nearest API snaps a single coordinate to the road network and returns the nearest `n` segments. Useful for validating whether a coordinate is routable, getting the exact snapped position, and obtaining `hint` values that speed up subsequent requests.
 
 Powered by the OSRM Nearest service.

diff --git a/api-reference/trip.mdx b/api-reference/trip.mdx
@@ -1,8 +1,11 @@
 ---
-title: "Trip API"
+title: "Trip"
 description: "Solve the traveling salesman problem — find the fastest visiting order for many stops."
+icon: "shuffle"
 ---
 
+## Overview
+
 Trip API solves the traveling salesman problem (TSP): given several stops, it returns an approximately optimal visiting order. Great for delivery route previews and multi-stop visit planning. Powered by the OSRM Trip service.
 
 <Note>

diff --git a/authentication.mdx b/authentication.mdx
@@ -1,6 +1,7 @@
 ---
 title: "Authentication"
 description: "How API keys work in JustRouting — creating keys, sending them, and understanding authentication errors."
+icon: "lock"
 ---
 
 Every JustRouting API request requires an API key, sent as an HTTP Bearer header:

diff --git a/coverage.mdx b/coverage.mdx
@@ -1,6 +1,7 @@
 ---
 title: "Coverage"
 description: "Which countries JustRouting covers, the cross-country constraint, and how map data updates work."
+icon: "map"
 ---
 
 ## Covered countries

diff --git a/docs.json b/docs.json
@@ -16,7 +16,6 @@
     "groups": [
       {
         "group": "Getting Started",
-        "icon": "rocket",
         "pages": [
           "index",
           "quickstart",
@@ -28,7 +27,6 @@
       },
       {
         "group": "API Reference",
-        "icon": "code",
         "pages": [
           "api-reference/directions",
           "api-reference/distance-matrix",
@@ -41,28 +39,25 @@
       },
       {
         "group": "MCP",
-        "icon": "sparkles",
         "pages": [
           "mcp/overview"
         ]
       },
       {
         "group": "OpenAPI",
-        "icon": "terminal",
         "pages": [
-          "openapi",
-          "openapi.json GET /route/v1/{profile}/{coordinates}",
-          "openapi.json GET /table/v1/{profile}/{coordinates}",
-          "openapi.json GET /match/v1/{profile}/{coordinates}",
-          "openapi.json GET /trip/v1/{profile}/{coordinates}",
-          "openapi.json GET /nearest/v1/{profile}/{coordinates}",
-          "openapi.json GET /geocode/v1/search",
-          "openapi.json POST /optimize"
+          "openapi/overview",
+          "openapi/openapi.json GET /route/v1/{profile}/{coordinates}",
+          "openapi/openapi.json GET /table/v1/{profile}/{coordinates}",
+          "openapi/openapi.json GET /match/v1/{profile}/{coordinates}",
+          "openapi/openapi.json GET /trip/v1/{profile}/{coordinates}",
+          "openapi/openapi.json GET /nearest/v1/{profile}/{coordinates}",
+          "openapi/openapi.json GET /geocode/v1/search",
+          "openapi/openapi.json POST /optimize"
         ]
       },
       {
         "group": "Guides",
-        "icon": "book-open",
         "pages": [
           "guides/draw-route-on-map",
           "guides/turn-by-turn",

diff --git a/errors.mdx b/errors.mdx
@@ -1,6 +1,7 @@
 ---
 title: "Errors"
 description: "Error format, HTTP status codes, and the complete error code reference for JustRouting APIs."
+icon: "triangle-exclamation"
 ---
 
 ## Error response format

diff --git a/guides/draw-route-on-map.mdx b/guides/draw-route-on-map.mdx
@@ -1,6 +1,7 @@
 ---
 title: "Draw a Route on a Map"
 description: "Render JustRouting route geometry with Leaflet, Mapbox GL JS, or react-leaflet."
+icon: "pen"
 ---
 
 Drawing a route on a map takes three steps: request `geometries=geojson`, grab `routes[0].geometry`, hand it to your map library. No polyline decoding needed.

diff --git a/guides/sdks.mdx b/guides/sdks.mdx
@@ -1,6 +1,7 @@
 ---
 title: "SDKs"
 description: "Official JustRouting client libraries for Python, JavaScript/TypeScript, and Go — zero dependencies."
+icon: "cube"
 ---
 
 SDKs are official clients, all **zero third-party dependencies** and open source (MIT). They cover the three API families — Directions, Distance Matrix, Fleet Optimization — with typed errors and built-in 429 retries.

diff --git a/guides/turn-by-turn.mdx b/guides/turn-by-turn.mdx
@@ -1,6 +1,7 @@
 ---
 title: "Turn-by-Turn Navigation"
 description: "Extract maneuver instructions from route steps to build navigation UI."
+icon: "arrow-turn-right"
 ---
 
 Request `steps=true` and every entry in `legs[].steps[]` is one maneuver plus a stretch of straight-line driving. Use them to build navigation lists, voice prompts, or per-segment highlighting.

diff --git a/index.mdx b/index.mdx
@@ -1,6 +1,7 @@
 ---
 title: "JustRouting Docs"
 description: "Routing APIs for Southeast Asia — directions, geocoding, distance matrices, map matching, and fleet optimization, with car and motorcycle profiles."
+icon: "house"
 ---
 
 # JustRouting APIs for Southeast Asia
@@ -43,7 +44,7 @@ Start in 30 seconds. **$0 to try.** No DevOps, no sales calls, no enterprise con
 ## Advanced APIs
 
 <CardGroup cols={3}>
-  <Card title="Map Matching" icon="crosshair" href="/api-reference/map-matching">
+  <Card title="Map Matching" icon="crosshairs" href="/api-reference/map-matching">
     Match noisy GPS traces to the road network and recover realistic road paths.
   </Card>
   <Card title="Trip" icon="route" href="/api-reference/trip">
@@ -102,7 +103,7 @@ Give an AI agent the ability to:
   <Card title="MCP" icon="sparkles" href="/mcp/overview">
     Connect Claude, Cursor, and other MCP-compatible AI clients to JustRouting.
   </Card>
-  <Card title="OpenAPI" icon="brackets-curly" href="/openapi">
+  <Card title="OpenAPI" icon="brackets-curly" href="/openapi/overview">
     Use the machine-readable API specification with code generators and AI coding tools.
   </Card>
 </CardGroup>

diff --git a/mcp/overview.mdx b/mcp/overview.mdx
@@ -1,8 +1,11 @@
 ---
-title: MCP
-description: Give AI assistants access to JustRouting's routing, geocoding, distance matrix, and vehicle routing capabilities.
+title: "Overview"
+description: "Give AI assistants access to JustRouting's routing, geocoding, distance matrix, and vehicle routing capabilities."
+icon: "sparkles"
 ---
 
+## JustRouting MCP
+
 JustRouting MCP lets AI assistants such as Claude and Cursor use [JustRouting](https://justrouting.tech/) for road routing, geocoding, distance and travel-time comparison, and multi-vehicle route optimization.
 
 Designed for Southeast Asia.

diff --git a/openapi.json → openapi/openapi.json b/openapi.json → openapi/openapi.json
diff --git a/openapi.mdx → openapi/overview.md b/openapi.mdx → openapi/overview.md
@@ -1,9 +1,10 @@
 ---
-title: "OpenAPI"
+title: "Overview"
 description: "Machine-readable specification for the JustRouting API."
+icon: "globe"
 ---
 
-# Overview
+# OpenAPI
 
 JustRouting provides an OpenAPI specification for developers and tools that
 want to discover and integrate the API programmatically.
@@ -13,7 +14,7 @@ schemas, and response schemas.
 
 ## Specification
 
-[Download openapi.json](https://raw.githubusercontent.com/justrouting/docs/main/openapi.json)
+[Download openapi.json](https://raw.githubusercontent.com/justrouting/docs/main/openapi/openapi.json)
 
 Use the interactive API explorer below to try JustRouting endpoints directly
 from the documentation.

diff --git a/quickstart.mdx b/quickstart.mdx
@@ -1,6 +1,7 @@
 ---
 title: "Quickstart"
 description: "Get an API key, make your first routing request, and draw the route on a map in under three minutes."
+icon: "bolt"
 ---
 
 Quickstart takes three steps and three minutes. No credit card required.

diff --git a/rate-limits.mdx b/rate-limits.mdx
@@ -1,6 +1,7 @@
 ---
 title: "Rate Limits & Quotas"
 description: "Request quotas, rate limits, and matrix/VRP size limits per plan, plus how `HTTP code=429` responses behave."
+icon: "gauge"
 ---
 
 ## Plans at a glance

diff --git a/style.css b/style.css
@@ -0,0 +1,4 @@
+.sidebar-group-header {
+  font-size: 1.0rem !important;
+  color: #2563eb !important;
+}