Update documentation

README.md

@@ -268,7 +268,7 @@ value. That is, `json j = "{ \"happy\": true, \"pi\": 3.141 }"` would just store
 `"{ "happy": true, "pi": 3.141 }"` rather than parsing the actual object.
 
 The string literal should be brought into scope with with `using namespace nlohmann::literals;`
-(see [`json::parse()`](https://json.nlohmann.me/api/basic_json/operator_literal_json/)).
+(see [`json::parse()`](https://json.nlohmann.me/api/operator_literal_json/)).
 
 The above example can also be expressed explicitly using [`json::parse()`](https://json.nlohmann.me/api/basic_json/parse/):
 

docs/mkdocs/docs/api/basic_json/index.md

@@ -289,8 +289,7 @@ Access to the JSON value
 
 ## Literals
 
-- [**operator""_json**](operator_literal_json.md) - user-defined string literal for JSON values
-- [**operator""_json_pointer**](operator_literal_json_pointer.md) - user-defined string literal for JSON pointers
+- [**operator""_json**](../operator_literal_json.md) - user-defined string literal for JSON values
 
 ## Helper classes
 

docs/mkdocs/docs/api/json_pointer/index.md

@@ -37,9 +37,11 @@ are the base for JSON patches.
 - [**push_back**](push_back.md) - append an unescaped token at the end of the pointer
 - [**empty**](empty.md) - return whether pointer points to the root document
 
+## Literals
+
+- [**operator""_json_pointer**](../operator_literal_json_pointer.md) - user-defined string literal for JSON pointers
 ## See also
 
-- [operator""_json_pointer](../basic_json/operator_literal_json_pointer.md) - user-defined string literal for JSON pointers
 - [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)
 
 ## Version history

docs/mkdocs/docs/api/macros/index.md

@@ -21,6 +21,7 @@ header. See also the [macro overview page](../../features/macros.md).
 - [**JSON_HAS_THREE_WAY_COMPARISON**](json_has_three_way_comparison.md) - control 3-way comparison support
 - [**JSON_NO_IO**](json_no_io.md) - switch off functions relying on certain C++ I/O headers
 - [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](json_skip_unsupported_compiler_check.md) - do not warn about unsupported compilers
+- [**JSON_USE_GLOBAL_UDLS**](json_use_global_udls.md) - place user-defined string literals (UDLs) into the global namespace
 
 ## Library version
 

docs/mkdocs/docs/api/macros/json_use_global_udls.md

@@ -0,0 +1,93 @@
+# JSON_USE_GLOBAL_UDLS
+
+```cpp
+#define JSON_USE_GLOBAL_UDLS /* value */
+```
+
+When defined to `1`, the user-defined string literals (UDLs) are placed into the global namespace instead of
+`nlohmann::literals::json_literals`.
+
+## Default definition
+
+The default value is `1`.
+
+```cpp
+#define JSON_USE_GLOBAL_UDLS 1
+```
+
+When the macro is not defined, the library will define it to its default value.
+
+## Notes
+
+!!! info "Future behavior change"
+
+    The user-defined string literals will be removed from the global namespace in the next major release of the
+    library.
+
+    To prepare existing code, define `JSON_USE_GLOBAL_UDLS` to `0` and bring the string literals into scope where
+    needed. Refer to any of the [string literals](#see-also) for details.
+
+## Examples
+
+??? example "Example 1: Default behavior"
+
+    The code below shows the default behavior using the `_json` UDL.
+    
+    ```cpp
+    #include <nlohmann/json.hpp>
+    
+    #include <iostream>
+    
+    int main()
+    {
+        auto j = "42"_json;
+    
+        std::cout << j << std::endl;
+    }
+    ```
+    
+    Output:
+    
+    ```json
+    42
+    ```
+
+??? example "Example 2: Namespaced UDLs"
+
+    The code below shows how UDLs need to be brought into scope before using `_json` when `JSON_USE_GLOBAL_UDLS` is
+    defined to `0`.
+    
+    ```cpp
+    #define JSON_USE_GLOBAL_UDLS 0
+    #include <nlohmann/json.hpp>
+
+    #include <iostream>
+    
+    int main()
+    {
+        // auto j = "42"_json; // This line would fail to compile,
+                               // because the UDLs are not in the global namespace
+    
+        // Bring the UDLs into scope
+        using namespace nlohmann::json_literals;
+    
+        auto j = "42"_json;
+    
+        std::cout << j << std::endl;
+    }
+    ```
+    
+    Output:
+    
+    ```json
+    42
+    ```
+
+## See also
+
+- [`operator""_json`](../operator_literal_json.md)
+- [`operator""_json_pointer`](../operator_literal_json_pointer.md)
+
+## Version history
+
+- Added in version 3.11.0.

docs/mkdocs/docs/api/operator_literal_json.md

@@ -1,12 +1,22 @@
-# <small>nlohmann::basic_json::</small>operator""_json
+# <small>nlohmann::</small>operator""_json
 
 ```cpp
 json operator "" _json(const char* s, std::size_t n);
 ```
 
 This operator implements a user-defined string literal for JSON objects. It can be used by adding `#!cpp _json` to a
-string literal and returns a [`json`](../json.md) object if no parse error occurred.
+string literal and returns a [`json`](json.md) object if no parse error occurred.
 
+Use any of the following lines to bring the operator into scope:
+```cpp
+using namespace nlohmann::literals;
+using namespace nlohmann::json_literals;
+using namespace nlohmann::literals::json_literals;
+using namespace nlohmann;
+```
+
+Alternatively, define [`JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md) to make them available in the global
+namespace.
 ## Parameters
 
 `s` (in)
@@ -17,11 +27,11 @@ string literal and returns a [`json`](../json.md) object if no parse error occur
 
 ## Return value
 
-[`json`](../json.md) value parsed from `s`
+[`json`](json.md) value parsed from `s`
 
 ## Exceptions
 
-The function can throw anything that [`parse(s, s+n)`](parse.md) would throw.
+The function can throw anything that [`parse(s, s+n)`](basic_json/parse.md) would throw.
 
 ## Complexity
 
@@ -46,3 +56,4 @@ Linear.
 ## Version history
 
 - Added in version 1.0.0.
+- Moved to namespace `nlohmann::literals::json_literals` in 3.11.0.

docs/mkdocs/docs/api/operator_literal_json_pointer.md

@@ -1,12 +1,22 @@
-# <small>nlohmann::basic_json::</small>operator""_json_pointer
+# <small>nlohmann::</small>operator""_json_pointer
 
 ```cpp
 json_pointer operator "" _json_pointer(const char* s, std::size_t n);
 ```
 
 This operator implements a user-defined string literal for JSON Pointers. It can be used by adding `#!cpp _json_pointer`
-to a string literal and returns a [`json_pointer`](../json_pointer/index.md) object if no parse error occurred.
+to a string literal and returns a [`json_pointer`](json_pointer/index.md) object if no parse error occurred.
 
+Use any of the following lines to bring the operator into scope:
+```cpp
+using namespace nlohmann::literals;
+using namespace nlohmann::json_literals;
+using namespace nlohmann::literals::json_literals;
+using namespace nlohmann;
+```
+
+Alternatively, define [`JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md) to make them available in the global
+namespace.
 ## Parameters
 
 `s` (in)
@@ -17,11 +27,11 @@ to a string literal and returns a [`json_pointer`](../json_pointer/index.md) obj
 
 ## Return value
 
-[`json_pointer`](../json_pointer/index.md) value parsed from `s`
+[`json_pointer`](json_pointer/index.md) value parsed from `s`
 
 ## Exceptions
 
-The function can throw anything that [`json_pointer::json_pointer`](../json_pointer/index.md) would throw.
+The function can throw anything that [`json_pointer::json_pointer`](json_pointer/index.md) would throw.
 
 ## Complexity
 
@@ -45,8 +55,9 @@ Linear.
 
 ## See also
 
-- [json_pointer](../json_pointer/index.md) - type to represent JSON Pointers
+- [json_pointer](json_pointer/index.md) - type to represent JSON Pointers
 
 ## Version history
 
 - Added in version 2.0.0.
+- Moved to namespace `nlohmann::literals::json_literals` in 3.11.0.

docs/mkdocs/mkdocs.yml

@@ -162,8 +162,6 @@ nav:
         - 'operator<=': api/basic_json/operator_le.md
         - 'operator>=': api/basic_json/operator_ge.md
         - 'operator<=>': api/basic_json/operator_spaceship.md
-        - 'operator""_json': api/basic_json/operator_literal_json.md
-        - 'operator""_json_pointer': api/basic_json/operator_literal_json_pointer.md
         - 'out_of_range': api/basic_json/out_of_range.md
         - 'other_error': api/basic_json/other_error.md
         - 'parse': api/basic_json/parse.md
@@ -236,6 +234,8 @@ nav:
       - 'operator<<(basic_json)': api/operator_ltlt.md
       - 'operator<<(json_pointer)': api/operator_ltlt.md
       - 'operator>>(basic_json)': api/operator_gtgt.md
+      - 'operator""_json': api/operator_literal_json.md
+      - 'operator""_json_pointer': api/operator_literal_json_pointer.md
       - 'ordered_json': api/ordered_json.md
       - 'ordered_map': api/ordered_map.md
       - macros:
@@ -258,6 +258,7 @@ nav:
         - 'JSON_SKIP_UNSUPPORTED_COMPILER_CHECK': api/macros/json_skip_unsupported_compiler_check.md
         - 'JSON_THROW_USER': api/macros/json_throw_user.md
         - 'JSON_TRY_USER': api/macros/json_throw_user.md
+        - 'JSON_USE_GLOBAL_UDLS': api/macros/json_use_global_udls.md
         - 'JSON_USE_IMPLICIT_CONVERSIONS': api/macros/json_use_implicit_conversions.md
         - 'JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON': api/macros/json_use_legacy_discarded_value_comparison.md
         - 'NLOHMANN_DEFINE_TYPE_INTRUSIVE': api/macros/nlohmann_define_type_intrusive.md
@@ -332,6 +333,8 @@ plugins:
         redirect_maps:
             'api/basic_json/operator_gtgt.md': api/operator_gtgt.md
             'api/basic_json/operator_ltlt.md': api/operator_ltlt.md
+            'api/basic_json/operator_literal_json.md': api/operator_literal_json.md
+            'api/basic_json/operator_literal_json_pointer.md': api/operator_literal_json_pointer.md
             'api/json_pointer/operator_string.md': api/json_pointer/operator_string_t.md
 
 extra_css: