mdn / kumascript

Bringing scripting to the wiki bears.

MDN Web Docs on Github

👋 Welcome, Bienvenida, 欢迎, Bienvenue, いらっしゃいませ, Receber, Добро пожаловать, 환영합니다, მოგესალმებით

Welcome to the mdn repository which we use to track MDN team work. The MDN teams public projects are here, where you can view current and upcoming tasks.

This repository is also used for requests and contains issue templates for the following processes:

• Proposing new content or features for MDN Web Docs
• Nominating an invited expert
• Nominating a co-maintainer

Invited experts

Joshua Chen

• GitHub
• Invited expert: JavaScript

Hidde de Vries

• GitHub
• Invited expert: Accessibility

Scott O'Hara

• GitHub
• Invited expert: Accessibility

André Jaenisch

• GitHub
• Invited expert: SVG

Mendy Berger

• GitHub
• Invited expert: WASM

NOTE: If you wish to nominate someone to be considered as an invited expert, start by filing an issue in this repository.

kumascript's Issues

{{AddonSidebar}} Update outdated Themes Section

It was decided to remove all sub-menus for Themes and just leave Themes as it is.

csssyntax errors

Some CSS pages are getting errors from the {{csssyntax}} macro. Not all of them, but at least:

https://developer.mozilla.org/en-US/docs/Web/CSS/attr
https://developer.mozilla.org/en-US/docs/Web/CSS/calc
https://developer.mozilla.org/en-US/docs/Web/CSS/minmax

I haven't tried refreshing every page yet though, so there are probably more.

Bug 1419434: Learning Area sidebar links do not match titles for Client-side web APIs

"Manipulating Docs" links to "Introduction", etc. See bug 1419434:

kumascript/macros/LearnSidebar.ejs

Lines 857 to 867 in 3ce8dfe

	<li data-default-state="<%=currentPageIsUnder('JavaScript/Client-side_web_APIs')%>"><a href="<%=baseURL%>JavaScript/Client-side_web_APIs"><%=text['Client-side_web_APIs']%></a>
	<ol>
	<li><a href="<%=baseURL%>JavaScript/Client-side_web_APIs"><%=text['Client-side_web_APIs_Introduction']%></a></li>
	<li><a href="<%=baseURL%>JavaScript/Client-side_web_APIs/Introduction"><%=text['Client-side_web_APIs_Manipulating_documents']%></a></li>
	<li><a href="<%=baseURL%>JavaScript/Client-side_web_APIs/Manipulating_documents"><%=text['Client-side_web_APIs_Fetching_data']%></a></li>
	<li><a href="<%=baseURL%>JavaScript/Client-side_web_APIs/Fetching_data"><%=text['Client-side_web_APIs_Third_party_APIs']%></a></li>
	<li><a href="<%=baseURL%>JavaScript/Client-side_web_APIs/Third_party_APIs"><%=text['Client-side_web_APIs_Drawing_graphics']%></a></li>
	<li><a href="<%=baseURL%>JavaScript/Client-side_web_APIs/Drawing_graphics"><%=text['Working_with_JSON_data']%></a></li>
	<li><a href="<%=baseURL%>JavaScript/Client-side_web_APIs/Video_and_audio_APIs"><%=text['Client-side_web_APIs_Video_and_audio_APIs']%></a></li>
	</ol>
	</li>

Update kumascript for compatibility with recent node.js versions

Kumascript was deployed on node v0.6.12, and nothing has been done to stay current since. This should be addressed.

{{APIListAlpha}} misses some subpages such as Fetch API because of space in title

Fetch API page is not included in API list.

In

kumascript/macros/APIListAlpha.ejs

Line 54 in 995a010

// It's not an interface, so return null.

The logic basically says, if the title has space and after space it's not (, it's not an interface, so shouldn't be included in the API list.

But Fetch API is apparently an interface, according to that very page:

The Fetch API provides an interface for fetching resources ...

Runtime configuration management

Currently, the configuration for Kumascript as deployed in Kuma happens in a kumascript_settings_local.json file that is editable only by IT. This works fine for settings that are infrastructure related (ie. the IP to a memcache server), but not so much for tuning settings (ie. the timeout duration before terminating a hung worker process).

On the Kuma side of things, we have django-constance that lets us alter some runtime settings for the site that does not require attention from IT folks. It would be nice if KumaScript had some settings that could be altered in this way.

Encrypted Media Extensions API is referred to by different keywords in different places

In GroupData.json, it's "Encrypted Media Extensions".

In SpecName.ejs, it's "EME".

This should be addressed; having them different invites confusion and chaos. Dogs and cats living together!

Finish InterfaceOverview macro

This macro is intended to be used to automatically generate all the lists of methods, properties, etc on API interfaces. It's already used on pages such as RTCPeerConnection, where it works quite well.

That said, there are improvements that could be made. I propose that in addition to what it currently does, it be updated to automatically add properties, methods, etc from mixins and parent interfaces directly into the list, rather than simply saying "Also inherits from..." with a link.

It should also be updated to use BCD's list of interface properties, methods, and so forth rather than walking the wiki, so that not-yet-documented items still get listed.

Consider writing a custom file transport for Winston to do more conventional log rotation

This is the current out-of-box file transport. It does some odd things for log rotation. Namely, it starts on kumascript.log, and when that file reaches max size it moves on to kumascript1.log, then kumascript2.log, etc.

This is the reverse of usual expectations of log rotation - that is, kumascript.log should always be the current log. When it fills up, move it to kumascript1.log, bump the rest down in the sequence, and let the last one fall off & be deleted.

Another alternative might be to rename the files with a datestamp of rotation, possibly with a {year}/{month}/{day} directory scheme?

And as another footnote, maybe we should have an errorrmill transport.

Several spec URLs are outdated

Pretty much all the obsoleted W3C DOM spec links in https://github.com/mdn/kumascript/blob/master/macros/SpecName.ejs now 404 when requested.

Example: https://developer.mozilla.org/en-US/docs/Web/API/NodeFilter#Specification links to https://www.w3.org/TR/DOM-Level-2-Traversal-Range/traversal.html#Traversal-NodeFilter through {{SpecName('DOM2 Traversal_Range', 'traversal.html#Traversal-NodeFilter', 'NodeFilter')}}, which is now known as https://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113/traversal.html#Traversal-NodeFilter.

Compat table macros should order subfeatures

The current aggregated compat tables order the features they contain:
https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/webRequest#Browser_compatibility

But subfeatures are not ordered:
https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/permissions#Browser_compatibility

The reason for this was a vague idea that subfeatures follow some kind of progression, as browsers add support for the feature, from more basic to more advanced. For some features this is probably true, but for some it isn't. For the sake of consistency, it would probably be better to always order subfeatures.

Make {{Firefox_for_developers}} macro smarter

The {{Firefox_for_developers}} macro currently simply lists all versions of Firefox up to a maximal version given as constant in that macro.

To avoid having to maintain that constant manually, the macro should base the display of the version links on the Firefox release dates.

The release dates are currently maintained in the {{CompatGeckoDesktop}} macro.

The idea is to extract the release data from that macro into a new {{firefoxReleaseDates}} macro (or store the data somewhere outside of the mozilla/kumascript, or even read it directly from the release calendar) and change the {{Firefox_for_developers}} macro to read the data from that source.
Based on that data, the macro would display the release links up to the newest Firefox Nightly. The currently displayed release page may be displayed differently, e.g. as plain text instead of a link or somehow highlighted.

Sebastian

New compat flag type "runtime_flag"

See mdn/browser-compat-data#615.

When we write a note for flags, we need news texts for runtime flags.
https://github.com/mdn/kumascript/blob/master/macros/Compat.ejs#L188
https://github.com/mdn/kumascript/blob/master/macros/CompatBeta.ejs#L254

{{LegacyAddonsNotice}} should mention mobile

Given that we are not turning off legacy add-ons on Fennec 57, we should make it clear in the {{LegacyAddonsNotice}}.

Consolidate KumaScript macros that generate a stylized URI to cross reference docs.

This is a continuation of a discussion that began on Bugzilla Bug 1324310.

The backstory of this proposal. One day in December, I got Wiki account set up with page creation. I was editing some pages, and looking at some old API things and saw a big red error banner warning about a KumaScript macro, and a lot of funny looking {{ AMInterface }} showing up on live page. The macro was removed at some point, though a dozen or so pages (with deprecated APIs to be obsoleted by end of 2017) were using it. During the process of bug reporting, I learned more about the KumaScript project, and discovered many macros doing nearly the same thing.

These macros invariably are following a pattern such as this:

1. Unique Macro Name

   • AMInterface
   • jsxref
   • Interface
   • manch

2. Same base URI (usually just language at root level)

   • /<lang>/

3. Unique paths to base of API docs

   Although APIs are a specific use case, the technique may be used on other reference documentation with different styling and/or structure.

   • Path/to/SomeAPI

4. Essentially the same structure of URI generated from 1 or 2 parameters.

   • First parameter is the API Object e.g.
     <code><a href="/en-US/Path/to/SomeAPI/APIObject" title="APIObject">APIObject</a></code>

   • Second, Optional parameter is a method on an API Object
     <code><a href="/en-US/Path/to/SomeAPI/APIObject#method()" title="APIObject.method()">method()</a></code>

5. Some often shared, sometimes unique stylings

   • This structure of paths, anchored links, titles, link text, and surrounding tags (such as <code>, above), may vary by document type in which it is used. I generally refer to that as "styling".
   • Also note, that these rules could be refined to allow for variation based on usage context. I.e. always wrapping <code> around a link may be unnecessary if the link is already in a <code> block. <code>abcd<code><a href>link</a></code>efgh</code> might be inefficient or problematic. A way to toggle specific styling options might be considered for a feature.

What the proposal intends to do, is explore the possibility of combining these similar macros into a single, generic, macro that can handle a wider rage of situations. Of specific concern is to create a macro that contains a lot of power, is easy to use, easy to extend, yet is efficient, so as not to bog down server. We also need a suitably generic yet concise and accurate name for the macro.

Looking at the pattern above, we can separate unique items from common items.

1. A unique macro name corresponds to a unique base path fragment, usually one to one.
2. A unique macro name often corresponds to the same structure and style, but in some cases differs.
3. The macros typically take 2 options, 1st required object name, 2nd optional method name, or in the case of non-API docs, 1st is a document page and 2nd is a heading to scroll down to.

What this tells us is that we are storing data in the macro name itself, thus the code duplication.

A proposed remedy is to move that macro name to the 1st parameter, which we then use to do a hash table lookup to get the path. Perhaps we store references to styling functions in hash as well, and refer to the same styling multiple times, and as needed, create new functions. Or else we use the "name" parameter inside a switch to achieve the same affect, and collapse multiple names to the same styling by stacking up cases. These are implementation details, and should be driven by not just by ease of initial implementation, but ultimately by code performance, readability, maintainability, etc.

A side note on ordered function parameters. I'm not yet familiar with the capabilities of Kuma/KumaScript, but I dislike ordered parameters because of the complexity of handling multiple optional parameters. Passing a hash table (Object) as a parameter would be nice.

(In reply to Leif-AMO from comment #14)

Regarding a generic "ToolkitInterface" macro

/*
The backstory (in case you're wondering "why is it like this?"): until a couple of months ago, all KumaScript macros were stored somewhere in Kuma's database and were edited as Wiki pages, that just lived in a completely flat hierarchy, like this: https://developer.mozilla.org/en-US/docs/Template:WebExtBrowserCompat, https://developer.mozilla.org/en-US/docs/Template:jsxref, etc. Editing them meant editing the macro's page, and saving it published it live into production. We didn't have any defined review process or any tests, and since it was hard to reason about the macros we had, there was a lot of code duplication.

In November we moved them into the GitHub repo, and this opens up possibilities about managing them better, including dealing with the code duplication issue. We're excited about getting into this work. But it's still a big task with a lot of legacy use.
*/

Intuitively assumed this was more or less the case. It's source code, better managed in a source code version control system. I only wish the Wiki pages themselves could have gone in somehow. I'd be able to clone the site, use search and replace, and perhaps even (with some help) come up with a way to test the correctness of generated URIs. What takes hours, days, weeks or months for one person to do (in spare time), could be reduced to a single afternoon. Maybe in a future evolution of the site, and assuredly in a separate proposal. For now, we'll work on this area of KumaScripts.

One thing to say about the proposal is that there are a lot of technology areas on MDN. They broadly fall into one of two categories:

• docs for Mozilla internal technologies: things that are useful if you are a Mozilla developer (or an old-school add-on developer, since old-school add-ons get access to a similar set of nonstandard JS APIs). That includes AddonManager and other JSMs (https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules), as well as XPCOM (https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM).

• "open web" docs: standards-based browser-agnostic reference, like JavaScript or CSS or WebExtensions.

I remember when the entirety of documentation I needed was access via a <200kb file named jsref.zip. :-)

The MDN team is much more focused on the open web docs than on the Mozilla internal docs.

Understood an appropriate. My interest here is to learn more about the system than the content and explore ideas to test on old docs on their way out (or at least to archival status), in hopes of applying those ideas to newer areas, if appropriate.

So one question is, is the proposal intended to cover xref macros used in the open web docs (I think it should!). If so, then "ToolkitReference" is probably not a good name. Kris's comment 11 is I think only about Mozilla's internal APIs. But in the context of the open web docs, then "Toolkit" doesn't really mean anything.

A name is the easiest thing to change at this stage. For lack of any better idea (or environmental awareness) at the moment, I used the same name, to have a handle with which to demonstrate concepts. Not attached to the name. A shorter, more general name would be great. Consider determining a suitable name as part of proposal requirement before widespread implementation. ;-)

I guess the general approach here could be:

1. write a new xref macro that can replace all the existing ones
2. update the old xref macros to call the new one
3. update the actual pages to call the new macro
4. delete the old xref macros

(3) in particular seems like a huge task, but one nice thing is that you'd get a lot of benefits by just doing (1) and (2), and you could do (3) gradually.

Regarding steps above:
0) "xref" seems like a good short name, "cross-reference", which is essentially what this macro lives to do.

1. Implement idea, the benefit is to have some working code instead of nifty ideas floating around.
2. Gets us some centralized code, and sanity.
3. 95% of the innovation is done, 95% of the grunt work begins. But which pages?
4. This is where I really wish there was an easy way to lookup "Which Wiki Pages (including all translations) use the macros: [ list, of, foo, macros, here ], and how many instances each per page?" This would be the basis for making a case to have the Wiki docs in a source control, or perhaps sufficient quality of info could be achieved in another macro to crawl site or analyze database or something. Not familiar with the rest of Kuma.

I think the best place to discuss this proposal, though, is not this bug, but as a separate issue in the kumascript repo: https://github.com/mozilla/kumascript/issues. Would you mind filing an issue there, with your proposal?

And here we are.

{{APIRef('XMLHttpRequest')}} misses almost all the methods but two

https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest

Check the sidebar: only abort() and getResponseHeader() shows up.

But apparently XMLHttpRequest has more:

I checked the kuma macros of APIRef quickly but don't know why.

If it's not a technical issue please let me know, will report to bugzilla instead.

{{EmbedLiveSample}} should offer a link to open the demo in it's own tab/window

For example, deviceorientation events are blocked in iframes. I added a warning below the demo here but to make the demo more useful we should offer a link to open the demo in it's own tab/window.

some EmbedLiveSample not work on localized page

This page has two EmbedLiveSample, but on the localized page they are not shown. When I changed the name of EmbedLiveSample to 'Examples' only returned the second, it was very strange.
And I did some testing.

× en-US/docs/Web/CSS/:first-of-type$samples/Example
√ en-US/docs/Web/CSS/:first-of-type$samples/Examples (return the second LiveSample)
√ en-US/docs/Web/CSS/:first-of-type$samples/Example_1_Simple_first_paragraph

√ zh-CN/docs/Web/CSS/:first-of-type$samples/Example (return the second LiveSample)
× zh-CN/docs/Web/CSS/:first-of-type$samples/Examples
× zh_CN/docs/Web/CSS/:first-of-type$samples/Example_1_Simple_first_paragraph

Add an .editorconfig file

It'd be nice if there was an .editorconfig file so users didn't have to think about tabs vs spaces.

Mozilla webdev has published standards for javascript.

But it's also possible to just copy the one from kuma or bedrock.

Support longer JS interactive examples

Currently, with the JS editor, if an example has more than 12 lines, the editor overflows and gets a scrollbar. 12 lines is a good maximum for most cases, but sometimes we really want to go over 12 lines. In these cases, it would be better to make the editor bigger, to avoid scrollbars.

We could support this by letting the EmbedInteractiveExample macro take a parameter asking for more space, and passing it on pages which need it.

Add support for listing by category to ListGroups macro; add options to include descriptions

Currently, ListGroups takes no parameters and outputs an alphabetized list of all APIs given their names pulled from the GroupData.json file. This is a good start!

Once issue #286 is implemented (adding a "category" to GroupData.json), we need to go a step farther. Allow ListGroups to accept as input parameters that tell it to either output the list sorted by category then alphabetically or alphabetically but including only items within a certain category or list of categories.

The syntax could be:

{{ListGroups([sortSpec][, describeCategories[, describeAPIs]])

Where if sortspec is missing, it's a complete list alphabetically of all APIs. If it's a single string, then the result is a list of APIs which match the specified category. We could also use an array to allow listing APIs that are a member of any one of the specified categories.

Listing by category would let us create really nicely nuanced menus listing the categories and the assorted APIs which are members of those categories. Listing for just a single category would then let us create nice API landing pages for a given category, too, so you could go to a page like "The multimedia APIs" and get a little overview and a list of the APIs within.

The describeCategories option would be a boolean which would add under the heading for each category a description of the category. Similarly, describeAPIs would turn the current simple, multi-column lists into a two-column-max list with summaries, in the ListSubpagesWithSummaries style, to match our landing page menu style.

Suggestion: Add a "category" field to GroupData.json

Let's add a "category" field to GroupData.json. This would let us assign each API to a category (Media, Storage, DOM, UX, etc.). It would then be trivial to produce an always-up-to-date page on MDN that lists all APIs grouped by category, so people interested in A/V and media stuff could get right to a list of those APIs.

This would also help us more easily create landing pages for individual technology areas. Imagine a page "Introducing the media APIs" that briefly talks about each API but then includes a generated list of them all below with links to appropriate documentation for each (say, the overview pages and tutorials for each).

We could also then do a categorized list of interfaces, instead of a purely alphabetical list of them like the one on the Web/API page right now (although still maybe in a new location, with a better landing page there).

I expect there are other valuable use cases here. The hardest part would be deciding on a set of categories to use, and even that isn't that hard to do.

CSSRef causes an error for localized pages without any category

There are currently pages with macro errors in the CSS section when those don't belong to any CSSData "category". (ex. https://developer.mozilla.org/fr/docs/Web/CSS/Valeur_calcul%C3%A9e )
This seems to be due to:

kumascript/macros/CSSRef.ejs

Line 180 in 41d0c3e

groupPages = groupPages.concat(page.subpagesExpand('/en-US/docs/Web/CSS/' + group[i].replace(/ /g, '_')));

where the localized slug is combined with /en-US/... prefix which causes the subpagesExpand method to throw.
I'll propose a simple WIP PR for that.

Compat.ejs makes an invalid assumption about compat data structure

Compat.ejs, in traverseFeatures, assumes that if a feature has a __compat object, then any feature underneath that feature also has a __compat object.

This isn't necessarily true, and the assumption causes a couple of aggregate tables to break:

• runtime, because onInstalled has __compat, but onInstalled.details does not.

• tabs, because connect has __compat, but connectInfo does not.

{{CompatEdge}}: version reporting inconsistent with MS feature changelog conventions

Unlike the approach this template uses, Microsoft usually uses five-digit build numbers instead of a more marketable build number when it comes to writing changelogs and reporting features. These monotonic build numbers establish a one-to-one mapping from/to an EdgeHTML version, an Edge version, and (for now) an associated Windows release.

Switching to the build number is more or less more useful to developers who actually use cutting-edge versions of Edge as it unifies the two version numbers and is closer to Microsoft-speak.

Unable to checkout some files to filesystem on Windows

They use a colon, Microsoft Windows does not support such a file name.

>git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        deleted:    macros/DekiScript:Date.ejs
        deleted:    macros/DekiScript:Page.ejs
        deleted:    macros/DekiScript:String.ejs
        deleted:    macros/DekiScript:Uri.ejs
        deleted:    macros/DekiScript:Web.ejs
        deleted:    macros/DekiScript:Wiki.ejs
        deleted:    macros/HTML:Element_Navigation.ejs
        deleted:    macros/InterfaceStatus:EXPERIMENTAL.ejs
        deleted:    macros/InterfaceStatus:FROZEN.ejs
        deleted:    macros/InterfaceStatus:FROZEN:DisplayName.ejs
        deleted:    macros/InterfaceStatus:Scriptable_no.ejs
        deleted:    macros/InterfaceStatus:Scriptable_yes.ejs
        deleted:    macros/InterfaceStatus:UNDER_REVIEW.ejs
        deleted:    macros/InterfaceStatus:unfrozen.ejs
        deleted:    macros/InterfaceStatus:unfrozen:DisplayName.ejs
        deleted:    macros/L10n:CSS.css
        deleted:    macros/L10n:Common.json
        deleted:    macros/L10n:CompatTable.json
        deleted:    macros/L10n:HTML.json
        deleted:    macros/L10n:JavaScript.json
        deleted:    macros/L10n:SVG.json
        deleted:    macros/MDN:Common.ejs
        deleted:    macros/RSS:Element_Navigation.ejs
        deleted:    macros/Storage:synchronous_io_warning.ejs
        deleted:    macros/Storage:threadsafety_callback_warning.ejs
        deleted:    macros/Storage:type_conversion_warning.ejs
        deleted:    macros/XUL:xul_element.ejs
        deleted:    macros/xul:box.ejs
        deleted:    macros/xul:hbox.ejs
        deleted:    macros/xul:vbox.ejs

Untracked files:
  (use "git add <file>..." to include in what will be committed)

        macros/L10n
        macros/MDN
        macros/RSS
        macros/Storage
        macros/XUL

no changes added to commit (use "git add" and/or "git commit -a")

{{EventRef}} macro has started throwing errors

For example see:

• https://developer.mozilla.org/en-US/docs/Web/Events/statechange_(cancellable_fetch)
• https://developer.mozilla.org/en-US/docs/Web/Events/responseprogress
• https://developer.mozilla.org/en-US/docs/Web/Events/requestprogress
• https://developer.mozilla.org/en-US/docs/Web/Events

The error is

    1 | <div>{{EventRef}}{{SeeCompatTable}}</div>
-------------^
    2 | 
    3 | <div>

TypeError: ejs:1
 >> 1| <%
    2| // Event Sidebar
    3| //
    4| 

Cannot read property 'indexOf' of undefined
    at eval (eval at compile (/data/www/developer.mozilla.org/kuma/kumascript/node_modules/ejs/lib/ejs.js:491:12), <anonymous>:44:22)
    at returnedFn (/data/www/developer.mozilla.org/kuma/kumascript/node_modules/ejs/lib/ejs.js:520:17)
    at /data/www/developer.mozilla.org/kuma/kumascript/lib/kumascript/templates.js:69:30

Modify SauceLabsPromo to handle localization

Currently the SauceLabsPromo macro cannot be localized easily. One could use the mdn.localString system which is used on other macros.

For example, the DevTools' landing page in French displays a pretty large block of English.

Add "Client-side web APIs" module to LearnSidebar macro

As you can see here, the Client-side web APIs module is under Learn -> Javascript -> Client-side web APIs. But currently the sidebar doesn't have it at all.

Khronos specs marked as REC/ED

WebGL and WebGL2 are marked respectively as REC and ED, whereas these statuses are supposed to be used only for W3C documents according to the status taxonomy, and both specs aren't W3C's, but Khronos'.

I'm happy to provide a pull request to fix this (with Standard/Draft), but wanted to check this hadn't been made on purpose.

CompatBeta: Add legend explaining icons and cell colors

The beta tables are missing the legend from the original design: http://stephaniehobson.github.io/browsercompat/5.0/#here

The easy version would be to always show all cell colors and icons, the better version would be to just have the legend show the icons/cell colors that are used on the table being shown.

{{InheritanceDiagram}}: Add a header and/or border to help identify them

Currently, our inheritance diagrams don't stand out well. They're not being used in an "Inheritance" section; instead, they're dropped in the intro text and left to do their own thing. There's nothing explaining what you're seeing or why it's there.

We should have the macro output a heading and/or draw a box around the diagram with a caption, to make it look like a figure.

Remove statsd usage from project

Kuma, the primary customer for this service, no longer uses statsd. Probably worth removing statsd from kumascript, possibly with some investigation into what might work better. (eg. New Relic?)

Compat macro should allow collapsing subfeatures with identical support

APIs implemented in the browser-compat-data repo require one subfeature per property and method, which in turn have their own pages with compatibility tables on MDN web docs. However, for interfaces with many properties and methods, this means the support table can become really long. Consider PointerEvent, for example:

Before: Basic support, tangentialPressure & twist, PointerEvent.getCoalescedEvents() (3 rows)
After: Basic support, PointerEvent() constructor, pointerId, width, height, pressure, tangentialPressure, tiltX, tiltY, twist, pointerType, isPrimary, getCoalescedEvents() (13 rows)

It is clear that most of these new rows are bloat, which should be assumed under "Basic support"; almost all of the properties come from the original level 1 specification. Specifically:

• Basic support and PointerEvent() constructor have identical data (IE10 is prefixed).
• pointerId, tiltX, tiltY and isPrimary have identical data (IE10 is supported).
• width, height, pressure and pointerType have near-identical data (IE10 has partial support).
• tangentialPressure and twist have identical data (new level 2 properties).
• Only getCoalescedEvents() is truly unique (experimental level 2 spec extension).

It would be great if the {Compat} macro could display this data as 5 rows instead of 13 by automatically collapsing rows that have identical support, excluding notes.

Add support for partial_implementation to Compat macro

The Compat macro is currently ignoring the partial_implementation information. See mdn/browser-compat-data#380 for an example were it is used.

I suggest to render cells indicating a partial implementation with a yellow background, and to replace Yes/No with Partial, and like 54 (Partial) if the version support was added is known.

{{InheritanceDiagram}}: Add a "use default" value for width, height, and offset parameters

Currently, when you specify 0 for any of these parameters, the value 0 is getting used. Instead, the default should get used. If 0 is valid for any of these (it probably is for offset), then make -1 mean "use default."

SpecName.ejs URL for WebUSB is 404 Not Found

Investigating #442 I found one URL that is truly "404 Not Found"

The entry for "Web USB" has:

    'Web USB':{
        name : 'WebUSB',
        url  : 'https://reillyeon.github.io/webusb/'
    },

That URL fails

• Fails 404: https://reillyeon.github.io/webusb/
• Works: https://wicg.github.io/webusb/

The header for the spec says:

WebUSB API
Editor’s Draft, 24 September 2017
    This version:
        https://wicg.github.io/webusb 

Note: The interior text mentions "Web Platform Incubator Community Group" and continues "It is not a W3C Standard nor is it on the W3C Standards Track."

Add survey link and remove ability to pass a class

The EmbedInteractiveExample macro no longer needs to be able to accept a class so, this functionality can be removed.

We also need to add the copy, and link to the survey for beta testing the interactive editor.

alternative_name doesn't render nicely in the compat tables

See: https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/menus#Browser_compatibility

It would probably be better to render them as footnotes.

CompatBeta: Features with descriptions aren't linked

See https://developer.mozilla.org/en-US/docs/Web/API/AudioContext#Browser_compatibility

The "AudioContext() constructor" feature should be linked to https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/AudioContext. It has an mdn_url in the data, but the implementation ignores it.

It's this if-condition that is nuts: https://github.com/mdn/kumascript/blob/master/macros/CompatBeta.ejs#L109

Add-on sidebar "Channel" item links to a nonexistent page

See: https://bugzilla.mozilla.org/show_bug.cgi?id=1410743.

The problem is that the "Channel" item in the sidebar is given a link:

<li><a href="<%=baseURL%>Channels">Channels</a>

(at https://github.com/mdn/kumascript/blob/master/macros/AddonSidebar.ejs#L136). You can't left-click the link, but you can still right-click and try to open the link under the context menu. It will try to open something like "https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/Channels", and that page doesn't exist.

Probably the "Channel" item should be defined like:

<li><a href="#">Channels</a>

link has Chinese lead to `APIRef` or `JSRef` throw error?

Here are some links to the wrong page.
Web/API/自定义元素注册表
Web/API/自定义元素注册表/define
Web/JavaScript/Reference/Global_Objects/生成器函数
Web/JavaScript/Reference/Global_Objects/生成器函数/prototype

In this page APIRef or JSRef throw error. I think it might be because the link has Chinese. How do I fix it?

Update base URL for interactive examples

Now that the interactive examples live on S3, we need to update the base URL on https://github.com/mdn/kumascript/blob/master/macros/EmbedInteractiveExample.ejs

Add docs folder, expand documentation

As suggested by @Elchi3 on #204 (comment) :

I'd like to keep the docs in this repo. It allows making docs changes in the same PR as we change the code. Maybe it's time for a docs/ folder here, though. We could add a few files:

• Architecture.md (diagram, how KS works)
• Development.md (docker, setup, etc)
• UpdatingMacros.md (the most common workflow explained)
• TestingMacros.md (test infra, mocha, how to write tests, fixtures etc. explained)
• Contributing.md (points to development.md or UpdatingMacros.md or other docs depending on what you want to contribute).

It would be trivial to publish on RTD if setup as a Sphinx projects.

Alternatively, we could use the GitHub wiki pages to write the docs, but then doc updates would not be synced with commits.

Compat beta: Flag / note icons sometimes missing in main cell

See this page which should have the flag icon for Firefox 57: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#Browser_compatibility

WebExtBrowserCompatTable macro should support "alternative_name"

This PR: mdn/browser-compat-data#263 uses alternative_name, which the WebExtension table macro doesn't support.

Note that at some point we expect a new macro to be ready, that will work for all MDN pages (i.e. JS and CSS as well as WebExtensions) and at that point we will switch over to that table. So depending on when that will happen, it might be better to wait, than to fix this now.

"Audio Output Devices API" missing in {{SpecName}} and {{spec2}} macros

The Audio Output Devices API was released as Candidate Recommendation on October 3rd 2017, yet it is still missing from the {{SpecName}} and {{spec2}} macros.

Please add the following to {{SpecName}}:

    'Audio Output Devices API':{
        name : 'Audio Output Devices API',
        url  : 'https://www.w3.org/TR/audio-output/'
    },

And the following to {{Spec2}}:

  'Audio Output Devices API'  : 'CR',

JSRef macro doesn't play nicely with A/B testing

Compare the sidebars in:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat?v=a
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat?v=b

The first one has a nice sidebar, the second one doesn't. This is probably because the "b" page isn't actually located at https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat, and the JSRef macro uses the "current page slug" to build the sidebar.

The simplest fix is probably to enable JSRef to take an optional argument that is the correct URL, and for it to use that URL in preference to the current URL. Then the "b" variant pages could be edited to pass that argument into JSRef.

This was originally reported here: https://bugzilla.mozilla.org/show_bug.cgi?id=1395257

Compat macro "depth" argument should default to infinite

The Compat.ejs macro has a depth parameter that tells it how deep to go into subfeatures, when building a compat table.

But there seems to be no way to say "go as deep as there is data" which is generally what I want when building a compat table, otherwise I lose data.

My suggestion would be to make "go as deep as there is data" be the default value for depth, so I get that behavior if I omit the parameter. Then I can provide the argument when I want to restrict the depth (as I do when building aggregate tables).

UI strings should be translated in Pontoon

This is filed as bug 1340342, and duplicated here to make it easier to link to in PRs, etc.

Currently, user interface strings are translated inside macros, such as {{CompatNo}}, which uses localString:

kumascript/macros/CompatNo.ejs

Lines 2 to 12 in f195712

	var text = mdn.localString({
	"en-US": "No support",
	"de" : "Nicht unterstützt",
	"es" : "Sin soporte",
	"fr" : "Pas de support",
	"ja" : "未サポート",
	"nl" : "Niet ondersteund",
	"pt-BR": "Não suportado",
	"ru" : "Нет",
	"zh-CN": "未实现"
	});

It is difficult to update this translation or add new languages. You need to open a PR, ensure the JSON is valid, etc. A responsible reviewer would ensure that the macro continues working in the new languages, and that it works in the new language. Translators tend to change many macros at once, which multiplies the effort to review the PR, and so translation PRs are often left open and unreviewed.

I'd like to make these strings available in Pontoon, so that instead CompatNo is:

var text=gettext('No support');

and the string No support would be available in Pontoon with the other MDN strings.

Some steps to get there:

• Move translation files out of Kuma and into their own repository (https://github.com/mozilla-l10n/mdn-l10n)
• Build KumaScript Docker image from the Kuma project so that locales will be available
• Write an EJS parser for Babel, to extract strings from macros
• Integrate Jed, po2json, and sprintf-js into KumaScript
• Convert some sample macros
• Document the process
• Recruit the community to convert remaining macros