From 7c1544c3ce6785c3387d20c03aabc4558021a980 Mon Sep 17 00:00:00 2001
From: Joel Kaasinen <joel.kaasinen@metosin.fi>
Date: Fri, 6 Feb 2026 13:25:33 +0200
Subject: [PATCH] doc: document match-by-name :url-encode? option

for #778 #519
---
 doc/basics/name_based_routing.md | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/doc/basics/name_based_routing.md b/doc/basics/name_based_routing.md
index 97016b3d..f693e7c9 100644
--- a/doc/basics/name_based_routing.md
+++ b/doc/basics/name_based_routing.md
@@ -75,6 +75,17 @@ Path-parameters are automatically coerced into strings, with the help of (curren
 ;        :path-params {:id "1"}}
 ```
 
+In case you want to do something like generate a template path for documentation, you can disable url-encoding:
+
+```clj
+(r/match-by-name router ::user {:id "<id goes here>"} {:url-encode? false})
+; #reitit.core.Match{:template "/api/user/:id"
+;                    :data {:name :user/user}
+;                    :path "/api/user/<id goes here>"
+;                    :result nil
+;                    :path-params {:id "<id goes here>"}}
+```
+
 There is also an exception throwing version:
 
 ```clj
@@ -97,5 +108,5 @@ It can take an optional map of query-parameters too:
 (-> router
     (r/match-by-name ::user {:id 1})
     (r/match->path {:iso "möly"}))
-; "/api/user/1?iso=m%C3%B6ly"    
+; "/api/user/1?iso=m%C3%B6ly"
 ```