Skip to content

Add in-page links, minor formatting #128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add in-page links, minor formatting #128

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 16 additions & 16 deletions pages/version/1.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` <a name="author"></a> (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.

Expand All @@ -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 <a name="items"></a>

`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 <a name="attachments"></a>

Expand All @@ -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",
Expand Down