Rewrote the docs structure. (#509)

* Changed folder structure, did a bunch of cleanup and introduce a doc helper to compose markdown in markdown. * Added basic rome styling. * Added some more styling. * Added hero. * Added more padding at bottom * Added permalinks. * Made border radius consistent. * Added basic mobile view. * npm instead of yarn, which we already use in @romejs-web/frontend * Removed yarn-error.log from gitignore due to npm * Migrated to sass * Cleanup from migrating to sass * Rewrote parts in sass * Formatted sass * Do not bundle unused resources. * Split sass components in separate files. * Added config for HTML meta tags. * Proposing a different document format. * Fixing broken links. * Consistency across titles. * Update website/src/docs/Introduction.md Co-authored-by: Kevin Kelbie <[email protected]> * Update website/src/docs/Linting.md Co-authored-by: Kevin Kelbie <[email protected]> Co-authored-by: Kevin Kelbie <[email protected]>
rome · May 23, 2020 · 9255e80 · 9255e80
1 parent f5486e4
commit 9255e80
Show file tree

Hide file tree

Showing 8 changed files with 97 additions and 199 deletions.
diff --git a/website/src/docs/Contributing.md b/website/src/docs/Contributing.md
@@ -4,8 +4,6 @@ We can use help in a bunch of areas and any help is appreciated. Our [GitHub iss
 
 Our [Discord server](https://discord.gg/9WxHa5d) is open for help and more adhoc discussion. All activity on the Discord is still moderated and will be strictly enforced under the project's [Code of Conduct](https://github.com/romejs/rome/blob/master/.github/CODE_OF_CONDUCT.md).
 
-## Getting Started
-
 Getting started with developing Rome is as easy as three commands. You will need Node v12 or above.
 
 ```bash
@@ -14,11 +12,11 @@ cd rome
 scripts/dev-rome --help
 ```
 
-> Note: If you previously ran the user-facing [installation instructions](../introduction/installation), the `dist` directory must be deleted before running any development commands.
+> Note: If you previously ran the user-facing [installation](#installation), the `dist` directory must be deleted before running any development commands.
 
 No dependency installation step is required as we check in our `node_modules` folder that contains only a copy of TypeScript and some definitions.
 
-Refer to [Getting Started](../introduction/getting-started.md) for more usage documentation.
+Refer to [Getting started](#getting-started) for more usage documentation.
 
 ## Testing
 
@@ -30,7 +28,7 @@ scripts/dev-rome test
 
 This will run all tests inside of any `__rtests__` directories.
 
-## Type Checking
+## Type checking
 
 Run TypeScript with code emitting disabled to perform a full typecheck outside the editor.
 

diff --git a/website/src/docs/Getting started.md b/website/src/docs/Getting started.md
@@ -1,106 +1,20 @@
-# Getting-started
+# Getting started
 
-While Rome seeks to fill the role of many tools in the JavaScript
-ecosystem, it can be integrated into existing projects and used
-as much or as little as you like.
-
-## Integrating Rome
+While Rome seeks to fill the role of many tools in the JavaScript ecosystem, it can be integrated into existing projects and used as much or as little as you like.
 
 First, navigate into your project folder:
 
 ```bash
 cd my_existing_project
 ```
 
-Now, create a Rome configuration for your project. When prompted,
-use the recommended settings:
+Now, create a Rome configuration for your project. When prompted, it is advised to use the recommended settings:
 
 ```bash
 rome init
 ```
 
-## What did we do?
-
-Running `rome init` with the recommended settings creates a Rome
-configuration file, `rome.json`, which looks like this:
-
-```json
-{
-  "version": "^0.0.52",
-  "lint": {
-    "enabled": true
-  }
-}
-```
-
-This file tells `rome` that it should be at least version 0.0.52
-in order to work with your project, and that it should lint your code.
-If you want to disable linting or apply advanced settings, see
-the `rome init` documentation.
-
-## Running your code
-
-The `rome run` command will run whatever file is passed to
-it. Use this command with your project's main file, for example:
-
-```bash
-rome run index.js
-```
-
-Rome is still under active development and may not be able to properly
-process all source files. If you are able to run a file with `node` but
-not with `rome`, please [create an issue](https://github.com/romejs/rome/issues/new?labels=bug&template=01_bug.md&title=)
-
-## Other Commands
-
-### `lint`
-
-This command will lint a file with a set of default lints and display the produced diagnostics.
-When ran with no arguments, all JavaScript files in a project are linted. For example:
-
-```bash
-rome lint file.js
-```
-
-### `compile`
-
-This command will compile a file with a set of default transforms. There is currently no options for this command to specify a subset of transforms.
-
-```
-rome compile file.js
-```
-
-### `parse`
-
-This command will parse a file and output a pretty formatted AST.
-
-```
-rome parse file.js
-```
-
-
-## `init`
-
-The `init` command helps you to initially setup your project for `rome`. Inside your project root directory run:
-
-```bash
-$ rome init
-```
-
-Following this `rome` will ask you whether you want to use the default setup or customize your project further. You can switch between `yes` and `no` with the arrow keys. Press `enter` to confirm your choice.
-
-```bash
-  Welcome to Rome!
-
-❯ Use recommended settings?
-ℹ Use arrow keys and then enter to select an option
-  ◉ Yes
-  ◯ No
-```
-
-### Default configuration
-
-If you choose `yes`, `rome` will create a default configuration file `rome.json` that looks like this:
+This command creates a Rome configuration file, `rome.json`, which looks like this:
 
 ```json
 {
@@ -111,53 +25,4 @@ If you choose `yes`, `rome` will create a default configuration file `rome.json`
 }
 ```
 
-### Customized configuration
-
-If you choose to customize your project further with the `no` option, you will be guided through a set of questions. First you get the chance give your project a name. Enter the name of your project and confirm with the `enter` key.
-
-```bash
- Welcome to Rome!
-
-ℹ Press space to select an option and enter to confirm
-❯ Use recommended settings?: No
-? Project name:
-```
-
-After this you have a choice of whether you want to enable linting, formatting and/or testing. You can move between the choices with the arrow keys. Check and uncheck a box with the `space` key.
-
-```bash
- Welcome to Rome!
-
-❯ Use recommended settings?: No
-? Project name: hello-world
-❯ Features enabled
-ℹ Use arrow keys and space to select or deselect options and then enter to confirm
-  ☑ Lint
-  ☐ Format
-```
-
-Choosing all options results in a config file like this:
-
-```json
-{
-  "name": "hello-world",
-  "version": "^0.0.52",
-  "lint": {
-    "enabled": true
-  },
-  "format": {
-    "enabled": true
-  }
-}
-```
-
-### I already have a configuration file
-
-If the project already contains a configuration file the `init` command will exit with an error.
-
-```bash
-✖ rome.json file already exists
-ℹ Use `rome config` to update an existing config
-```
-
-Instead of `init` use the `config` command to update your configuration.
+You're all set to get started with Rome. Continue reading to explore the variety of commands that Rome supports.
diff --git a/website/src/docs/Installation.md b/website/src/docs/Installation.md
@@ -1,14 +1,8 @@
 # Installation
 
-## Before you continue
+Rome requires you to have `node` and `npm` installed on your system. Make sure you have these before you proceed.
 
-To install Rome, you must have `node` and `npm` installed on your system. If you do not have `node` and `npm`
-installed, install them before continuing.
-
-## Cloning and building
-
-Rome is not available via `npm` and must be installed from GitHub.
-In a folder of your choice, clone the `rome` repository:
+Rome is currently not available via `npm`, and must be installed from GitHub. In a folder of your choice, clone the `rome` repository.
 
 ```bash
 git clone https://github.com/romejs/rome
@@ -20,19 +14,18 @@ Then, navigate into it and build `rome`:
 cd rome; ./scripts/build-release dist
 ```
 
-On Windows 10 build `rome` using the following command using PowerShell 7:
+On Windows 10, build `rome` using the following command in PowerShell 7:
 
-```powershell
+```bash
 cd rome && node scripts/build-release dist
 ```
 
-Now, install `rome` globally:
+As a final step, install `rome` globally:
 
-```
+```bash
 npm install -g ./dist/
 ```
 
 Congratulations! Rome is installed.
 
-When it comes time to update Rome, repeat the above process. `npm` will
-automatically overwrite your existing Rome installation with the new version.
+When it comes time to update Rome, repeat the above process. `npm` will automatically overwrite your existing Rome installation with the new version.
diff --git a/website/src/docs/Intro.md b/website/src/docs/Intro.md
@@ -1,4 +1,4 @@
 <div class="hero">
-  <h1 toc-exclude>Rome is a JavaScript toolchain</h1>
-  <h2 toc-exclude>Linting, bundling, compiling, testing, and more</h2>
+  <h1 toc-exclude>Your next-gen JavaScript toolchain.</h1>
+  <h2 toc-exclude>Focus on code, let Rome take care of the rest!</h2>
 </div>
diff --git a/website/src/docs/Introduction.md b/website/src/docs/Introduction.md
@@ -0,0 +1,5 @@
+# Introduction
+
+Rome is an all-in-one JavaScript toolchain, including a compiler, linter, formatter, bundler, testing framework and more. It aims to be a comprehensive tool for anything related to the processing of JavaScript source code.
+
+Rome aims to be a replacement for many existing JavaScript tools. We will, however, offer integrations for components in other tools. For example, using the Rome compiler as a plugin for another bundler.
diff --git a/website/src/docs/Commands.md → website/src/docs/Linting.md b/website/src/docs/Commands.md → website/src/docs/Linting.md
@@ -1,33 +1,41 @@
-# Commands
+# Linting
 
-## `lint`
+Rome comes with a builtin linter that analyzes your JavaScript code to flag programming errors, bugs, stylistic errors and more.
 
-The `lint` command checks your project files for code problems, such as unused variables. If no arguments are given, the entire project will be included.
+```javascript
+// Lint your entire project.
+rome lint
 
-```bash
-rome lint [files]
+// Lint one or more specific files.
+rome lint index.js hello.js
 ```
 
-### Checking only certain files
+## Interpreting the result
 
-If you want to lint only certain files, you can add the files you want to check:
+If `rome` did not detect any problems, you'll get a result like this:
 
-```bash
-$ rome lint index.js hello.js
+```javascript
+ℹ 1 file linted
+✔ No known problems!
 ```
 
-### Interpreting the result
+However, if there is something not ok, `rome` will provide you with diagnostics warnings in the following format:
 
-If `rome` did not detect any problems, you'll get the a result like this:
+```javascript
+<the affected file>:<line>:<column> <the linter rule that was violated>
+-----------------------------------
 
-```bash
-ℹ 1 file linted
-✔ No known problems!
-```
+x description of what is not ok
 
-However if there is something not ok, `rome` will give you error messages in the following format:
+> 1 | the line of code that is problematic
+    |     ^^^ <the part of the line that is not ok>
 
-```bash
+ ℹ helpful message(s) of what you can do to fix the problem
+ ```
+
+Let's look at an example of what the linter might throw at you:
+
+```javascript
 foobar.js:1 parse/js ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
   ✖ import and export can only appear in a module
@@ -40,37 +48,23 @@ foobar.js:1 parse/js ━━━━━━━━━━━━━━━━━━━
   ℹ Add "type": "module" to your package.json
 ```
 
-These messages contain the following sections:
+Rome will point you to the mistake in your JavaScript source code, and will potentially list you with options on how you can fix these.  You'll be presented with 1 message for each problem.
 
-```
-<the affected file>:<line>:<column> <the linter rule that was violated>
------------------------------------
-
-x description of what is not ok
-
-> 1 | the line of code that is problematic
-    |     ^^^ <the part of the line that is not ok>
-
- ℹ helpful message(s) of what you can do to fix the problem
-```
-
-You'll get 1 message for each problem.
-
-### Example
+## Example
 
 The following code has 2 unused variables: `join` in line 1 and `unused` in line 3.
 
-```js
+```javascript
 const {join} = require('path');
 
 const unused = 'I am not used :)';
 
 console.log('hello world!');
 ```
 
-The result for this code would look like this:
+You'll notice that Rome provides you with the following detailed warnings:
 
-```bash
+```javascript
 index.js:1:8 lint/unusedVariables ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
   ✖ Unused variable join
@@ -94,4 +88,4 @@ index.js:1:8 lint/unusedVariables ━━━━━━━━━━━━━━━
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ℹ 1 file linted
 ✖ Found 2 problems
-```
+```