Cleaned up formatting in paragraphs and inline code

Fixes #177.

Author: flexseth

key-concepts.md

@@ -6,7 +6,11 @@ In this page we'll break down some of the key concepts and terms associated with
 
 In the context of the WordPress REST API a **route** is a URI which can be mapped to different HTTP methods. The mapping of an individual HTTP method to a route is known as an **endpoint**.
 
-As an example, if we make a `GET` request to the URI `http://oursite.com/wp-json/` we are returned a JSON response showing what routes are available, and what endpoints are available within each route. `/wp-json/` is a route, and when that route receives a `GET` request then that request is handled by the endpoint which displays what is known as the index for the WordPress REST API. The route `wp-json/wp/v2/posts` by contrast has a `GET` endpoint which returns a list of posts, but also a `POST` endpoint which accepts authenticated requests to create new posts.
+As an example, if we make a `GET` request to the URI `http://oursite.com/wp-json/` we are returned a JSON response showing what routes are available, and what endpoints are available within each route. 
+
+`/wp-json/` is a route, and when that route receives a `GET` request then that request is handled by the endpoint which displays what is known as the index for the WordPress REST API. 
+
+The route `wp-json/wp/v2/posts` by contrast has a `GET` endpoint which returns a list of posts, but also a `POST` endpoint which accepts authenticated requests to create new posts.
 
 We will learn how to register our own routes and endpoints in the following sections.
 
@@ -16,7 +20,9 @@ If you get a `404` error when trying to access `http://oursite.com/wp-json/`, co
 
 ## Requests
 
-A REST API request is represented within WordPress by an instance of the `WP_REST_Request` class, which is used to store and retrieve information for the current request. A `WP_REST_Request` object is automatically generated when you make an HTTP request to a registered API route. The data specified in this object (derived from the route URI or the JSON payload sent as a part of the request) determines what response you will get back out of the API.
+A REST API request is represented within WordPress by an instance of the `WP_REST_Request` class, which is used to store and retrieve information for the current request. A `WP_REST_Request` object is automatically generated when you make an HTTP request to a registered API route. 
+
+The data specified in this object (derived from the route URI or the JSON payload sent as a part of the request) determines what response you will get back out of the API.
 
 Requests are usually submitted remotely via HTTP but may also be made internally from PHP within WordPress plugin or theme code. There are a lot of neat things you can do using this class, detailed further elsewhere in the handbook.
 
@@ -26,9 +32,15 @@ Responses are the data you get back from the API. The `WP_REST_Response` class p
 
 ## Schema
 
-Each endpoint requires a particular structure of input data, and returns data using a defined and predictable structure. Those data structures are defined in the API Schema. The schema structures API data and provides a comprehensive list of all of the properties the API can return and which input parameters it can accept. Well-defined schema also provides one layer of security within the API, as it enables us to validate and sanitize the requests being made to the API. The [Schema section](https://developer.wordpress.org/rest-api/extending-the-rest-api/schema/) explores this large topic further.
+Each endpoint requires a particular structure of input data, and returns data using a defined and predictable structure. Those data structures are defined in the API Schema. 
+
+The schema structures API data and provides a comprehensive list of all of the properties the API can return and which input parameters it can accept. 
+
+Well-defined schema also provides one layer of security within the API, as it enables us to validate and sanitize the requests being made to the API. The [Schema section](https://developer.wordpress.org/rest-api/extending-the-rest-api/schema/) explores this large topic further.
 
 
 ## Controller Classes
 
-Controller classes unify and coordinate all these various moving parts within a REST API response cycle. With a controller class you can manage the registration of routes & endpoints, handle requests, utilize schema, and generate API responses. A single class usually contains all of the logic for a given route, and a given route usually represents a specific type of data object within your WordPress site (like a custom post type or taxonomy).
+Controller classes unify and coordinate all these various moving parts within a REST API response cycle. With a controller class you can manage the registration of routes & endpoints, handle requests, utilize schema, and generate API responses. 
+
+A single class usually contains all of the logic for a given route, and a given route usually represents a specific type of data object within your WordPress site (like a custom post type or taxonomy).

using-the-rest-api/linking-and-embedding.md

@@ -5,7 +5,18 @@ The WP REST API incorporates hyperlinking throughout the API to allow discoverab
 
 ## Links
 
-The `_links` property of the response object contains a map of links to other API resources, grouped by "relation." The relation specifies how the linked resource relates to the primary resource. (Examples include "author," describing a relationship between a resource and its author, or "wp:term," describing the relationship between a post and its tags or categories.) The relation is either a [standardized relation](http://www.iana.org/assignments/link-relations/link-relations.xhtml#link-relations-1), a URI relation (like `https://api.w.org/term`) or a Compact URI relation (like `wp:term`). (Compact URI relations can be normalized to full URI relations to ensure full compatibility if required.) This is similar to HTML `<link>` tags, or `<a rel="">` links.
+The `_links` property of the response object contains a map of links to other API resources, grouped by "relation." The relation specifies how the linked resource relates to the primary resource. 
+
+Examples include: 
+- `author` - describing a relationship between a resource and its author
+- `wp:term` - describing the relationship between a post and its tags or categories 
+
+The relation is either a 
+- [standardized relation](http://www.iana.org/assignments/link-relations/link-relations.xhtml#link-relations-1)
+- a `URI relation` - like `https://api.w.org/term`
+- or a `Compact URI relation` - like `wp:term`
+
+ Compact URI relations can be normalized to full URI relations to ensure full compatibility if required. This is similar to HTML `<link>` tags, or `<a rel="">` links.
 
 The links are an object containing a `href` property with an absolute URL to the resource, as well as other optional properties. These include content types, disambiguation information, and data on actions that can be taken with the link.
 
@@ -76,4 +87,4 @@ When embedding a collection response, for instance `/wp/v2/posts?author=1`, the
     }
   }
 }
-```
+```