docs(en): improve 15 additional low-quality doc pages

- Add introductory prose and runnable code to binding, routing, server-config, logging, and middleware pages
- Add "Test it" sections with curl commands and expected output
- Add "See also" cross-references to related documentation
- Replace GitHub issue links with self-contained explanations
- Fix heading levels from h3 to h2 for consistency
- Make all code examples complete with package and imports

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: appleboy

src/content/docs/en/docs/binding/bind-body-into-different-structs.md

@@ -4,10 +4,20 @@ sidebar:
   order: 13
 ---
 
-The normal methods for binding request body consumes `c.Request.Body` and they
-cannot be called multiple times.
+The standard binding methods like `c.ShouldBind` consume `c.Request.Body`, which is an `io.ReadCloser` — once read, it cannot be read again. This means you cannot call `c.ShouldBind` multiple times on the same request to try different struct shapes.
+
+To solve this, use `c.ShouldBindBodyWith`. It reads the body once and stores it in the context, allowing subsequent bindings to reuse the cached body.
 
 ```go
+package main
+
+import (
+  "net/http"
+
+  "github.com/gin-gonic/gin"
+  "github.com/gin-gonic/gin/binding"
+)
+
 type formA struct {
   Foo string `json:"foo" xml:"foo" binding:"required"`
 }
@@ -16,46 +26,51 @@ type formB struct {
   Bar string `json:"bar" xml:"bar" binding:"required"`
 }
 
-func SomeHandler(c *gin.Context) {
-  objA := formA{}
-  objB := formB{}
-  // This c.ShouldBind consumes c.Request.Body and it cannot be reused.
-  if errA := c.ShouldBind(&objA); errA == nil {
-    c.String(http.StatusOK, `the body should be formA`)
-  // Always an error is occurred by this because c.Request.Body is EOF now.
-  } else if errB := c.ShouldBind(&objB); errB == nil {
-    c.String(http.StatusOK, `the body should be formB`)
-  } else {
-    ...
-  }
+func main() {
+  router := gin.Default()
+
+  router.POST("/bind", func(c *gin.Context) {
+    objA := formA{}
+    objB := formB{}
+    // This reads c.Request.Body and stores the result into the context.
+    if errA := c.ShouldBindBodyWith(&objA, binding.JSON); errA == nil {
+      c.JSON(http.StatusOK, gin.H{"message": "matched formA", "foo": objA.Foo})
+      return
+    }
+    // At this time, it reuses body stored in the context.
+    if errB := c.ShouldBindBodyWith(&objB, binding.JSON); errB == nil {
+      c.JSON(http.StatusOK, gin.H{"message": "matched formB", "bar": objB.Bar})
+      return
+    }
+
+    c.JSON(http.StatusBadRequest, gin.H{"error": "request body did not match any known format"})
+  })
+
+  router.Run(":8080")
 }
 ```
 
-For this, you can use `c.ShouldBindBodyWith`.
+## Test it
 
-```go
-func SomeHandler(c *gin.Context) {
-  objA := formA{}
-  objB := formB{}
-  // This reads c.Request.Body and stores the result into the context.
-  if errA := c.ShouldBindBodyWith(&objA, binding.JSON); errA == nil {
-    c.String(http.StatusOK, `the body should be formA`)
-  // At this time, it reuses body stored in the context.
-  } else if errB := c.ShouldBindBodyWith(&objB, binding.JSON); errB == nil {
-    c.String(http.StatusOK, `the body should be formB JSON`)
-  // And it can accepts other formats
-  } else if errB2 := c.ShouldBindBodyWith(&objB, binding.XML); errB2 == nil {
-    c.String(http.StatusOK, `the body should be formB XML`)
-  } else {
-    ...
-  }
-}
+```sh
+# Body matches formA
+curl -X POST http://localhost:8080/bind \
+  -H "Content-Type: application/json" \
+  -d '{"foo":"hello"}'
+# Output: {"foo":"hello","message":"matched formA"}
+
+# Body matches formB
+curl -X POST http://localhost:8080/bind \
+  -H "Content-Type: application/json" \
+  -d '{"bar":"world"}'
+# Output: {"bar":"world","message":"matched formB"}
 ```
 
-* `c.ShouldBindBodyWith` stores body into the context before binding. This has
-a slight impact to performance, so you should not use this method if you only need to bind once.
-* This feature is only needed for some formats -- `JSON`, `XML`, `MsgPack`,
-`ProtoBuf`. For other formats, `Query`, `Form`, `FormPost`, `FormMultipart`,
-can be called by `c.ShouldBind()` multiple times without any damage to
-performance (See [#1341](https://github.com/gin-gonic/gin/pull/1341)).
+:::note
+`c.ShouldBindBodyWith` stores the body in the context before binding. This has a slight performance impact, so only use it when you need to bind the body more than once. For formats that do not read the body — such as `Query`, `Form`, `FormPost`, `FormMultipart` — you can call `c.ShouldBind()` multiple times without issue.
+:::
+
+## See also
 
+- [Binding and validation](/en/docs/binding/binding-and-validation/)
+- [Bind query string or post data](/en/docs/binding/bind-query-or-post/)

src/content/docs/en/docs/binding/custom-validators.md

@@ -4,7 +4,9 @@ sidebar:
   order: 2
 ---
 
-It is also possible to register custom validators. See the [example code](https://github.com/gin-gonic/examples/tree/master/struct-lvl-validations).
+Gin uses [go-playground/validator](https://github.com/go-playground/validator) for field-level validation. In addition to the built-in validators (like `required`, `email`, `min`, `max`), you can register your own custom validation functions.
+
+The example below registers a `bookabledate` validator that rejects dates in the past, ensuring that booking check-in and check-out dates are always in the future.
 
 ```go
 package main
@@ -56,13 +58,23 @@ func getBookable(c *gin.Context) {
 }
 ```
 
+## Test it
+
 ```sh
-$ curl "localhost:8085/bookable?check_in=2118-04-16&check_out=2118-04-17"
-{"message":"Booking dates are valid!"}
+# Both dates are in the future and check_out > check_in
+curl "http://localhost:8085/bookable?check_in=2118-04-16&check_out=2118-04-17"
+# Output: {"message":"Booking dates are valid!"}
 
-$ curl "localhost:8085/bookable?check_in=2118-03-10&check_out=2118-03-09"
-{"error":"Key: 'Booking.CheckOut' Error:Field validation for 'CheckOut' failed on the 'gtfield' tag"}
+# check_out is before check_in -- fails gtfield validation
+curl "http://localhost:8085/bookable?check_in=2118-03-10&check_out=2118-03-09"
+# Output: {"error":"Key: 'Booking.CheckOut' Error:Field validation for 'CheckOut' failed on the 'gtfield' tag"}
 ```
 
-[Struct level validations](https://github.com/go-playground/validator/releases/tag/v8.7) can also be registered this way.
-See the [struct-lvl-validation example](https://github.com/gin-gonic/examples/tree/master/struct-lvl-validations) to learn more.
+:::tip
+You can also register [struct-level validations](https://github.com/go-playground/validator/releases/tag/v8.7) for cross-field rules that go beyond single-field checks. See the [struct-lvl-validation example](https://github.com/gin-gonic/examples/tree/master/struct-lvl-validations) to learn more.
+:::
+
+## See also
+
+- [Binding and validation](/en/docs/binding/binding-and-validation/)
+- [Bind default values](/en/docs/binding/bind-default-values/)

src/content/docs/en/docs/binding/multipart-urlencoded-binding.md

@@ -4,10 +4,16 @@ sidebar:
   order: 11
 ---
 
+`ShouldBind` automatically detects the `Content-Type` and binds `multipart/form-data` or `application/x-www-form-urlencoded` request bodies into a struct. Use the `form` struct tag to map form field names to struct fields, and `binding:"required"` to enforce mandatory fields.
+
+This is commonly used for login forms, registration pages, or any HTML form submission.
+
 ```go
 package main
 
 import (
+  "net/http"
+
   "github.com/gin-gonic/gin"
 )
 
@@ -18,25 +24,51 @@ type LoginForm struct {
 
 func main() {
   router := gin.Default()
+
   router.POST("/login", func(c *gin.Context) {
-    // you can bind multipart form with explicit binding declaration:
-    // c.ShouldBindWith(&form, binding.Form)
-    // or you can simply use autobinding with ShouldBind method:
     var form LoginForm
-    // in this case proper binding will be automatically selected
-    if c.ShouldBind(&form) == nil {
-      if form.User == "user" && form.Password == "password" {
-        c.JSON(200, gin.H{"status": "you are logged in"})
-      } else {
-        c.JSON(401, gin.H{"status": "unauthorized"})
-      }
+    // ShouldBind automatically selects the right binding based on Content-Type
+    if err := c.ShouldBind(&form); err != nil {
+      c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+      return
+    }
+
+    if form.User == "user" && form.Password == "password" {
+      c.JSON(http.StatusOK, gin.H{"status": "you are logged in"})
+    } else {
+      c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"})
     }
   })
+
   router.Run(":8080")
 }
 ```
 
-Test it with:
+## Test it
+
 ```sh
-$ curl -v --form user=user --form password=password http://localhost:8080/login
+# Multipart form
+curl -X POST http://localhost:8080/login \
+  -F "user=user" -F "password=password"
+# Output: {"status":"you are logged in"}
+
+# URL-encoded form
+curl -X POST http://localhost:8080/login \
+  -d "user=user&password=password"
+# Output: {"status":"you are logged in"}
+
+# Wrong credentials
+curl -X POST http://localhost:8080/login \
+  -d "user=wrong&password=wrong"
+# Output: {"status":"unauthorized"}
+
+# Missing required field
+curl -X POST http://localhost:8080/login \
+  -d "user=user"
+# Output: {"error":"Key: 'LoginForm.Password' Error:Field validation for 'Password' failed on the 'required' tag"}
 ```
+
+## See also
+
+- [Binding and validation](/en/docs/binding/binding-and-validation/)
+- [Bind html checkboxes](/en/docs/binding/bind-html-checkbox/)

src/content/docs/en/docs/binding/only-bind-query-string.md

@@ -4,13 +4,15 @@ sidebar:
   order: 3
 ---
 
-`ShouldBindQuery` function only binds the query params and not the post data. See the [detail information](https://github.com/gin-gonic/gin/issues/742#issuecomment-315953017).
+`ShouldBindQuery` binds only the URL query string parameters to a struct, ignoring the request body entirely. This is useful when you want to ensure that POST body data does not accidentally overwrite query parameters — for example, in endpoints that accept both query filters and a JSON body.
+
+In contrast, `ShouldBind` on a GET request also uses query binding, but on a POST request it will first check the body. Use `ShouldBindQuery` when you explicitly want query-only binding regardless of the HTTP method.
 
 ```go
 package main
 
 import (
-  "log"
+  "net/http"
 
   "github.com/gin-gonic/gin"
 )
@@ -28,11 +30,32 @@ func main() {
 
 func startPage(c *gin.Context) {
   var person Person
-  if c.ShouldBindQuery(&person) == nil {
-    log.Println("====== Only Bind By Query String ======")
-    log.Println(person.Name)
-    log.Println(person.Address)
+  if err := c.ShouldBindQuery(&person); err != nil {
+    c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+    return
   }
-  c.String(200, "Success")
+
+  c.JSON(http.StatusOK, gin.H{
+    "name":    person.Name,
+    "address": person.Address,
+  })
 }
 ```
+
+## Test it
+
+```sh
+# GET with query parameters
+curl "http://localhost:8085/testing?name=appleboy&address=xyz"
+# Output: {"address":"xyz","name":"appleboy"}
+
+# POST with query parameters -- body is ignored, only query is bound
+curl -X POST "http://localhost:8085/testing?name=appleboy&address=xyz" \
+  -d "name=ignored&address=ignored"
+# Output: {"address":"xyz","name":"appleboy"}
+```
+
+## See also
+
+- [Bind query string or post data](/en/docs/binding/bind-query-or-post/)
+- [Binding and validation](/en/docs/binding/binding-and-validation/)

src/content/docs/en/docs/logging/define-format-for-the-log-of-routes.md

@@ -4,16 +4,19 @@ sidebar:
   order: 6
 ---
 
-The default log of routes is:
+When Gin starts, it prints all registered routes in debug mode. The default format looks like this:
+
 ```
 [GIN-debug] POST   /foo                      --> main.main.func1 (3 handlers)
 [GIN-debug] GET    /bar                      --> main.main.func2 (3 handlers)
 [GIN-debug] GET    /status                   --> main.main.func3 (3 handlers)
 ```
 
-If you want to log this information in given format (e.g. JSON, key values or something else), then you can define this format with `gin.DebugPrintRouteFunc`.
-In the example below, we log all routes with standard log package but you can use another log tools that suits of your needs.
+You can customize this format by assigning a function to `gin.DebugPrintRouteFunc`. This is useful if you want to log routes as JSON, key-value pairs, or in any other format your logging pipeline expects.
+
 ```go
+package main
+
 import (
   "log"
   "net/http"
@@ -23,6 +26,7 @@ import (
 
 func main() {
   router := gin.Default()
+
   gin.DebugPrintRouteFunc = func(httpMethod, absolutePath, handlerName string, nuHandlers int) {
     log.Printf("endpoint %v %v %v %v\n", httpMethod, absolutePath, handlerName, nuHandlers)
   }
@@ -39,7 +43,19 @@ func main() {
     c.JSON(http.StatusOK, "ok")
   })
 
-  // Listen and Server in http://0.0.0.0:8080
-  router.Run()
+  router.Run(":8080")
 }
 ```
+
+When the server starts, instead of the default `[GIN-debug]` lines, you will see:
+
+```
+endpoint POST /foo main.main.func2 3
+endpoint GET /bar main.main.func3 3
+endpoint GET /status main.main.func4 3
+```
+
+## See also
+
+- [Custom log format](/en/docs/logging/custom-log-format/)
+- [Skip logging](/en/docs/logging/skip-logging/)