babel / babel/website

Improve documentation on option settings

Open
#2,008 6 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
777
Forks
1.4k
Avg merge
16h 45m
Merged PRs (30d)
3

Description

## Feature Request

I feel it's utterly hard to grasp from the documentation where and how to set any of the Babel options.

Just reading something like:

```json
JSON
-----
{
"targets": "> 0.25%, not dead"
}
```

isn't helpful. The context describing where to put this information is missing throughout the documentation.

### Describe the solution you'd like

Can we have a dynamic solution, with a drop-down box replacing the "JSON" title.

The drop-down box should provide a list of configuration situations (e.g. package.json, babelrc, babel.config.js etc.).

Selecting an item from this drop down list should add context information to the given sample.

## Example

#### Instead of showing:

![image](https://user-images.githubusercontent.com/9283914/55554068-28494980-56e2-11e9-93a3-e5bf4ab60a26.png)

#### The proposed solution should show:

_(Please note the lower panel output, changing context information subject to the drop-down box's selection)_

![image](https://user-images.githubusercontent.com/9283914/55555183-f4235800-56e4-11e9-9b40-2741859f0214.png)

![image](https://user-images.githubusercontent.com/9283914/55554680-aa863d80-56e3-11e9-90c9-cbfb3919f5bb.png)

## Describe alternatives you've considered
Searching through the documentation over and over again for different configuration opportunities and how to apply a configuration setting.

## Teachability, Documentation, Adoption, Migration Strategy

I'm not familiar with Babel's configuration opportunities, yet the implementation should, basically, be quite simple:

A custom element (aka. web component) is supposed to take a sample text argument, either as attribute value or as innerHTML. Moreover, it is supposed to generate a drop-down box and a `

` element:

```html




      




```

There may be a static kind of array in that web componend containing an array of following type:
```ts
class ConfigOpportunity
{
constructor(public name: string, public prefix: string, public suffix: string) {}
}
```

The drop-down box is supposed to be filled with the array's names, like:

```ts
default export class BabelConfiguration extends HTMLElement
{
private static readonly configOpportunities: ConfigOpportunity[] =
[
new ConfigOpportunity("package.json", "{\n babel: {\n ", "\n }\n}");
, new ConfigOpportunity("babelrc", "", "");
, new ConfigOpportunity("babel.config.js", "{\n ", "\n}");
];

private readonly _list: HTMLSelectElement = document.createElement("select");

public connectedCallback()
{
configOpportunities.forEach((item: ConfigOpportunity, index: number) =>
{
const option: HTMLOptionElement = document.createElement("option");

option.value = index;
option.text = item.name;

this._list.appendChild(option);
});

this.appendChild(list);
}
}

// register the new web component in the browser
customElements.define("babel-configuration", BabelConfiguration);
```

The `` area is supposed to take the instance's innerHTML, provided by the web page author. I'm leaving this step out here for brevity.

And an event handler is supposed to change the `

` block's configuration opportunity's context content, according to the drop-down box's selection:

```js
this._list.addEventListener("change", () =>
{
const spans: HTMLSpanElement[] = this.getElementByTagName("span");

spans[0].textContent = configOpportunities[this._list.selectedIndex].prefix;
spans[2].textContent = configOpportunities[this._list.selectedIndex].suffix;
});
```

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.