markup using yaml syntax highlighting

[hamishwillee]

YAML code syntax highlighting is now supported on MDN: mdn/yari#6831

The only usage of it I could find was on the page structure docs. This adds it there.

[github-actions]

Preview URLs

• https://pr19807.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_reference_page_template

Flaws

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_reference_page_template
Title: API reference page template
on GitHub
Flaw count: 10

• macros:
  • /en-us/docs/web/api/mdn (url: /en-US/docs/Web/API/MDN) does not exist
  • /en-US/docs/Web/API/NameOfTheInterface/NameOfTheInterface does not exist
  • /en-US/docs/Web/API/NameOfTheInterface does not exist
  • /en-US/docs/Web/API/NameOfParentInterface does not exist
  • /en-US/docs/Web/API/NameOfTheInterface/property1 does not exist
  • and 4 more flaws omitted
• bad_bcd_queries:
  • No BCD data for query: path.to.feature.NameOfTheInterface

External URLs

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_reference_page_template
Title: API reference page template
on GitHub

No new external URLs

(this comment was updated 2022-08-22 23:00:05.229040)

[Josh-Cena]

Actually this is Markdown. YAML is supported in Markdown as an embedded language. I learned that here: PrismJS/prism#3283 If md doesn't work it's probably because we listed yaml after md in the Prism loading list, and we just need to fix that.

[hamishwillee]

@Josh-Cena

1. I'd take an argument that this should be marked up as "md" because what we're showing here is the text to copy which is in "markdown" - as opposed to trying to show yaml for the sake of yaml. So close if you like.
2. That said, marking up as yaml works and shows your clear intent. I'd much rather than in the normal case than marking up as markdown. If there needs to be a change to the tool to support this via markdown then cool, but an alias should still be added for yaml because I don't think using md for this case helps anyone.
3. There wasn't any other easily discoverable yaml in the docs, which makes this whole conversation take up more time than it was worth :-).

Upshot, close this if you like. I don't plan to ever use md for "real" yaml though, or chase up changes in yari.

[Josh-Cena]

I don't have strong opinions either way. We don't show much YAML/Markdown in actual content anyway, so it's not crucial for the sake of tooling. Front matter is definitely part of Markdown, though.

[queengooborg]

I think that we should keep this set as md, as it would provide better syntax highlighting and make it clearer to readers and tooling alike that the codeblock is Markdown. I feel this scenario is the same reason why we decided to add PowerShell and similar to the syntax highlighting, so that we aren't representing something as a language it is not.

[wbamberg]

I think these blocks are not YAML because they include the front matter delimiters --- which are not part of YAML. So this:

---
title: NameOfTheConstructor()
slug: Web/API/NameOfTheParentInterface/NameOfTheParentInterface
page-type: web-api-constructor
tags:
  - API
  - Constructor
  - Reference
  - Experimental
  - Deprecated
  - Non-standard
browser-compat: path.to.feature.NameOfTheConstructor
---

...is not valid YAML, although this:

title: NameOfTheConstructor()
slug: Web/API/NameOfTheParentInterface/NameOfTheParentInterface
page-type: web-api-constructor
tags:
  - API
  - Constructor
  - Reference
  - Experimental
  - Deprecated
  - Non-standard
browser-compat: path.to.feature.NameOfTheConstructor

...is.

So I think we should close this PR.

[Josh-Cena]

@wbamberg --- is part of YAML. It delimits documents. (A piece of YAML source can have multiple documents)

[hamishwillee]

^^^ FWIW that doesn't change that what we're showing in this particular case is markdown that happens to also be yaml. So I'm happy with the reversion.

[hamishwillee]

I have reverted all the "yaml" to "md" and changed the one case of "plain" to MD. This should be able to merge now.

[Josh-Cena]

The existing code blocks marked with md already seem to work, so this LGTM