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/examples/ordered_map.cpp

@@ -0,0 +1,43 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// simple output function
+template<typename Map>
+void output(const char* prefix, const Map& m)
+{
+    std::cout << prefix << " = { ";
+    for (auto& element : m)
+    {
+        std::cout << element.first << ":" << element.second << ' ';
+    }
+    std::cout << "}" << std::endl;
+}
+
+int main()
+{
+    // create and fill two maps
+    nlohmann::ordered_map<std::string, std::string> m_ordered;
+    m_ordered["one"] = "eins";
+    m_ordered["two"] = "zwei";
+    m_ordered["three"] = "drei";
+
+    std::map<std::string, std::string> m_std;
+    m_std["one"] = "eins";
+    m_std["two"] = "zwei";
+    m_std["three"] = "drei";
+
+    // output: m_ordered is ordered by insertion order, m_std is ordered by key
+    output("m_ordered", m_ordered);
+    output("m_std", m_std);
+
+    // erase and re-add "one" key
+    m_ordered.erase("one");
+    m_ordered["one"] = "eins";
+
+    m_std.erase("one");
+    m_std["one"] = "eins";
+
+    // output: m_ordered shows newly added key at the end; m_std is again ordered by key
+    output("m_ordered", m_ordered);
+    output("m_std", m_std);
+}