Link List

We haven't fully defined the link list data type, breaking changes may still be made.

A link list is a standard format for representing a list of external resources used in various places on the site.

Attribute Reference

Attribute Job Description
type
string 		Type of the resource

Non-exhaustive common types are listed in _data/link-types.yaml.
href
string 		URL of the resource

Should be wrapped in quotes.
snapshot
string 		Archive snapshot reference

The five-character archive.is snapshot reference. References are case-sensitive.
href_snapshot
string 		URL to archive snapshot
username
string 		Username on a service.

If type has an href attribute in _data/link-types.yaml you must use this field instead of href, otherwise omit.
title
string 		Title of resource

Useful for headlines of news articles. Only include if suitable.
icon
string 		Icon class

Usually set by link type
date
date 		Date resource was published

Useful for news articles. Formatted YYYY-MM-DD. Only include if suitable.
publisher
String 		Name of publisher

Useful for news articles, required for reviews.
rating
string 		Rating (or stars) a review gave

Only applies to reviews. Write as x/of_y, i.e 5/10.
quote
string 		Short quote from resource

Applicable for news stories or reviews. A short quotation summarising the resource.
note
string 		A visible note about the resource

Displayed as a title on the anchor.
comment
string 		Reserved for editor comments

Displayed in editors’ mode.

Archiving Resources

Linking to many online resources as part of a long-term project is risky. Websites may close or re-arrange their URLs rendering our links broken. To protect against this editors should create snapshots of resources when they link to them. These snapshots save the state of those resources at a single point in time. Unless the archiving service closes we should have a permanent record of all resources with snapshots.

We currently use archive.is to create snapshots. Snapshots are created by entering the URL of the resource to be saved on the archive.is website. A page will be returned with a five-character reference code in the URL. For example archiving example.com returns page whose URL is https://archive.fo/oYs92, the reference code is oYs92. This code should be placed in the snapshot attribute of the link list item.

Example Link List

links:
  - type: Example Domain
    href: "https://example.com"
    snapshot: oYs92
    title: Example Domain
  - type: News Story
    href: "https://news.com/a-story"
    snapshot: abc12
    title: A Story
    date: 1980-01-01
    quote: "A very interesting quotation."