Nomenclature

[MattWilcox]

"Style": "h1"

Should not be "style", a heading is not a style, it's a semantic label for type of content in the text node. This property seems to have a confusing name. Style decoration (this should look like whatever a h3 might) should not be tied to the semantic label of the text node, and the existence of "style" here seems confusing.

Additionally, I would question the use of baked in HTML heading levels in an abstracted text format such as this. Heading levels are a design mistake of HTML, and should properly be inferred from the context of the document and nesting of section elements. Within an abstracted block of text, a "level" is not relevant, merely the fact that it is a heading for the following text nodes. A "level" becomes relevant only in a larger context, and baking that into the fragment harms portability.

[kmelve]

Yes, that’s a good point about the “h1”. We’ll change the example and clearify. Will leave this open until then 👍.

[MattWilcox]

Ok, I may be confused as I'm not currently seeing any method to mark the semantics for a text node, where I am seeing a "style" property for which the purpose is to indicate a "visual style"?

I may be confused, but I thought the purpose of the project was to encode rich text - which to my thinking would not have anything at all to do with visual representation of that text - that should be a matter for the render engine?

I'd have thought the goal would be to mark "this chunk is a paragraph" and "this chunk is a heading" or "this chunk is emphasised"; all of which mean things and those meanings may be expressed visually, or through a screen reader, or via a UI of some sort (like heading navigation) ... but those are not the same as "style".

[SteveALee]

I initially thought the the same but now think it's actually both a style hook and semantic. The example uses as purely styling but HTML uses it semantically too.

As Mat says Portable Text has no semantics for heading level but I guess rendering to HTML it gets introduced (I've not tested this), based purely on the style name. This might need to be made explicit. If users have semantics like heading level then the format needs a way to capture and express that.

Semantics like heading level ARE important for non visual renders like screen readers accessing HTML for accessibility or speech agents.

I think some accessibility features need to be encoded in the Portable Text (eg Alt for images) and others appear during rendering, perhaps through heuristics based on the portable text content.