Add a "page-type" front matter key

[wbamberg]

(Copied from mdn/yari#3350)

There are places where we want to do things depending on the type of thing a page documents.

One example is a sidebar that wants to group together pages that document particular types of thing. For example, the JSRef sidebar wants to group properties and methods in separate sections:

https://github.com/mdn/yari/blob/9ab36796e8c032b6d20eae65ce5067456bd2f4cf/kumascript/macros/JSRef.ejs#L133-L138

...and the CSSRef sidebar wants to group CSS properties, at-rules, and so on in separate sections:

https://github.com/mdn/yari/blob/9ab36796e8c032b6d20eae65ce5067456bd2f4cf/kumascript/macros/CSSRef.ejs#L332-L338

Currently we use tags for this, but tags don't have clear semantics. For example, suppose we look for "CSS At-rules" tag to find pages that document at-rules. But someone might think the "CSS At-rules" should appear on a guide page about CSS at-rules, and why shouldn't they?

Similarly, for a tag identifying a page that documents a data type, is it "CSS Type" or "Type" or "CSS Data Type" or "Data Type"? To make this work reliably we have to define a particular "subtype" of tags, that have a particular semantics ("page type") and that are allowed to have a particular set of values. But at that point we're just hacking page_type into the generic tag system.

Another example where page type is useful is sidebars. We've talked about having a sidebar front matter item (instead of a KS macro call in content). This is good, but for most pages I think it would be better for the page to say what sort of page it is, and then for Yari to be able to map that onto a sidebar (there are some places where this doesn't work, like guide and landing pages).

But this idea goes beyond our current usages. If we have page types, we can also describe what sorts of things different types of pages should contain, like "every CSS property page should have a BCD table" or even "every JS class page should have a 'Constructor' section", and we can use this to lint our page's content, and potentially to build pages.

Technically, as @peterbe points out in mdn/yari#3350, this basic idea is already possible, since front matter keys are exposed to JS.

So what's needed is:

1. decide if this is a direction we want to take. To me this feels like a big decision really, that unlocks lots of possibilities for MDN, in particular going beyond our site being essentially a pile of undifferentiated blobs of HTML towards being an organized collection of structured content.

2. if we do think this is a good idea, start to define which page types we want to have. This shouldn't end up like tags, where we have hundreds of ill-defined types. We should be careful to define a fairly small set of meaningful types. We did a lot of this work back in stumptown days, and in particular defined complete page types for JS and CSS:

• JS:

  • javascript-class
  • javascript-constructor
  • javascript-error
  • javascript-language-feature
  • javascript-method
  • javascript-namespace
  • javascript-property

• CSS

  • css-at-rule-descriptor
  • css-at-rule
  • css-data-type
  • css-function
  • css-keyword
  • css-media-feature
  • css-property
  • css-selector
  • css-shorthand-property

We also defined "guide" for pages that don't follow any particular structure.

(We also wrote descriptions of what these different page types should contain: https://github.com/mdn/stumptown-content/tree/master/recipes , but that would be for the future).

[peterbe]

Drive-by-comment; If we do this, we should throw an error (not a flaw!) if a page-type is set to a value (technically, a value in an array of values) that is not hardcoded in the Yari builder. This would make a content PR crash and burn in CI early to avoid ever getting typos in. E.g.

page-type: 
  - css-tt-rule-descriptor

Also, if we going down this route we should bite the bullet and rewrite how the page-type is pulled out of the document for the benefit of translated documents. Perhaps this code exemplifies my point:

// SomeSidebar.ejs
const pageType = locale !== 'en-US ? env.doc.getParent().metadata['page-type'] : env.doc.metadata['page-type']

For ease of migration; perhaps we can write it in a very forgiving way. Example implementation:

// SomeSidebar.ejs
let isCSSSelectorPage = false;
let pageType = env.doc.metadata['page-type'];
if (pageType) {
  isCSSSelectorPage = pageType === 'css-selector';
} else {
  // Front-matter hasn't been upgraded yet!
  isCSSSelectorPage = env.doc.metadata.tags.includes("CSS Selector");
  console.warn(`${env.doc.mdn_url}` lacks 'page-type' front-matter. Falling back on tags.`);
}

Not sure that helps. Perhaps it's "obvious" but still felt it worth pointing out.

[wbamberg]

If we do this, we should throw an error (not a flaw!) if a page-type is set to a value (technically, a value in an array of values) that is not hardcoded in the Yari builder.

Yes, definitely!

Also, if we going down this route we should bite the bullet and rewrite how the page-type is pulled out of the document for the benefit of translated documents.

You mean, always use the en-US value? Yes, this should not be translatable. I guess ideally we'd have a way to stop translated pages from changing page-type rather than have to deal with this in the macro code.

[peterbe]

How about we write some code in the KS Node code that just figures all of this out so that when you're inside the KS macro code, you have access to something like env['page-type'] and env['tags'] and these would magically always come from the en-US document (unless it's an orphan translation).

Then, the KS macro code just needs to worry about using these without having to worry about where it came from.

[peterbe]

Nevermind me. Well, the way the CSSRef.ejs works is that it builds the list of links (and their potential "Experimental" or "Deprecated" badge) based on const pageList = await page.subpagesExpand('/en-US/docs/Web/CSS');
So, the tags in translated documents don't matter.
The sidebar gathers the documents from en-US but then, "last-minute", swaps the URL for /fr/ but it also goes through smartLink(). So the French CSS pages' sidebar has the same and correct badges.

[teoli2003]

Just for the record – not CSS though – {{APIRef}} is using tags (also GroupData.json and Interface.json). [But I agree we should get rid of tags in translated-content (at least)].

[hamishwillee]

FWIW Yes, absolutely to all.

• I like the idea of using front-matter for metadata.
• There are cases where we use filename conventions for this kind of thing - e.g. events. Front matter for all "typing" is a more consistent approach.
• There are cases where we have multiple ways effectively to define metadata - macro, BCD, tags, other front-matter, filename. Really for all of these we should use specific metadata. Overriding BCD for some of it if defined in frontmatter. Frontmatter also autogenerating any needed badging if at all possible (e.g. availableinworkers) instead of macros.
• On that note, we should have specific front matter for reflecting state - Deprecated, experimental, whatever.

Somewhere today I suggested that sidebars should be added via frontmatter rather than macro - my logic being that something like {{CSS_Ref}} does not scream out "this is the sidebar to use" in the same way that frontmatter as below might:

sidebar: CSS_ref
sidebar: Something_else_of_interest.

Arguably that is not needed if sidebars are associated with content types.

[teoli2003]

[Not sure how github discussions work: it looks that a question is asked in the initial entry, then people are proposing answers, the actual discussions happen in replies of these, and the answers get updates; people also vote for the proposed answered that are ordered by votes by default. Finally an answer is chosen as the answer and the discussion is close. A kind of StackOverflow]

I'm in favour of having page-type: in front-matter.

Rationale for page-type:

I see having quite a few advantages of having a page-type: directive in front-matter:

• They will be the source of truth for the sidebars macro (or even later, if sidebars type are moved out of the text to front-matter too, as @hamishwillee is proposing.
• It will lower the amount of tags that are difficult to maintain, and lower the burden – or at least the perplexity – of translators
• It will allow to implement page tests in the CI (like controlling the structure of a page given its page-type).
• It will not be missing (like tags sometimes are) and sidebars using it will be more reliable

Like @peterbe said, we should have a fixed set of values, that are enforced by the CI.

First set of values for page-type:

@wbamberg listed a first set of page types for JS and CSS, I'll add some more for API
For JS:

• javascript-class
• javascript-constructor
• javascript-error
• javascript-language-feature
• javascript-method
• javascript-namespace
• javascript-property

For CSS:

• css-at-rule-descriptor
• css-at-rule
• css-data-type
• css-function
• css-keyword
• css-media-feature
• css-property
• css-selector
• css-shorthand-property

For API:

• api-property
• api-method
• api-constructor
• api-interface

Non-goals

1. Even if it is a mid-term goal (and I think a good idea), I would not yet include a sidebar: directive in front-runner as proposed by @hamishwillee ; not because they don't belong there, but because I fear complex issues there (like several sidebars on the same page).
2. I would not create a type guide initially: I'm not sure there will be a unified structure for guide. I'll prefer not to allow a page-type for these pages initially.

How to proceed

Prerequesite (on yari)

As yari already supports page-type, the only prerequisite is to add the check of the acceptable page-type values through CI (yari). We don't need an exhaustive set, as it will be possible to extend them.

Conversion

We don't need to convert all tags in one pass. We can select a group of them, starting with those bringing the more value to the users.

For each set of pages:

1. Check the CI rule to be sure it allows the page-type values needed; if not we add them on yari.
2. Populate the page-type: directive for relevant pages; it can be scripted if tags were used for them). (and update documentation)
3. If needed, update the relevant sidebar macros to use page-type: instead of tags
4. If needed, remove the tags (may be scripted)

After the conversion

I can see further advantages of having the page-type: we could add ci rules to check the structure of such pages. (I would wait for the migration to .md before doing this)

Conclusion

I think a page-type: directive has a clear value for both users and maintenabilty. It has a low impact on dev time (but not zero!) and migration can be broken down in manageable chunk, mostly done by the writers (even the yari PR doesn't need to be writte by the core dev team then).

I really like the idea.

[estelle]

A page-type: has been added to the frontmatter of all /content/ pages. The project is complete, so closing this