A lot of Codex users (including all users using it inside MediaWiki) don't use TypeScript. However, all code examples in the documentation do use TypeScript. This is confusing for people who don't know TypeScript and don't know how to mentally transform TypeScript code to plain JavaScript code. We should provide code examples that are readable and copy-pasteable for the majority of our users.
There are three main approaches we could take:
- Provide both TS and plain JS versions of the same examples. Allow viewers of the docs site to toggle between them
- Change all our examples from TS to plain JS, leaving no TS examples
- Change all our examples from TS to JS with type annotation comments
#1 would be ideal, but would take more work. In the short term, #2 would be easier to achieve. I'm not sure that #3 has as much value, because it's not very easy to mentally transform JS with jsdoc comments to TypeScript either.
Additionally, there are other barriers to copy-pasting code from our docs site into MediaWiki that we should consider:
- import/export vs require/module.exports
- Self-closing tag treatment: <cdx-icon :icon="foo" /> vs <cdx-icon :icon="foo"></cdx-icon>
- Importing tokens (when using mixins, see also T328602): @import '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less'; vs @import 'mediawiki.skin.variables.less';
For those reasons we should consider providing MW-specific code samples alongside generic code samples where the two differ.
Approach
We decided to:
- Make the gap between our code samples and code that works in MW smaller:
- Change all code samples to use plain JS (with type annotation comments where useful)
- Only use ES6 syntax in code samples, to improve MediaWiki compatibility
- Remove getEventLogger, and replace it with hard-coded event handlers in each example
- Automatically generate MW-compatible versions of the code samples
- Write a script that applies transformations to a regular code example to make it MW-compatible
- Change import/export to require/module.exports
- Change imports from @wikimedia/codex-icons to import from ./icons.json instead
- Change Less imports of @wikimedia/codex-design-tokens to import mediawiki.skin.variables.less instead
- Change self-closing tags to non-self-closing tags
- Build the generated code samples to an examples-mw directory (packages/codex-docs/component-demos/COMPONENT-NAME/examples-mw/) and gitignore those directories
- Update all the .md files to use a code group with two tabs, like this
- Write a script that applies transformations to a regular code example to make it MW-compatible
Acceptance Criteria
- Our code samples don't use TypeScript or ES >6 syntax
- All code samples at https://doc.wikimedia.org/codex are available in regular and MW-targeted versions
