yari icon indicating copy to clipboard operation
yari copied to clipboard
verified publisher icon mdn

(experiment) Implement secure context banners in Yari

Open wbamberg opened this issue 3 years ago • 4 comments

Summary

An experiment to see how we might implement banners using front matter and Yari, instead of KumaScript.

Problem

Currently we have a lot of banners on MDN for various things:

  • deprecated
  • experimental
  • needs secure context
  • needs permissions
  • available in workers
  • ...

Currently these are implemented by authors adding macros to pages. We have thought for a while that it might be better for authors and the platform if we can represent things like this as just data, for instance in the page front matter, and have Yari auto-add banners based on the data. This would also give Yari more flexibility to figure out other ways of displaying these facts (like a single status bar for example, or a border down the page).

See also https://github.com/openwebdocs/project/issues/81 (I've used a different feature here, but it would work for experimental as well of course).

Solution

This adds a new module to the page builder, "inject-banners", which has a single export, which is given:

  • the Cheerio object
  • the value of CONTENT_ROOT
  • the locale of the page being built
  • the page metadata

It:

  1. loads localized strings from the existing /jsondata/L10nCommon.json file . It does some stuff lightly stolen from https://github.com/mdn/yari/blob/main/content/popularities.ts to try to cache the strings, so we're not reading the file every time. But this is probably broken, tbh I don't really know what I am doing there.
  2. looks at the page metadata to decide which banners to insert, and uses the strings out of L10nCommon.json for the content

At the moment it adds:

  • the "secure context required" banner, which uses the metadata structure described by @teoli2003 in https://github.com/mdn/content/pull/20435#issuecomment-1241782925.
  • the "experimental" and "deprecated" banners, powered by BCD

To see it working you can check out the corresponding branch https://github.com/wbamberg/content/tree/yari-banners , which:

  • adds the en-US strings to L10nCommon.json
  • updates https://developer.mozilla.org/en-US/docs/web/api/storagemanager with the new secure-context metadata (https://github.com/mdn/content/compare/main...wbamberg:content:yari-banners)
  • updates https://developer.mozilla.org/en-US/docs/Web/CSS/clip and https://developer.mozilla.org/en-US/docs/Web/CSS/element to remove their banner macros

At the moment I'd love to know if this seems like a good thing to do, and if so what it would take to get this into Yari.

Screenshots

Before

Screen Shot 2022-09-24 at 4 02 19 PM Screen Shot 2022-09-25 at 9 49 41 AM Screen Shot 2022-09-25 at 9 50 01 AM

After

Screen Shot 2022-09-24 at 4 05 22 PM Screen Shot 2022-09-25 at 9 49 31 AM Screen Shot 2022-09-25 at 9 49 50 AM

(I updated the wording of some of these, partly to see the difference and partly because the existing wording isn't very good.)

How did you test this change?

Visited: http://localhost:3000/en-US/docs/Web/API/StorageManager http://localhost:3000/en-US/docs/Web/CSS/element http://localhost:3000/en-US/docs/Web/CSS/clip

wbamberg avatar Sep 24 '22 23:09 wbamberg

A handful of pages use an array of BCD queries in the browser-compat field.

Click to see all pages that use an array of BCD queries https://developer.mozilla.org/en-us/docs/mozilla/add-ons/webextensions/interact_with_the_clipboard
https://developer.mozilla.org/en-us/docs/mozilla/add-ons/webextensions/user_interface/browser_styles
https://developer.mozilla.org/en-us/docs/web/api/channel_messaging_api
https://developer.mozilla.org/en-us/docs/web/api/channel_messaging_api/using_channel_messaging
https://developer.mozilla.org/en-us/docs/web/api/clipboard_api
https://developer.mozilla.org/en-us/docs/web/api/css_typed_om_api
https://developer.mozilla.org/en-us/docs/web/api/device_memory_api
https://developer.mozilla.org/en-us/docs/web/api/device_orientation_events/detecting_device_orientation
https://developer.mozilla.org/en-us/docs/web/api/device_orientation_events
https://developer.mozilla.org/en-us/docs/web/api/dommatrix
https://developer.mozilla.org/en-us/docs/web/api/ecdsaparams
https://developer.mozilla.org/en-us/docs/web/api/encoding_api
https://developer.mozilla.org/en-us/docs/web/api/file_system_access_api
https://developer.mozilla.org/en-us/docs/web/api/fullscreen_api/guide
https://developer.mozilla.org/en-us/docs/web/api/fullscreen_api
https://developer.mozilla.org/en-us/docs/web/api/geometry_interfaces
https://developer.mozilla.org/en-us/docs/web/api/keyboard_api
https://developer.mozilla.org/en-us/docs/web/api/long_tasks_api
https://developer.mozilla.org/en-us/docs/web/api/navigation_timing_api
https://developer.mozilla.org/en-us/docs/web/api/network_information_api
https://developer.mozilla.org/en-us/docs/web/api/push_api
https://developer.mozilla.org/en-us/docs/web/api/storage_access_api
https://developer.mozilla.org/en-us/docs/web/api/streams_api
https://developer.mozilla.org/en-us/docs/web/api/web_authentication_api
https://developer.mozilla.org/en-us/docs/web/api/web_locks_api
https://developer.mozilla.org/en-us/docs/web/api/web_share_api
https://developer.mozilla.org/en-us/docs/web/api/web_speech_api
https://developer.mozilla.org/en-us/docs/web/api/web_speech_api/using_the_web_speech_api
https://developer.mozilla.org/en-us/docs/web/api/web_storage_api
https://developer.mozilla.org/en-us/docs/web/api/web_storage_api/using_the_web_storage_api
https://developer.mozilla.org/en-us/docs/web/api/webgl_api
https://developer.mozilla.org/en-us/docs/web/api/webglrenderingcontext/compressedteximage2d
https://developer.mozilla.org/en-us/docs/web/api/webglrenderingcontext/texparameter
https://developer.mozilla.org/en-us/docs/web/api/webvtt_api
https://developer.mozilla.org/en-us/docs/web/css/_doublecolon_-webkit-scrollbar
https://developer.mozilla.org/en-us/docs/web/css/color_value/rgba https://developer.mozilla.org/en-us/docs/web/css/compositing_and_blending
https://developer.mozilla.org/en-us/docs/web/css/css_conditional_rules
https://developer.mozilla.org/en-us/docs/web/css/css_containment
https://developer.mozilla.org/en-us/docs/web/css/css_counter_styles
https://developer.mozilla.org/en-us/docs/web/css/css_scrollbars
https://developer.mozilla.org/en-us/docs/web/css/display-inside
https://developer.mozilla.org/en-us/docs/web/css/display-internal
https://developer.mozilla.org/en-us/docs/web/css/display-legacy
https://developer.mozilla.org/en-us/docs/web/css/filter_effects
https://developer.mozilla.org/en-us/docs/web/css/fit-content_function
https://developer.mozilla.org/en-us/docs/web/css/layout_cookbook/card
https://developer.mozilla.org/en-us/docs/web/css/layout_cookbook/center_an_element
https://developer.mozilla.org/en-us/docs/web/css/layout_cookbook/column_layouts
https://developer.mozilla.org/en-us/docs/web/css/layout_cookbook/list_group_with_badges
https://developer.mozilla.org/en-us/docs/web/css/layout_cookbook/media_objects
https://developer.mozilla.org/en-us/docs/web/css/layout_cookbook/pagination
https://developer.mozilla.org/en-us/docs/web/css/layout_cookbook/sticky_footers
https://developer.mozilla.org/en-us/docs/web/guide/woff
https://developer.mozilla.org/en-us/docs/web/html/attributes/crossorigin
https://developer.mozilla.org/en-us/docs/web/html/attributes/disabled
https://developer.mozilla.org/en-us/docs/web/html/attributes/for
https://developer.mozilla.org/en-us/docs/web/html/attributes/max
https://developer.mozilla.org/en-us/docs/web/html/attributes/maxlength
https://developer.mozilla.org/en-us/docs/web/html/attributes/min
https://developer.mozilla.org/en-us/docs/web/html/attributes/minlength
https://developer.mozilla.org/en-us/docs/web/html/attributes/readonly
https://developer.mozilla.org/en-us/docs/web/html/attributes/rel
https://developer.mozilla.org/en-us/docs/web/javascript/guide/modules
https://developer.mozilla.org/en-us/docs/web/security/subresource_integrity
https://developer.mozilla.org/en-us/docs/web/web_components

In these cases I have just omitted any BCD-derived banners, because it seems to me that it's not possible to get a good answer to questions about status.

But I do think this is a problem. I would be happy to try to stop allowing BCD to be an array. I think in a lot of these cases we could just link to the underlying reference pages for BCD. One tricky case is API overview pages, which is part of an issue we've never resolved: https://github.com/mdn/content/discussions/4920.

Basically, if:

  • an API is deprecated
  • and it has no entry in BCD
  • and we use BCD to represent deprecation status ...then how can we show it is deprecated?

wbamberg avatar Sep 25 '22 18:09 wbamberg

Actually a better way to implement "secure context" banners would be to read the SecureContext extended attribute out of the IDL using webref.

But the trick seems to be mapping from a page to a spec shortname, which we can use to look up the IDL. We ought to be able to use BCD for this, since BCD includes spec_url. But we are stymied by spec_url sometimes being an array. If it's an array, which one do we use to look up the IDL?

Alternatively we could keep spec shortname in the front matter, which is easy, quick and reliable. But then we are duplicating spec information of course.

wbamberg avatar Oct 01 '22 04:10 wbamberg

I like it. That's a great general direction.

  • Can / should we get the "secure context" information from BCD?
  • The experimental flag should also be in BCD.
  • WebWorker availability might have to come from webref but maybe we should expose this to BCD somehow?

Getting the data is one thing. But maybe we should also think about how to display this information. Maybe banners are fine for now but I'd love to have this a bit more compact. Banners can pile up (see Barcode Detection API).

fiji-flo avatar Oct 05 '22 14:10 fiji-flo

I like it. That's a great general direction.

  • Can / should we get the "secure context" information from BCD?

I just started a thread to help figure out where to keep metadata. Personally I don't think we should use BCD for this but we'll see. Also though, as I said in https://github.com/mdn/yari/pull/7227#issuecomment-1264230886 we can in theory use webref/idl to get secure_context, but there are some issues to work through.

  • The experimental flag should also be in BCD.

Not sure I understand, this PR uses BCD to get experimental? But again, there are issues with pages that have an array of BCD queries.

  • WebWorker availability might have to come from webref but maybe we should expose this to BCD somehow?

Getting the data is one thing. But maybe we should also think about how to display this information. Maybe banners are fine for now but I'd love to have this a bit more compact. Banners can pile up (see Barcode Detection API).

For sure, but I thought we could do this in stages. First step would be the plumbing to be able to generate banners automatically, and then we can attack rendering separately.

wbamberg avatar Oct 05 '22 18:10 wbamberg

@wbamberg I'll be on leave from 26/12 to 27/01. Let me know if you want to land this before. 🙂

caugner avatar Dec 13 '22 17:12 caugner

This pull request has merge conflicts that must be resolved before it can be merged.

github-actions[bot] avatar Feb 08 '23 12:02 github-actions[bot]

This pull request has merge conflicts that must be resolved before it can be merged.

github-actions[bot] avatar Mar 13 '23 17:03 github-actions[bot]