More md cleaning

docs/api/api.md

@@ -1,5 +1,3 @@
-
-
 # API
 
 An Application Programming Interface (API) allows you to connect your code to eZ Platform.
@@ -8,7 +6,7 @@ From the eZ Blog: [How would you explain what an API is to your mom](http://ez.
 
 eZ Platform offers two APIs:
 
-1.  The [REST API](https://doc.ez.no/display/DEVELOPER/REST+API+Guide) allows you to interact with an eZ Platform installation using the HTTP protocol, following a REST interaction model
-2.  The [Public (PHP) API](https://doc.ez.no/display/DEVELOPER/Public+API+Guide) exposes a Repository which allows you to create, read, update, manage and delete all objects available in eZ Platform, first and foremost content, but also related objects like sections, locations, content types, content types groups, languages and so on.
+1.  The [REST API](rest_api_guide.md) allows you to interact with an eZ Platform installation using the HTTP protocol, following a REST interaction model
+2.  The [Public (PHP) API](public_php_api.md) exposes a Repository which allows you to create, read, update, manage and delete all objects available in eZ Platform, first and foremost content, but also related objects like sections, locations, content types, content types groups, languages and so on.
 
-There is also a [JavaScript API Client](JS-Client_31429579.html), useful for working with eZ Platform as a [headless CMS](http://ez.no/Blog/Content-as-a-Service-CaaS-Decoupled-CMS-and-Headless-CMS-101).
+There is also a [JavaScript API Client](js_client.md), useful for working with eZ Platform as a [headless CMS](http://ez.no/Blog/Content-as-a-Service-CaaS-Decoupled-CMS-and-Headless-CMS-101).

docs/api/extending_the_rest_api.md

@@ -1,5 +1,3 @@
-
-
 # Extending the REST API
 
 The eZ Platform REST API comes with a framework that makes it quite easy to extend the API for your own needs.
@@ -152,11 +150,11 @@ class Hello extends ValueObjectVisitor
 }
 ```
 
-Do not hesitate to look into the built-in ValueObjectVisitors, in `           eZ/Publish/Core/REST/Server/Output/ValueObjectVisitor         `, for more examples.
+Do not hesitate to look into the built-in ValueObjectVisitors, in `eZ/Publish/Core/REST/Server/Output/ValueObjectVisitor`, for more examples.
 
 ### Cache handling
 
-The easiest way to handle cache is to re-use the `           CachedValue         ` Value Object. It acts as a proxy, and adds the cache headers, depending on the configuration, for a given object and set of options.
+The easiest way to handle cache is to re-use the `CachedValue` Value Object. It acts as a proxy, and adds the cache headers, depending on the configuration, for a given object and set of options.
 
 When you want the response to be cached, return an instance of CachedValue, with your Value Object as the argument. You can also pass a location id using the second argument, so that the Response is tagged with it:
 
@@ -249,7 +247,7 @@ You can register newly added resources so that they show up in the REST root res
 
 New resources can be registered with code like this:
 
-```
+``` yaml
 ez_publish_rest:
     system:
         default:

docs/api/general_rest_usage.md

@@ -1,21 +1,19 @@
-
-
 # General REST usage
 
 
-As explained in the [introduction](../api/rest_api_guide.md), the REST API is based on a very limited list of general principles:
+As explained in the [introduction](rest_api_guide.md), the REST API is based on a very limited list of general principles:
 
 -   each resource (uri) interacts with a part of the system (Content, URL aliases, User Groups, etc.),
 -   for each resource, one or more verbs are available, each having a different effect (delete a Content item, get a URL Alias, list user groups, etc.),
 -   media-type request headers indicate what type of data (Content / ContentInfo), and data format (JSON or XML), are expected as a response, and what can be requested.
 
 ## Anatomy of a REST call
 
-## What we can learn from a GET request
+### What we can learn from a GET request
 
 This verb is used to query the API for information. It is one of the two operations web browsers implement, and the one most commonly used.
 
-## Request
+### Request
 
 The only requirement for this verb is usually the resource URI, and the accept header. On top of that, cache request headers can be added, like `If-None-Match`, but those aren't fully implemented yet in eZ Publish 5.0.
 
@@ -45,17 +43,17 @@ Content-Length: xxx
 
 The length of our content, provided by the Content-Length header, isn't *that* useful.
 
-## HTTP Code
+###### HTTP Code
 
 The API responded here with a standard 200 OK HTTP response code, which is the expected response code for a "normal" GET request. Some GET requests, like [getting a Content item's current version](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#13241%C2%A0%C2%A0%C2%A0get-current-version), may reply with a 301 Moved permanently, or 307 Temporary redirect code.
 
 Errors will be indicated with HTTP error codes, like 404 for Not Found, or 500 for Internal server error. The [REST specifications](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst) provide the list of every HTTP response code you can expect from implemented resources.
 
-## Content-Type header
+###### Content-Type header
 
 As long as a response contains an actual HTTP body, the Content-Type header will be used to specify which Content-Type is contained in the response. In that case, a ContentInfo (`Content-Type: application/vnd.ez.api.ContentInfo`) in XML (`Content-Type: application/vnd.ez.api.ContentInfo+xml`)
 
-## Accept-Patch header
+###### Accept-Patch header
 
 This is a very interesting one.
 
@@ -65,17 +63,17 @@ This last part means that if we send a PATCH /content/objects/23 request with a
 
 REST will use the `Accept-Patch` header to indicate how to **modify** the returned **data**.
 
-## Other headers: Location
+###### Other headers: Location
 
 Depending on the resource, request & response headers will vary. For instance, [creating content](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#13231%C2%A0%C2%A0%C2%A0creating-content), or [getting a Content item's current version](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#13241%C2%A0%C2%A0%C2%A0get-current-version) will both send a `Location` header to provide you with the requested resource's ID.
 
 Those particular headers generally match a specific list of HTTP response codes. Location is sent by `201 Created`, `301 Moved permanently,` `307 Temporary redirect responses`. This list isn't finished, but you can expect those HTTP responses to provide you with a Location header.
 
-## Other headers: Destination
+###### Other headers: Destination
 
 This request header is the request counterpart of the Location response header. It is used in a COPY / MOVE operation, like [copying a Content item](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#13236%C2%A0%C2%A0%C2%A0copy-content), on a resource to indicate where the resource should be moved to, using the ID of the destination.
 
-## Response body
+#### Response body
 
 **Load ContentInfo response body**  Expand source
 
@@ -105,7 +103,7 @@ As explained above, the API has told us that we could modify content object 23 b
 
 The REST API data structs mostly match a PHP Public API value object
 
-## Value objects representation
+#### Value objects representation
 
 Value objects like [ContentInfo](https://github.com/ezsystems/ezp-next/blob/master/eZ/Publish/API/Repository/Values/Content/ContentInfo.php) basically feature two types of fields: basic, local fields (modified, name...) and foreign field(s) references (sectionId, mainLocationId).
 
@@ -167,11 +165,7 @@ Accept: application/vnd.ez.api.Root+json
 X-Siteaccess: ezdemo_site_admin
 ```
 
-
-
-
-
-# REST API Authentication
+## REST API Authentication
 
 
 The REST API supports two authentication methods: session, and basic. 
@@ -181,21 +175,21 @@ The REST API supports two authentication methods: session, and basic. 
 
 Session-based is the default authentication method, as this is needed for UI.
 
-## Session based authentication
+### Session based authentication
 
 This authentication method requires a Session cookie to be sent with each request.
 
 If this authentication method is used with a web browser, this session cookie is automatically available as soon as your visitor logs in. Add it as a cookie to your REST requests, and the user will be authenticated.
 
-### Logging in
+#### Logging in
 
 It is also possible to create a session for the visitor if they aren't logged in yet. This is done by sending a **`POST`** request to `/user/sessions`. Logging out is done using a **`DELETE`** request on the same resource.
 
 More information
 
 [Session-based authentication chapter of the REST specifications](https://github.com/ezsystems/ezp-next/blob/master/doc/specifications/rest/REST-API-V2.rst#123%C2%A0%C2%A0%C2%A0session-based-authentication)
 
-## HTTP Basic authentication
+### HTTP Basic authentication
 
 To enable HTTP Basic authentication, you need to edit app`/config/security.yml`, and add/uncomment the following block. Note that this is enabled by default.
 
@@ -222,46 +216,46 @@ Accept: application/vnd.ez.api.Root+json
 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
 ```
 
-## Error handling
+### Error handling
 
 Error handling in the REST API is fully based on HTTP error codes. As a web developer, you are probably familiar with the most common ones: 401 Unauthorized, 404 Not Found or 500 Internal Server Error. The REST API uses those, along with a few more, to allow proper error handling.
 
 The complete list of error codes used and the conditions in which they apply are specified in the [reference documentation](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst).
 
-## General error codes
+### General error codes
 
 A few error codes apply to most resources (if they *are* applicable)
 
-### 500 Internal Server Error
+#### 500 Internal Server Error
 
 The server encountered an unexpected condition, usually an exception, which prevented it from fulfilling the request: database down, permissions or configuration error.
 
-### 501 Not Implemented
+#### 501 Not Implemented
 
 Returned when the requested method has not yet been implemented. As of eZ Publish 5.0, most of User, User group, Content, Location and Content Type have been implemented. Some of their methods, as well as other features, may return a 501.
 
-### 404 Not Found
+#### 404 Not Found
 
 Returned when the request failed because the request object was not found. You should be familiar with this one.
 
-### 405 Method Not Allowed
+#### 405 Method Not Allowed
 
 Returned when the requested REST API resource doesn't support the HTTP verb that was used.
 
-### 406 Not Acceptable
+#### 406 Not Acceptable
 
 Returned when an accept header sent with the requested isn't supported.
 
-## Error handling in your REST implementation
+### Error handling in your REST implementation
 
 It is up to you, in your client implementation, to handle those codes by checking if an error code (4xx or 5xx) was returned instead of the expected 2xx or 3xx.
 
-## REST API Countries list
+### REST API Countries list
 
 
 Countries list is a REST service that gives access to an [ISO-3166](http://en.wikipedia.org/wiki/ISO_3166) formatted list of world countries. It is useful when presenting a country options list from any application.
 
-## Get the list of countries
+### Get the list of countries
 
 To send a GET request to the REST API Countries list, you have to provide the Content Type header `application/vnd.ez.api.CountriesList+xml`.
 
@@ -273,11 +267,7 @@ Method: GET
 Content-Type: application/vnd.ez.api.CountriesList+xml
 ```
 
-See the [General REST usage documentation page](General-REST-usage_31430291.html) for further information.[](https://gist.github.com/bdunogier/8665017#example)
-
-### Usage example
-
-
+#### Usage example
 
 **Countries list request**
 
@@ -287,8 +277,6 @@ Host: example.com
 Accept: application/vnd.ez.api.CountriesList+xml
 ```
 
-
-
 The HTTP response will it be with a 200 OK Header.
 
 **Countries list response headers**
@@ -298,8 +286,6 @@ HTTP/1.1 200
 Content-Type: application/vnd.ez.api.CountriesList+xml
 ```
 
-
-
 And the body of the Response is XML formatted country list with names and codes according to the ISO-3166 standard. 
 
 ISO-3166

docs/api/js_client.md

@@ -1,11 +1,9 @@
-
-
 # JS Client
 
 
 The JavaScript REST API Client is a JavaScript library meant to ease the use of the eZ Platform REST API. For now, it can only be used in a web browser.
 
-See [Using the JavaScript REST API Client](Using-the-JavaScript-REST-API-Client_31430299.html) for a guide on how to use the client, and view the [generated JS API Client reference](http://ezsystems.github.io/javascript-rest-client/).
+See [below](#using-the-javascript-rest-api-client) for a guide on how to use the client, and view the [generated JS API Client reference](http://ezsystems.github.io/javascript-rest-client/).
 
 
 ## Using the JavaScript REST API Client
@@ -15,7 +13,7 @@ The JavaScript REST API Client is a JavaScript library meant to ease the use of
 
 ## Installation
 
-## In the PlatformUIAssetsBundle
+### In the PlatformUIAssetsBundle
 
 Since the JavaScript REST Client is one of the foundations of [the Platform Backend Interface](../guide/extending_ez_platform_ui.md), the client is provided by the [PlatformUIAssetsBundle](https://github.com/ezsystems/PlatformUIAssetsBundle) which is installed by default. As a result, the client is directly available and can be embedded in any Platform-generated page with the following Twig code:
 
@@ -27,7 +25,7 @@ Since the JavaScript REST Client is one of the foundations of [the Platform Back
 <!-- <script src="{{ asset('bundles/ezplatformuiassets/vendors/ez-js-rest-client/dist/CAPI-min.js') }}"></script> -->
 ```
 
-## With Bower
+### With Bower
 
 Alternatively, the JavaScript REST Client can be installed directly in any project with [Bower](http://bower.io/):
 
@@ -45,7 +43,7 @@ It is also possible to directly retrieve either `dist/CAPI.js` or `dist/CAPI-min
 
 ## Usage examples
 
-Once included, `CAPI.js` exports the `eZ` namespace which contains `eZ.CAPI`, the constructor function of the client. This constructor must receive the API end point and an authentication agent responsible for handling the authentication (session or basic auth). This is detailed in the [Instantiation and authentication](http://doc.ez.no#UsingtheJavaScriptRESTAPIClient-Instantiationandauthentication) section below.
+Once included, `CAPI.js` exports the `eZ` namespace which contains `eZ.CAPI`, the constructor function of the client. This constructor must receive the API end point and an authentication agent responsible for handling the authentication (session or basic auth). This is detailed in the [Instantiation and authentication](#instantiation-and-authentication) section below.
 
 [The auto-generated API documentation of the JavaScript REST API client is available online.](http://ezsystems.github.io/javascript-rest-client) Like in the Public API, the code is organized around 3 main services:
 
@@ -58,16 +56,16 @@ In essence, the operations available through those services are asynchronous, so
 1.  `error`: depending on the success of the operation, this parameter is either `false` or a [`CAPIError`](http://ezsystems.github.io/javascript-rest-client/classes/CAPIError.html) instance representing the error
 2.  `response`: it's always of a [`Response`](http://ezsystems.github.io/javascript-rest-client/classes/Response.html) instance allowing you to retrieve any information from the REST API response
 
-## Instantiation and authentication
+### Instantiation and authentication
 
 [The `eZ.CAPI` constructor function](http://ezsystems.github.io/javascript-rest-client/classes/CAPI.html) expects two parameters:
 
 1.  the API end point URI
-2.  an authentication agent instance to configure the client for [the authentication mechanism configuration in eZ Platform](../general_rest_usage.md#REST-API-Authentication).
+2.  an authentication agent instance to configure the client for [the authentication mechanism configuration in eZ Platform](general_rest_usage.md#rest-api-authentication).
 
 The JavaScript REST Client comes with two authentication agents for the Session and Basic Auth authentication mechanism.
 
-## Session auth
+#### Session auth
 
 The Session Auth Agent expects an object describing the existing Session or containing the credentials for the user to create the corresponding session. So if the user is not yet authenticated, the client can be instantiated with:
 
@@ -121,7 +119,7 @@ capi.isLoggedIn(function (error, response) {
 });
 ```
 
-## Basic auth
+#### Basic auth
 
 When configured in the Basic Authentication, the basic auth agent just expects the user's credentials:
 
@@ -147,7 +145,7 @@ capi.logIn(function (error, response) {
 });
 ```
 
-## Loading a ContentInfo or a Content
+### Loading a ContentInfo or a Content
 
 To load a ContentInfo, you need [the Content Service](http://ezsystems.github.io/javascript-rest-client/classes/ContentService.html), it is returned by the `getContentService` method on the client instance:
 
@@ -178,7 +176,7 @@ contentService.loadContentInfo(contentRestId, function (error, response) {
 
 If you run this example, you should see in the browser network panel a GET HTTP request to <http://example.com/api/ezp/v2/content/objects/1> with the necessary headers to get a JSON representation of the ContentInfo. If you want to load the Content instead, you can use [the `loadContent` method](http://ezsystems.github.io/javascript-rest-client/classes/ContentService.html#method_loadContent).
 
-## Moving a Location
+### Moving a Location
 
 To move a Location, [the Content Service](http://ezsystems.github.io/javascript-rest-client/classes/ContentService.html) is also needed, this operation will generate a MOVE HTTP request. If configured for the session authentication mechanism, the client will automatically add the CSRF Token.
 
@@ -207,9 +205,9 @@ contentService.moveSubtree(locationRestId, newParentLocationRestId, function (er
 })
 ```
 
-## Searching for Content or Location
+### Searching for Content or Location
 
-Searching for Content or Location can be done with [REST views](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#views). REST views can be configured with the [search engine criteria](../guide/search_criteria_reference.md) to match some Content items or Locations:
+Searching for Content or Location can be done with [REST views](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#views). REST views can be configured with the [search engine criteria](../guide/search.md#search-criteria-reference) to match some Content items or Locations:
 
 **REST views**
 
@@ -240,7 +238,7 @@ contentService.createView(query, function (error, response) {
 })
 ```
 
-REST views
+!!! note "REST views"
 
-REST views are designed to be persisted but this feature is not yet implemented. As a result, when calling `createView`, the POST request does not create the view but directly returns the results.
+    REST views are designed to be persisted but this feature is not yet implemented. As a result, when calling `createView`, the POST request does not create the view but directly returns the results.