Authoring metadata

[rofe]

Helix Pages currently doesn't give authors full control over metadata values beyond what they choose as title/heading, first larger paragraph and first image in their document.

Several projects have a requirement to extend metadata authoring. Here's a proposal how to do that:

1. The author adds a 2 column table with a single header labeled "Metadata"

+--------------------------------------------+
| Metadata                                   |
+-------------+------------------------------+
| Title       | This is my meta title.       |
+-------------+------------------------------+
| Description | This is my meta description. |
+-------------+------------------------------+
| Image       | https://hlx.blob.core.win... |
+-------------+------------------------------+
| Tags        | Creativity, Photography      |
+-------------+------------------------------+

• all labels are case-insensitive
• images URLs can be provided via upload through Slack Bot
• "Tagger" support TBD

2. helix-word2md and helix-gdoc2md transforms such a table into the following midmatter:

---
metadata:
- title: This is my meta title
- description: This is my meta description.
- image: https://hlx.blob.core.win...
- tags:
  - Creativity
  - Photography
---

3. helix-pipeline or helix-pages then transforms it into metadata tags in HTML:

<meta name="description" content="This is my meta description.">
<meta property="og:title" content="This is my meta title.">
<meta property="og:description" content="This is my meta description.">
<meta property="og:image" content="https://<my_domain>/hlx_12345678.jpg?auto=webp&amp;format=pjpg&amp;optimize=medium&amp;width=1200">
<meta property="og:image:secure_url" content="https://<my_domain>/hlx_12345678.jpg?auto=webp&amp;format=pjpg&amp;optimize=medium&amp;width=1200">
<meta name="twitter:title" content="This is my meta title.">
<meta name="twitter:description" content="This is my meta description.">
<meta name="twitter:image" content="https://<my_domain>/hlx_12345678.jpg?auto=webp&amp;format=pjpg&amp;optimize=medium&amp;width=1200">

• note: blob store URLs are rewritten to use the actual hostname <my_domain>

If no metadata table is present in the content, or only partial properties are provided, Helix Pages will extract the missing metadata values from the content, like it does today.

wdyt?

[rofe]

We could also consider adding support for very specific metadata properties/names, ie.g. by letting authors provide labels like property=og:foo or name=twitter:blah, where the type prefix would inform which meta tag attribute to use.

[davidnuescheler]

i like it a lot. the one thing i would want to test with non-web authors is what they would call this. Metadata especially in one word seems very tech influences. if i think of similar concepts in word processing or documents i would say the "properties" would be more common. on the other hand if an author knows about meta data (especially if they are involved in SEO etc.) meta data seems to be intuitive as well...

[rofe]

Good point. I think it would be great to get input from (ideally non-tech) native speakers on this...
I tried to research the term a bit: Google yields 13M results for meta data vs 164M for metadata. Merriam Webster only seems to list metadata and even made it their "word of the day" back in 2015 😉. In any case, we could definitely add support for metadata, meta data and properties.

[trieloff]

My general rule of couterintuitive naming for engineers would be to pick the more specific name used in the most common use case instead of the "correct" general term.

In this case it would be SEO, which is, unfortunately a faddish acronym with doubtful staying power. So, count me in for Metadata.

[tripodsan]

I see a potential clash with the page blocks (#159 (comment)).

maybe we can use some kind of namespace instead of just metadata, eg: helix:metadata.

[rofe]

Where would you see it clashing? The metadata table would first be translated into a regular block, which would get processed at a later stage and finally deleted before the output.

[Aeroid]

I would support "properties" slightly more than "metadata", sounds a little less technical.

What about existing gdocs properties, couldn't we use them? I would assume there are at least some, but I'm not an gdocs expert. Just stumbled over this: while googling: https://blog.ouseful.info/2015/01/28/adding-metadata-to-google-docs/

[davidnuescheler]

i think it would be great for a range of uses to be able to manage certain meta data in a more table oriented fashion.

so if had a way to address a page's metadata in a dedicated spreadsheet (json source) that would allow for usecases where a centralized approach to metadata is more intuitive.

i envision a table that has a column that identifies the path and additionally columns for the meta properties. i think they could be combined with the meta data on the doc with some sort of precendence.

Path	Keywords	Locale
/en/home	tag1, tag2	en-US
/de/home	tag3, tag4	de-DE

i think it would also be great if the Path allows for globbing patterns.

[rofe]

I think the order of priority should be:

1. metadata spreadsheet (admin provided)
2. metadata block (author provided)
3. content (extracted by helix)

[trieloff]

I think authors should be able to override both our own heuristics and the admin-provided defaults, so:

1. metadata block
2. spreadsheet
3. content

[rofe]

I was pondering that as well... then concluded that hierarchically the admin should win...

[trieloff]

I think authors should win because they have more knowledge about the content and because there would be no other way of setting a metadata property on some, but not all documents.

[rofe]

1 and 3 is implemented in adobe/helix-pages#729

[rofe]

Regarding meta images: I think these can come in the following variety from the document, as plain text, link or pasted image:

|Image|https\://www\.adobe.com/thumb.800.480.png|

|Image|<https://www.adobe.com/thumb.800.480.png>|

|Image|![](https://hlx.blob.core.windows.net/external/d6675ca179a0837756ceebe7f93aba2f14dabde9#image.jpeg)|

leading to the following block row output:

<div><div>Image</div><div>https://www.adobe.com/thumb.800.480.png</div></div>

<div><div>Image</div><div><a href="https://www.adobe.com/thumb.800.480.png">https://www.adobe.com/thumb.800.480.png</a></div></div>

<div><div>Image</div><div><picture><source media="(max-width: 400px)" srcset="/hlx_d6675ca179a0837756ceebe7f93aba2f14dabde9.jpeg?width=750&amp;format=webply&amp;optimize=medium"><img src="/hlx_d6675ca179a0837756ceebe7f93aba2f14dabde9.jpeg?width=2000&amp;format=webply&amp;optimize=medium" alt="" loading="eager"></picture></div></div>

All of these should work and have precedence over the first image in the content.

[rofe]

Arbitrary metadata: besides the well known metadata keys like title, description, image, keywords and tags, authors can also add arbitrary ones like

|Template|default|
|article:publisher|<https://www.facebook.com/Adobe>|

which will get rendered like this:

  <meta name="template" content="default">
  <meta property="article:publisher" content="https://www.facebook.com/Adobe">

[rofe]

@davidnuescheler I was thinking about date values: should we try and parse them and always output UTC date strings?

[davidnuescheler]

i would keep them verbatim as strings, until we have to provide some magic. i have always failed to try to solve date/time problems globally.

[rofe]

From adobe/helix-pages#786: if the metadata block contains a title, that should also win over the first heading 1 in the content as the document title.

[rofe]

@davidnuescheler should we make template a standard property whose value we put in the <html class=""> on the server side?

[davidnuescheler]

I don't think we need to. I think there is no benefit in comparison to doing it on the client.

[rofe]

Zero code 😉