diff --git a/pages/version/1.markdown b/pages/version/1.markdown
index 1837bc666..08e2e4398 100644
--- a/pages/version/1.markdown
+++ b/pages/version/1.markdown
@@ -75,7 +75,7 @@ After that there’s an array of objects — `items` — that describe each obj
* `favicon` (optional, string) is the URL of an image for the feed suitable to be used in a source list. It should be square and relatively small, but not smaller than 64 x 64 (so that it can look good on retina displays). As with `icon`, this image should use transparency where appropriate, since it may be rendered on a non-white background.
-* `author` (optional, object) specifies the feed author. The author object has several members. These are all optional — but if you provide an author object, then at least one is required:
+* `author` (optional, object) specifies the feed author. The author object has several members. These are all optional — but if you provide an author object, then at least one is required:
* `name` (optional, string) is the author’s name.
@@ -85,35 +85,35 @@ After that there’s an array of objects — `items` — that describe each obj
* `expired` (optional, boolean) says whether or not the feed is finished — that is, whether or not it will ever update again. A feed for a temporary event, such as an instance of the Olympics, could expire. If the value is `true`, then it’s expired. Any other value, or the absence of `expired`, means the feed may continue to update.
-* `hubs` (very optional, array of objects) describes endpoints that can be used to subscribe to real-time notifications from the publisher of this feed. Each object has a `type` and `url`, both of which are required. See the section “Subscribing to Real-time Notifications” below for details.
+* `hubs` (very optional, array of objects) describes endpoints that can be used to subscribe to real-time notifications from the publisher of this feed. Each object has a `type` and `url`, both of which are required. See the section “[Subscribing to Real-time Notifications](#subscribing-to-real-time-notifications)” below for details.
### Items
-`items` is an array, and is required. An item includes:
+* `items` (required, array) Each item includes:
-* `id` (required, string) is unique for that item for that feed over time. If an item is ever updated, the `id` should be unchanged. New items should never use a previously-used `id`. If an `id` is presented as a number or other type, a JSON Feed reader must coerce it to a string. Ideally, the `id` is the full URL of the resource described by the item, since URLs make great unique identifiers.
+ * `id` (required, string) is unique for that item for that feed over time. If an item is ever updated, the `id` should be unchanged. New items should never use a previously-used `id`. If an `id` is presented as a number or other type, a JSON Feed reader must coerce it to a string. Ideally, the `id` is the full URL of the resource described by the item, since URLs make great unique identifiers.
-* `url` (optional, string) is the URL of the resource described by the item. It’s the permalink. This may be the same as the `id` — but should be present regardless.
+ * `url` (optional, string) is the URL of the resource described by the item. It’s the permalink. This may be the same as the `id` — but should be present regardless.
-* `external_url` (very optional, string) is the URL of a page elsewhere. This is especially useful for linkblogs. If `url` links to where you’re talking about a thing, then `external_url` links to the thing you’re talking about.
+ * `external_url` (very optional, string) is the URL of a page elsewhere. This is especially useful for linkblogs. If `url` links to where you’re talking about a thing, then `external_url` links to the thing you’re talking about.
-* `title` (optional, string) is plain text. Microblog items in particular may omit titles.
+ * `title` (optional, string) is plain text. Microblog items in particular may omit titles.
-* `content_html` and `content_text` are each optional strings — but one or both must be present. This is the HTML or plain text of the item. Important: the only place HTML is allowed in this format is in `content_html`. A Twitter-like service might use `content_text`, while a blog might use `content_html`. Use whichever makes sense for your resource. (It doesn’t even have to be the same for each item in a feed.)
+ * `content_html` and `content_text` are each optional strings — but one or both must be present. This is the HTML or plain text of the item. Important: the only place HTML is allowed in this format is in `content_html`. A Twitter-like service might use `content_text`, while a blog might use `content_html`. Use whichever makes sense for your resource. (It doesn’t even have to be the same for each item in a feed.)
-* `summary` (optional, string) is a plain text sentence or two describing the item. This might be presented in a timeline, for instance, where a detail view would display all of `content_html` or `content_text`.
+ * `summary` (optional, string) is a plain text sentence or two describing the item. This might be presented in a timeline, for instance, where a detail view would display all of `content_html` or `content_text`.
-* `image` (optional, string) is the URL of the main image for the item. This image may also appear in the `content_html` — if so, it’s a hint to the feed reader that this is the main, featured image. Feed readers may use the image as a preview (probably resized as a thumbnail and placed in a timeline).
+ * `image` (optional, string) is the URL of the main image for the item. This image may also appear in the `content_html` — if so, it’s a hint to the feed reader that this is the main, featured image. Feed readers may use the image as a preview (probably resized as a thumbnail and placed in a timeline).
-* `banner_image` (optional, string) is the URL of an image to use as a banner. Some blogging systems (such as [Medium](https://medium.com/)) display a different banner image chosen to go with each post, but that image wouldn’t otherwise appear in the `content_html`. A feed reader with a detail view may choose to show this banner image at the top of the detail view, possibly with the title overlaid.
+ * `banner_image` (optional, string) is the URL of an image to use as a banner. Some blogging systems (such as [Medium](https://medium.com/)) display a different banner image chosen to go with each post, but that image wouldn’t otherwise appear in the `content_html`. A feed reader with a detail view may choose to show this banner image at the top of the detail view, possibly with the title overlaid.
-* `date_published` (optional, string) specifies the date in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. (Example: `2010-02-07T14:04:00-05:00`.)
+ * `date_published` (optional, string) specifies the date in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. (Example: `2010-02-07T14:04:00-05:00`.)
-* `date_modified` (optional, string) specifies the modification date in RFC 3339 format.
+ * `date_modified` (optional, string) specifies the modification date in RFC 3339 format.
-* `author` (optional, object) has the same structure as the top-level `author`. If not specified in an item, then the top-level `author`, if present, is the author of the item.
+ * `author` (optional, object) has the same structure as the [top-level](#author) `author`. If not specified in an item, then the top-level `author`, if present, is the author of the item.
-* `tags` (optional, array of strings) can have any plain text values you want. Tags tend to be just one word, but they may be anything. Note: they are not the equivalent of Twitter hashtags. Some blogging systems and other feed formats call these categories.
+ * `tags` (optional, array of strings) can have any plain text values you want. Tags tend to be just one word, but they may be anything. Note: they are not the equivalent of Twitter hashtags. Some blogging systems and other feed formats call these categories.
#### Attachments
@@ -135,7 +135,7 @@ An individual item may have one or more attachments.
Publishers can use custom objects in JSON Feeds. Names must start with an `_` character followed by a letter. Custom objects can appear anywhere in a feed.
-For instance, imagine a podcast directory service — call it Blue Shed Podcasts — that asks a podcaster to specify some additional information about a feed or item. A publisher would do something like this:
+For instance, imagine a podcast directory service — call it "Blue Shed Podcasts" — that asks a podcaster to specify some additional information about a feed or item. A publisher would do something like this:
"_blue_shed": {
"about": "https://blueshed-podcasts.com/json-feed-extension-docs",