Consolidate documentation (#3071)

* 🔥 consolidate documentation
* ♻️ overwork std specializations
* 🚚 move images files to mkdocs
* ♻️ fix URLs
* 🔧 tweak MkDocs configuration
* 🔧 add namespaces
* 📝 document deprecations
* 📝 document documentation generation
* 🚸 improve search
* 🚸 add examples
* 🚧 start adding documentation for macros
* 📝 add note for https://github.com/nlohmann/json/issues/874#issuecomment-1001699139
* 📝 overwork example handling
* 📝 fix Markdown tables

doc/mkdocs/docs/api/ordered_map.md

@@ -1,7 +1,70 @@
-# ordered_map
+# <small>nlohmann::</small>ordered_map
 
 ```cpp
 template<class Key, class T, class IgnoredLess = std::less<Key>,
          class Allocator = std::allocator<std::pair<const Key, T>>>
 struct ordered_map : std::vector<std::pair<const Key, T>, Allocator>;
 ```
+
+A minimal map-like container that preserves insertion order for use within [`nlohmann::ordered_json`](ordered_json.md)
+(`nlohmann::basic_json<ordered_map>`).
+
+## Template parameters
+
+`Key`
+:   key type
+
+`T`
+:   mapped type
+
+`IgnoredLess`
+:   comparison function (ignored and only added to ensure compatibility with `#!cpp std::map`)
+
+`Allocator`
+:   allocator type
+
+## Member types
+
+- **key_type** - key type (`Key`)
+- **mapped_type** - mapped type (`T`)
+- **Container** - base container type (`#!cpp std::vector<std::pair<const Key, T>, Allocator>`)
+- **iterator**
+- **const_iterator**
+- **size_type**
+- **value_type**
+
+## Member functions
+
+- (constructor)
+- (destructor)
+- **emplace**
+- **operator\[\]**
+- **at**
+- **erase**
+- **count**
+- **find**
+- **insert**
+
+## Examples
+
+??? example
+
+    The example shows the different behavior of `std::map` and `nlohmann::ordered_map`.
+     
+    ```cpp
+    --8<-- "examples/ordered_map.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/ordered_map.output"
+    ```
+
+## See also
+
+- [ordered_json](ordered_json.md)
+
+## Version history
+
+- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](ordered_json.md).