Move docs from README to docs/ dir

README.md

@@ -138,14 +138,6 @@ render json: @post, meta: { total: 10 }, meta_key: "custom_meta"
 
 `meta` will only be included in your response if you are using an Adapter that supports `root`, as JsonAPI and Json adapters, the default adapter (FlattenJson) doesn't have `root`.
 
-### Links
-
-A top-level `links` object may be specified in the `render` call:
-
-```ruby
-render json: @post, links: { self: "/posts/1" }
-```
-
 ### Overriding association methods
 
 If you want to override any association, you can use:

docs/README.md

@@ -12,6 +12,7 @@ This is the documentation of AMS, it's focused on the **0.10.x version.**
 ## How to
 
 - [How to add root key](howto/add_root_key.md)
+- [How to add top-level links](howto/add_top_level_links.md) (```JSON-API``` only)
 
 ## Getting Help
 

docs/howto/add_top_level_links.md

@@ -0,0 +1,31 @@
+# How to add top-level links
+
+JsonApi supports a [links object](http://jsonapi.org/format/#document-links) to be specified at top-level, that you can specify in the `render`:
+
+```ruby
+  render json: @posts, links: { "self": "http://example.com/api/posts" }
+```
+
+That's the result:
+
+```json
+{
+  "data": [
+    {
+      "type": "posts",
+      "id": "1",
+      "attributes": {
+        "title": "JSON API is awesome!",
+        "body": "You should be using JSON API",
+        "created": "2015-05-22T14:56:29.000Z",
+        "updated": "2015-05-22T14:56:28.000Z"
+      }
+    }
+  ],
+  "links": {
+    "self": "http://example.com/api/posts"
+  }
+}
+```
+
+This feature is specific to JsonApi, so you have to use the use the [JsonApi Adapter](https://github.com/rails-api/active_model_serializers/blob/master/docs/general/adapters.md#jsonapi)

test/action_controller/serialization_test.rb

@@ -65,7 +65,7 @@ def render_array_using_implicit_serializer_and_links
               Profile.new({ name: 'Name 1', description: 'Description 1', comments: 'Comments 1' })
             ]
 
-            render json: @profiles, links: { self: "/profiles/1" }
+            render json: @profiles, links: { self: "http://example.com/api/profiles/1" }
           end
         end
 
@@ -292,7 +292,7 @@ def test_render_array_using_implicit_serializer_and_links
             }
           ],
           links: {
-            self: "/profiles/1"
+            self: "http://example.com/api/profiles/1"
           }
         }