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.

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."