Support "weight" as a front matter item

[wbamberg]

This is a bit vague at the moment but I think it is potentially useful.

The problem

We quite often want to say that a collection of pages is an ordered set, in which we expect the reader to start at the first and progress through to the last.

Examples of this:

• throughout the Learn area, which is composed of "modules", where each module is an ordered set of articles that build on each other. For example: https://developer.mozilla.org/en-US/docs/Learn/JavaScript/First_steps .
• domain-specific tutorials, like https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/Tutorial.
• the JS Guide: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide

Guides under Web/API are also ordered, although it's less clear there. Typically we want to start off with "Using the XYZ" API, present common usages, then move into more niche usages in later articles.

So the main thing here is that we want to present these guides in a certain order (for example in sidebars). We generally do this by listing them in various spots, like in the sidebar macro itself or in another config file like GroupData.json.

Another thing is that we want to provide Next/Previous links in the articles. We do this by making authors add the relevant macro calls at the tops and bottoms of the articles, passing the next/previous links as arguments.

In some cases we also want to list all the articles in a series, as we do in the Learn area for example: https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/JavaScript_basics#in_this_module . We do this, again, manually, by adding a ist of links.

There's a lot of duplication here! Especially for Learn we are duplicating this structure in the sidebar, in the macro calls, and hardcoded into each page. Keeping it all up to date is hard and we often make mistakes. It also leads to inconsistencies where we forget to include it in one page or another, or put the list in a different place, or format the links differently, or...

The solution

Other SSGs deal with this using the concept of "weight". You assign a weight to each article in a series, and the platform lets you order them by weight.

On MDN for now this might mean that:

• we have an optional front matter item, "weight". Or it could even be mandatory for guide pages.
• a sidebar macro could get a list of subpages and order them by weight
• if a collection of pages at a single level of the tree sets weight, Yari could figure out the order and automatically insert Next/Previous links and a list of all the articles in the series

[teoli2003]

I like this idea. I think this will solve the ordering problem for guides and tutorials.

We should make it mandatory for guides (we want the order to be a content decision) and forbidden for all page types that don't use it (or else it won't be maintainable). We can be restrictive at first, and open the system to more page types if the need appears.

Like for page-type: headers, we need to have at least one use of weight: as maintaining these will be done only if there is an outcome to do this. We see this with tags: experimental, non-standard, …, and property, interface, … are all relatively well-maintained as they are used to display sidebars correctly, all the other tags are not. That's why I think we should update {{APIRef}} and {{DefaultAPISidebar}} to use both (or even one!) YAML headers asap, even without a final, better sidebar system.

[hamishwillee]

This looks a bit like slapping a Band-Aid on the broken sidebar. The discussion of weighting is perfectly reasonable, but we should not predicate it on things like learn modules or problems with ordering. If the sidebar provided context you could use any ordering approach you liked.

Rant over for now, one day common sense will prevail. My thoughts on this topic:

There are three common approaches for sidebar organization

• Monolithic sidebar definition
• Document child-level sidebar (a document defines the sidebar structure of its immediate children)
• Weighted sidebar definition by folder

MDN is kind of a hybrid of the first two with a monolithic definition, various dynamic import mechanisms, and quicklinks.

All the approaches have their upsides/downsides.

• A monolithic sidebar means you can "see" the structure of your sidebar where you edit it. Also popular when people want to manage the sidebar and not accidentally break the structure (i.e. a "non trusting" model)
• Weighting puts control in author hands, in the same place as the document is written. Downside is that it is a bit of a pain to visualize the order without building the docs. Also it can result in unpredictable behaviour if it is possible to pull a document in to multiple places. People like me hate having to update the order of all the docs in a series because we discovered we had a new doc that needed to go in the middle of the weighting.
• Document-based nesting is a half-way house. As for weighting, hard to get a big picture of the sidebar. It is also too easy to lose a document from the tree and all it's nested items. Nice because you can have separate subtrees

[wbamberg]

I'm not sure I understand everything here, but this is not just about sidebars. Whatever sidebar implementation we have, there's sometimes we need to present a collection of pages in a curated (i.e. not alphabetical) order. I can think of two main approaches:

• you list the pages in order, like we currently do in sidebars
• you have weighting

These correspond to your 1 and 3 I guess? I'm not sure I understand your 2.

But this ordering is not just for sidebars but is needed in other places, like next/previous links (and even possibly landing pages). So if the order is defined in the sidebar definition, then it's hard for these other usages to use that definition, and we end up having to specify the order in multiple places, which I really hate. I'm sure you know this, but updating the nav when you add new docs to the Learn area is ridiculously hard and error-prone.

When I was playing with this for stumptown I thought, we could separate out the concept of an "ordered list of pages", and let sidebars reference this list, and we could also use the list to build next/previous links or sections of landing pages. But the problem with that is it gives you a new thing - the reusable list of pages - to understand and keep track of, and put somewhere, and... So now I think weighting is better, because there's no new stuff, just a new front matter item.

Downside is that it is a bit of a pain to visualize the order without building the docs.

Yeah, I agree about that.

[hamishwillee]

Thanks for the explanation. It's disappointing this can't be inferred from the existing sidebar. I can see how adding weighting would be a much smaller change than other options.

So "2" is what sphinx-doc does, as discussed here. Essentially this works by a doc listing its immediate-child docs in a "macro". Those child docs are then added as sub-page-peers in the sidebar. The child docs might themselves define a lower level of nesting.

IN this system, next-back links appear automatically, and only progress through the current set of peers (as I recall).

[Rumyra]

So I've been thinking about this - I am 100% on board with finding a good way to order pages. Tutorials/learn and listing api pages specifically.

One thing I consider a lot is I can't find a good solution that isn't fragile. Listing sub pages, macros, weighting - they all require knowledge of the pages and the order and with contributions would this get broken easily?

However I agree with @wbamberg weighting is one of the simplest approaches and I prefer it to other suggestions, I just worry that I personally assume weight backwards (100 is heavy and important, whereas 0 is light and not important) whereas it's the other way around in static sites (I'll get used to it) - another concern is that authors would get into a z-index state, where the numbers would become very large or very small just to try and 'hack' the system.

I go back to @teoli2003 's ideas to restrict it to certain page types - that would help mitigate some of the concerns I have I think 👍

[hamishwillee]

PS You might have somewhere already considered and stated how this fits in with all the other complicated sidebar story. If so, sorry! The reason I commented this yesterday is that I do think that this is an important topic and I don't want it to sit here un-progressed. If weighting can make things better I'm all for it.

[wbamberg]

Thank you for the clarification! I totally agree that what we have at the moment for sidebars is terribly over-complicated, and I do think it is worth thinking about different sidebar options and not necessarily being locked into our current system.

I think many simplifications can be made in the current IA and in the current sidebar architecture. I've been chipping away at these on and off, but there are lots still on the table. (For example, I don't understand why we have to have translations of page titles in sidebars like Learn, rather than getting the translated title from the page.) Weight is pretty much in that category. So, probably, is auto-assigning a sidebar, so writers don't have to call the macro explicitly.

But other simplifications are hard to do in the context of our current IA, especially wrt Web/API.

By "monolithic sidebars" I mean "explicit sidebar definitions that cover the whole sidebar definition" - what we have now for learn.

OK, so with learn literally every page in the sidebar is explicitly listed. We could do this for everything, and that would avoid the need for any tag (or page type)-based systems, or weight, or anything like that. It's very simple, and there is only one way to do it.

But there's a common desire in our docs to say something like "list all the pages under this node, in alphabetical order". Like: list all the CSS properties, or all the Web/API interfaces, or all the methods of a class. If we don't support this, then writers have to update the sidebar whenever one of these things is added, and manually ensure that it maintains alpha listing. It seems like this would get pretty clunky.

If we do want to support "auto-list all the pages under this node", though, then either our directory hierarchy needs to map onto our sidebar (which it doesn't at the moment) or we need something like filtering by tag (or page type) as well. So some of the complexity you've listed turns out to be needed.

Suppose we say: OK then, we won't support this feature. We'll make writers list every page, including lists that are really just alphabetical lists of subpages. We could imagine each sidebar definition as a JSON file listing the pages that the sidebar needs to list, with appropriate nestings.

For many sidebars, like CSS or HTML or Learn, we'd have just one JSON sidebar definition for each area. For JavaScript, we'd have maybe 70 different sidebar definitions, one for the main sidebar and one for each "global object" sidebar. For Web/API, we'd have about 1100 different sidebar definitions. I don't think this is maintainable, or obviously better than what we have now.

Basically, the "depends on a data definition" aspect of the Web/API sidebars flows from the IA for Web/API. So getting rid of it means reforming the IA, and this is hard - see openwebdocs/project#76 for some more or less stalled discussion of this.

I have thought before that we could get somewhat simpler sidebars with a system that auto-assigns sidebars to pages, and in which the sidebar definition is basically a nested list of explicitly named pages, but with a couple of extra bits to implement "get me all the pages under this node, optionally filtered by page type". But this is stymied, again, by Web/API.

You can do all of that in any kind of sidebar if you can parse your sidebar structure - it does not depend on using weight. In fact this kind of thing is often better with an explicit sidebar because you have the context to also do up and next links across sections.

That depends on a given set of weighted pages only appearing in a single sidebar, otherwise you have 2 or more copies to keep in sync, again, and you have the question of which one is authoritative if you need to use it to build a list of subpages. Currently we can't make this assumption - Learn pages appear in both the Learn sidebar and the domain sidebar.

Arguably we should not be doing this, but again, this is an IA issue.

[wbamberg]

I just don't want it to be layered over all that stuff ^^^ (i.e. yet one more rule to know) if it can be avoided.

Well it is an extra thing to implement, and to know, and to do. But it enables us to stop doing various other things, which I've outlined above 🤷 .

[wbamberg]

You can do all of that in any kind of sidebar if you can parse your sidebar structure - it does not depend on using weight. In fact this kind of thing is often better with an explicit sidebar because you have the context to also do up and next links across sections.

Actually I like this idea better than weight, but it does depend on sorting out the Learn situation, and possibly other places that have the same problem (I can't think of any other offhand).

[hamishwillee]

@wbamberg Wish I could over useful advice and not just whinge-lists and pointers to how others "do sidebars".
I'm just a lot concerned that if we go down the path of weighting and it proves "sub-optimal" it will be impossible to undo. I'd be more confident if we had a final picture in our head of how this will work before we go down that path (sounds like you do, but I do not).

I don't understand why we have to have translations of page titles in sidebars like Learn, rather than getting the translated title from the page.

Yes, makes no sense to me either. The title or translated title is explicitly in the context of the page. Worth fixing.

Weight is pretty much in that category.

Respectfully disagree. The position of a page within a hierarchy is in the context of the hierarchy. That's not the same as the title, which belongs to the page.

Sphinx toolchain makes this explicit by saying that the children of a page are a property of the page. The children can be listed explicitly or globbed. I like that approach though it probably doesn't suit all cases MDN has to support.

I would like it if we could more closely match docs hierarchy to file structure. I do appreciate we present things in different ways depending on context. Perhaps that is the problem - it is always easier to design a sidebar if you have the rule "one topic can only appear in one sidebar".