Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reorganize the docs. #1041

Merged
merged 11 commits into from
Dec 6, 2016
Merged

Reorganize the docs. #1041

merged 11 commits into from
Dec 6, 2016

Conversation

mareksuscak
Copy link
Contributor

@mareksuscak mareksuscak commented Dec 6, 2016

Resolves #930 + adds a new section on configuring Editors to get syntax highlighting.

Here's how it looks

screen shot 2016-12-06 at 15 55 50

Noteworthy Changes:

  • Blog link moved from the right menu to the left menu
  • Moved Options section under API page and removed the old page (old now redirects to new)
  • Removed Browser section as the same info is in the Setup guide
  • ES2015 is now a top level link


## Syntax Highlighting

Most popular editors these days do support ES2015+ syntax highlighting.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about:

These days, many popular editors support ES2015+ syntax highlighting out of the box, while some require installing additional extensions.

@danez
Copy link
Member

danez commented Dec 6, 2016

The options (at least most of them) are also valid for CLI usage, but maybe we should add a separate table there anyway? Especially to describe the common confusion on how to disable an option e.g. --no-comments, which options are only cli or only .babelrc etc

@mareksuscak
Copy link
Contributor Author

mareksuscak commented Dec 6, 2016

@danez I have moved the options section to the API docs. There's a blockquote. And we also link to that section from CLI page.

UPDATE: We can document how to disable the option, though.

@mareksuscak
Copy link
Contributor Author

I had a discussion with @hzoo and we agreed that this is the first step towards having better docs. I set the baseline and we need to further polish it in the following PRs. There's quite a bit of work left, I know.

---
layout: docs
title: Editors
description: Learn how to use Babel in the editor of choice
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be (emphasis mine):

Learn how to use Babel in your editor of choice

@existentialism
Copy link
Member

existentialism commented Dec 6, 2016

👍 nice work @mareksuscak!

@hzoo
Copy link
Member

hzoo commented Dec 6, 2016

@mareksuscak In the future we should discuss in #website on slack so there's no missing context


## Syntax Highlighting

These days, many popular editors support ES2015+ syntax highlighting
Copy link
Member

@hzoo hzoo Dec 6, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be interesting to have a screenshot of syntax highlighting somewhere on here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Absolutely. I can add that. If you happen to have such a picture with various ES syntax constructs in it, let me know. Otherwise, I'll create it myself.

@@ -4,6 +4,8 @@ title: API
description: How to use the Node.js API.
permalink: /docs/usage/api/
package: babel-core
Copy link
Member

@xtuc xtuc Dec 6, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I moved this doc in babel/babel (PR babel/babel#4938). It will be then included in the website at build-time (PR #1026)

Could you apply your modifications in babel repo ? Thanks.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For clarification this would mean making a pr to babel/babel in the babel-core readme

and then adding {% include package_readme.html %} instead of the content here.

we can do it in another pr too?

@hzoo hzoo merged commit 6989b87 into babel:master Dec 6, 2016
@hzoo
Copy link
Member

hzoo commented Dec 6, 2016

Thanks @mareksuscak!

@mareksuscak mareksuscak deleted the reorganize-docs branch December 6, 2016 19:35
@hzoo hzoo removed the blog label Sep 11, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants