News Page: Decide on front matter (metadata) content for news items

[tnabtaf]

Description

The news page will be our first "index" page. These pages list items of a particular type (e.g., news, blog, events, etc.).

To generate the index page we need common metadata for each item. This is implemented in YAML at the front of each page. This issue is about coming up with what the metadata should be for news items.

Tasks

• Determine what the "standard" front matter is in Docusaurus.
  • Examples show title, id and tags but it's not clear what is required or what each does.
• Determine and document what any additional metadata should be on this issue. This will be done in conjunction with issue Contributing HowTo(s) Framework #23

[tnabtaf]

Here's a suggestion to get us started

title:

• Title of news item and the page. Shown on the index page.
• Required.

date:

• Official publication date for the news item. Determines sort order on index page. Use ISO format (YYYY-MM-DD).
• Required.

external_url:

• If the news item is external to this site, then this is the link to the news item.
• If this field has a value then then content part of the page should be empty.
• Optional

tags:

• Tags can be incredibly useful for categorizing web site content.
• We'll need to come up with someway to define a preferred set of tags.
• Optional.

tease:

• Short bit of additional text about the news item. This bit would be shown on the index page.
• Alternatively, we could just sample the first n (20?) words of the news item, which is what many sites do.
• If tease is not provided use the first n words of the post itself as the tease.
• Optional

Other metadata to consider:

updated:

• Some news items get updated.
• Do we care enough to keep track of two (or more?) dates, or should we just update date and manually add text that says when it was originally published.
• Not sure how a separate updated field would impact sort order.
• Use ISO format (YYYY-MM-DD).
• Optional.

authors:

• Some news items have an author. Many won't.
• Two possibilies, if we have this
  1. It could be just a text string
  2. Or, this could have two subfields
  • author_name or person_name
  • author_url or person_url
  • repeated for each author. In this case, the author_url would be optional.
• We could ignore this for now, but we will need to figure it out for the Blog index page.
• Optional

[tnabtaf]

Of these, I lean towards supporting the first 5:

• title, date, external_url, tags and tease.

I like having tease as an option because often the first n words of a post do not make a a good tease.

[tnabtaf]

Discussed on the 2022-11-01 content team call. Updated the tease clause to explicitly say to default to news item content, if a tease is not provided.

[travishathaway]

I'm going to be closing this for now because we have decided against a separate news section for the initial release.