Document URL pattern best practices

content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/microflows/microflow.md

@@ -52,6 +52,8 @@ In the **Edit Microflow URL** dialog box, the configured URL is shown together w
 URLs are not supported for microflows that have non-persistable entities or lists as parameters.
 {{%/alert %}}
 
+For recommendations on structuring URLs and avoiding conflicts, see [Page and Microflow URLs](/refguide/general-best-practices/#page-and-microflow-urls).
+
 ### Common Section {#common}
 
 #### Name

content/en/docs/refguide/modeling/best-practices/dev-best-practices/general-guidelines.md

@@ -30,6 +30,40 @@ Applications exceeding these guidelines may still function, depending on your sy
 App size impacts IDE performance. Choose a development strategy that aligns with your system's capabilities and Mendix's recommended guidelines.
 {{% /alert %}}
 
+## Page and Microflow URLs {#page-and-microflow-urls}
+
+When designing page and microflow URLs, prefer clear path segments over compact patterns:
+
+* Use `/` to divide the URL into meaningful segments
+* Put a parameter in its own segment, for example, `product/{Product/Name}` instead of `product-{Product/Name}`
+* Do not start the URL with a parameter. Use a static segment first, for example, `user/{User/Id}` instead of `{User/Id}`
+* Use static segments to make the structure explicit, for example, `category/{Category/Code}/product/{Product/Name}`
+* Use `-` to separate words within a static segment, for example, `orders/request-return-label`
+
+This makes URLs easier to read, easier to maintain, and less likely to conflict with other URLs.
+
+URL conflicts are checked per path segment. Two URLs are considered conflicting when they have the same number of segments and Studio Pro cannot tell, from the URL structure alone, which page or microflow should handle the request. A conflict can be full or partial.
+
+A full conflict means the patterns overlap for all matching values. In other words, every URL that matches one pattern also matches the other. For example, `product/{Product/Name}` and `product/{Product/Code}` always conflict because both patterns accept any value in the second segment, so Studio Pro cannot use the URL itself to tell them apart. This means there is no single possible URL that will not be conflicting. For example, `https://example.com/p/product/chair` matches both patterns.
+
+A partial conflict means the patterns overlap only for specific values. Most URLs are still unique, but some URLs can match both patterns. For example, `product-{Name}` and `product-overview` only conflict for the URL `product-overview`, because `Name` can be `overview`. In that case, Studio Pro cannot tell whether `overview` is meant to be a fixed URL or a parameter value. For example, `https://example.com/p/product-overview` matches both patterns, while `https://example.com/p/product-chair` only matches `product-{Name}`.
+
+When a request matches conflicting URL patterns, the runtime picks one pattern and tries to open it. Which pattern is chosen is undefined. This can lead to unexpected behavior or a not-found page. For example, `https://example.com/p/product-overview` matches both `product-{Name}` and `product-overview`. If the selected pattern does not resolve to valid values, the request can fail even though the other pattern would have worked.
+
+Common full conflict cases include the following:
+
+* Two parameters in the same position, such as `product/{Product/Name}` and `product/{Product/Code}`. Resolve this by adding distinct static segments, for example, `product/name/{Product/Name}` and `product/code/{Product/Code}`.
+
+Common partial conflict cases include the following:
+
+* A static segment that can also be matched by a parameter, such as `product/{Product/Name}` and `product/sale`. Resolve this by making the parameter route more explicit, for example, `product/name/{Product/Name}` and `product/sale`.
+* A numeric static segment that overlaps with an `Id` parameter, such as `order/{Order/Id}` and `order/123`. Resolve this by using a different static pattern, for example, `order/{Order/Id}` and `order-123`.
+* Mixed segments where neither the static prefix nor the static suffix makes the segment unique, such as `product-{Product/Name}-details` and `product-sale-details`. Resolve this by putting the parameter in its own segment, for example, `product/{Product/Name}/details` and `product-sale-details`.
+
+If either the prefix or the suffix is unique, the segments do not conflict.
+
+Using separate segments reduces ambiguity. For example, `product/{Product/Name}` and `product-sale` do not conflict because they have a different number of segments.
+
 ## Model SDK
 
 The Mendix Model SDK enforces a strict limit of 20,000 units per working copy.

content/en/docs/refguide/modeling/pages/page/page-properties.md

@@ -106,6 +106,8 @@ In simple e-commerce applications, the URLs can be configured as follows:
 Mendix does not recommend configuring page URLs for pages that are displayed as a pop-up. Navigating to such a URL will result in layout issues.
 {{%/alert %}}
 
+For recommendations on structuring URLs and avoiding conflicts, see [Page and Microflow URLs](/refguide/general-best-practices/#page-and-microflow-urls).
+
 ### Common Section {#common}
 
 {{% snippet file="/static/_includes/refguide/common-section-link.md" %}}