Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Sync README -> docs/options.md * Sync README -> docs/*.md * Misc fixups * Remove markdown-toc * Remove insert-pragma from ToC * Never again! * Move all docs to ./docs * Remove yarn toc * Fix inter-doc links * Fix links in footer * Clean up README.md * Add basic description to README.md * Use flat badges * Move editor guides to website * Improve prettier-ignore docs * Fixup bad find/replace * Add JSON to README * Fix custom parser API link * Fixup GitHub centering, add downloads badge * Add 1.8 docs * docs(website): mention markdown on homepage (#1) * Add intro * Add watching-files.md * Fix markdown syntax highlighting * Switch back to .md links
- Loading branch information
Showing
40 changed files
with
931 additions
and
1,481 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -7,6 +7,7 @@ | |
/.vscode | ||
/dist | ||
/website/node_modules | ||
/website/build | ||
.DS_Store | ||
coverage | ||
.idea |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,115 @@ | ||
--- | ||
id: api | ||
title: API | ||
--- | ||
|
||
```js | ||
const prettier = require("prettier"); | ||
``` | ||
|
||
## `prettier.format(source [, options])` | ||
|
||
`format` is used to format text using Prettier. [Options](options.md) may be provided to override the defaults. | ||
|
||
```js | ||
prettier.format("foo ( );", { semi: false }); | ||
// -> "foo()" | ||
``` | ||
|
||
## `prettier.check(source [, options])` | ||
|
||
`check` checks to see if the file has been formatted with Prettier given those options and returns a `Boolean`. | ||
This is similar to the `--list-different` parameter in the CLI and is useful for running Prettier in CI scenarios. | ||
|
||
## `prettier.formatWithCursor(source [, options])` | ||
|
||
`formatWithCursor` both formats the code, and translates a cursor position from unformatted code to formatted code. | ||
This is useful for editor integrations, to prevent the cursor from moving when code is formatted. | ||
|
||
The `cursorOffset` option should be provided, to specify where the cursor is. This option cannot be used with `rangeStart` and `rangeEnd`. | ||
|
||
```js | ||
prettier.formatWithCursor(" 1", { cursorOffset: 2 }); | ||
// -> { formatted: '1;\n', cursorOffset: 1 } | ||
``` | ||
|
||
## `prettier.resolveConfig(filePath [, options])` | ||
|
||
`resolveConfig` can be used to resolve configuration for a given source file, passing its path as the first argument. | ||
The config search will start at the file path and continue to search up the directory (you can use `process.cwd()` to start | ||
searching from the current directory). | ||
Or you can pass directly the path of the config file as `options.config` if you don't wish to search for it. | ||
A promise is returned which will resolve to: | ||
* An options object, providing a [config file](./configuration-file.html) was found. | ||
* `null`, if no file was found. | ||
|
||
The promise will be rejected if there was an error parsing the configuration file. | ||
|
||
If `options.useCache` is `false`, all caching will be bypassed. | ||
|
||
```js | ||
const text = fs.readFileSync(filePath, "utf8"); | ||
prettier.resolveConfig(filePath).then(options => { | ||
const formatted = prettier.format(text, options); | ||
}) | ||
``` | ||
|
||
Use `prettier.resolveConfig.sync(filePath [, options])` if you'd like to use sync version. | ||
|
||
## `prettier.clearConfigCache()` | ||
|
||
As you repeatedly call `resolveConfig`, the file system structure will be cached for performance. | ||
This function will clear the cache. Generally this is only needed for editor integrations that | ||
know that the file system has changed since the last format took place. | ||
|
||
## `prettier.getSupportInfo([version])` | ||
|
||
Returns an object representing the parsers, languages and file types Prettier | ||
supports. | ||
|
||
If `version` is provided (e.g. `"1.5.0"`), information for that version will be | ||
returned, otherwise information for the current version will be returned. | ||
|
||
The support information looks like this: | ||
|
||
``` | ||
{ | ||
languages: Array<{ | ||
name: string, | ||
since: string, | ||
parsers: string[], | ||
group?: string, | ||
tmScope: string, | ||
aceMode: string, | ||
codemirrorMode: string, | ||
codemirrorMimeType: string, | ||
aliases?: string[], | ||
extensions: string[], | ||
filenames?: string[], | ||
linguistLanguageId: number, | ||
vscodeLanguageIds: string[], | ||
}> | ||
} | ||
``` | ||
|
||
## Custom Parser API | ||
|
||
If you need to make modifications to the AST (such as codemods), or you want to provide an alternate parser, you can do so by setting the `parser` option to a function. The function signature of the parser function is: | ||
```js | ||
(text: string, parsers: object, options: object) => AST; | ||
``` | ||
|
||
Prettier's built-in parsers are exposed as properties on the `parsers` argument. | ||
|
||
```js | ||
prettier.format("lodash ( )", { | ||
parser(text, { babylon }) { | ||
const ast = babylon(text); | ||
ast.program.body[0].expression.callee.name = "_"; | ||
return ast; | ||
} | ||
}); | ||
// -> "_();\n" | ||
``` | ||
|
||
The `--parser` CLI option may be a path to a node.js module exporting a parse function. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,114 @@ | ||
--- | ||
id: cli | ||
title: CLI | ||
--- | ||
|
||
Run Prettier through the CLI with this script. Run it without any | ||
arguments to see the [options](options.md). | ||
|
||
To format a file in-place, use `--write`. You may want to consider | ||
committing your code before doing that, just in case. | ||
|
||
```bash | ||
prettier [opts] [filename ...] | ||
``` | ||
|
||
In practice, this may look something like: | ||
|
||
```bash | ||
prettier --single-quote --trailing-comma es5 --write "{app,__{tests,mocks}__}/**/*.js" | ||
``` | ||
|
||
Don't forget the quotes around the globs! The quotes make sure that Prettier | ||
expands the globs rather than your shell, for cross-platform usage. | ||
The [glob syntax from the glob module](https://github.com/isaacs/node-glob/blob/master/README.md#glob-primer) | ||
is used. | ||
|
||
Prettier CLI will ignore files located in `node_modules` directory. To opt-out from this behavior use `--with-node-modules` flag. | ||
|
||
## `--debug-check` | ||
|
||
If you're worried that Prettier will change the correctness of your code, add `--debug-check` to the command. | ||
This will cause Prettier to print an error message if it detects that code correctness might have changed. | ||
Note that `--write` cannot be used with `--debug-check`. | ||
|
||
## `--find-config-path` and `--config` | ||
|
||
If you are repeatedly formatting individual files with `prettier`, you will incur a small performance cost | ||
when prettier attempts to look up a [configuration file](./configuration-file.html). In order to skip this, you may | ||
ask prettier to find the config file once, and re-use it later on. | ||
|
||
```bash | ||
prettier --find-config-path ./my/file.js | ||
./my/.prettierrc | ||
``` | ||
|
||
This will provide you with a path to the configuration file, which you can pass to `--config`: | ||
|
||
```bash | ||
prettier --config ./my/.prettierrc --write ./my/file.js | ||
``` | ||
|
||
You can also use `--config` if your configuration file lives somewhere where prettier cannot find it, | ||
such as a `config/` directory. | ||
|
||
If you don't have a configuration file, or want to ignore it if it does exist, | ||
you can pass `--no-config` instead. | ||
|
||
### `--ignore-path` | ||
|
||
Path to a file containing patterns that describe files to ignore. By default, prettier looks for `./.prettierignore`. | ||
|
||
## `--require-pragma` | ||
|
||
Require a special comment, called a pragma, to be present in the file's first docblock comment in order for prettier to format it. | ||
```js | ||
/** | ||
* @prettier | ||
*/ | ||
``` | ||
|
||
Valid pragmas are `@prettier` and `@format`. | ||
|
||
## `--insert-pragma` | ||
|
||
Insert a `@format` pragma to the top of formatted files when pragma is absent. | ||
Works well when used in tandem with `--require-pragma`. | ||
|
||
## `--list-different` | ||
|
||
Another useful flag is `--list-different` (or `-l`) which prints the filenames of files that are different from Prettier formatting. If there are differences the script errors out, which is useful in a CI scenario. | ||
|
||
```bash | ||
prettier --single-quote --list-different "src/**/*.js" | ||
``` | ||
|
||
## `--no-config` | ||
|
||
Do not look for a configuration file. The default settings will be used. | ||
|
||
## `--config-precedence` | ||
|
||
Defines how config file should be evaluated in combination of CLI options. | ||
|
||
**cli-override (default)** | ||
|
||
CLI options take precedence over config file | ||
|
||
**file-override** | ||
|
||
Config file take precedence over CLI options | ||
|
||
**prefer-file** | ||
|
||
If a config file is found will evaluate it and ignore other CLI options. If no config file is found CLI options will evaluate as normal. | ||
|
||
This option adds support to editor integrations where users define their default configuration but want to respect project specific configuration. | ||
|
||
## `--with-node-modules` | ||
|
||
Prettier CLI will ignore files located in `node_modules` directory. To opt-out from this behavior use `--with-node-modules` flag. | ||
|
||
## `--write` | ||
|
||
This rewrites all processed files in place. This is comparable to the `eslint --fix` workflow. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,16 @@ | ||
--- | ||
id: comparison | ||
title: Prettier vs. Linters | ||
--- | ||
|
||
## How does it compare to ESLint/TSLint/stylelint, etc.? | ||
|
||
Linters have two categories of rules: | ||
|
||
**Formatting rules**: eg: [max-len](http://eslint.org/docs/rules/max-len), [no-mixed-spaces-and-tabs](http://eslint.org/docs/rules/no-mixed-spaces-and-tabs), [keyword-spacing](http://eslint.org/docs/rules/keyword-spacing), [comma-style](http://eslint.org/docs/rules/comma-style)... | ||
|
||
Prettier alleviates the need for this whole category of rules! Prettier is going to reprint the entire program from scratch in a consistent way, so it's not possible for the programmer to make a mistake there anymore :) | ||
|
||
**Code-quality rules**: eg [no-unused-vars](http://eslint.org/docs/rules/no-unused-vars), [no-extra-bind](http://eslint.org/docs/rules/no-extra-bind), [no-implicit-globals](http://eslint.org/docs/rules/no-implicit-globals), [prefer-promise-reject-errors](http://eslint.org/docs/rules/prefer-promise-reject-errors)... | ||
|
||
Prettier does nothing to help with those kind of rules. They are also the most important ones provided by linters as they are likely to catch real bugs with your code! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,85 @@ | ||
--- | ||
id: configuration | ||
title: Configuration File | ||
--- | ||
|
||
Prettier uses [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) for configuration file support. | ||
This means you can configure prettier via: | ||
|
||
* A `.prettierrc` file, written in YAML or JSON, with optional extensions: `.yaml/.yml/.json/.js`. | ||
* A `prettier.config.js` file that exports an object. | ||
* A `"prettier"` key in your `package.json` file. | ||
|
||
The configuration file will be resolved starting from the location of the file being formatted, | ||
and searching up the file tree until a config file is (or isn't) found. | ||
|
||
The options to the configuration file are the same the [API options](options.md). | ||
|
||
## Basic Configuration | ||
|
||
JSON: | ||
|
||
```json | ||
// .prettierrc | ||
{ | ||
"printWidth": 100, | ||
"parser": "flow" | ||
} | ||
``` | ||
|
||
YAML: | ||
|
||
```yaml | ||
# .prettierrc | ||
printWidth: 100 | ||
parser: flow | ||
``` | ||
|
||
## Configuration Overrides | ||
|
||
Prettier borrows eslint's [override format](http://eslint.org/docs/user-guide/configuring#example-configuration). | ||
This allows you to apply configuration to specific files. | ||
|
||
JSON: | ||
|
||
```json | ||
{ | ||
"semi": false, | ||
"overrides": [{ | ||
"files": "*.test.js", | ||
"options": { | ||
"semi": true | ||
} | ||
}] | ||
} | ||
``` | ||
|
||
YAML: | ||
|
||
```yaml | ||
semi: false | ||
overrides: | ||
- files: "*.test.js" | ||
options: | ||
semi: true | ||
``` | ||
|
||
`files` is required for each override, and may be a string or array of strings. | ||
`excludeFiles` may be optionally provided to exclude files for a given rule, and may also be a string or array of strings. | ||
|
||
To get prettier to format its own `.prettierrc` file, you can do: | ||
|
||
```json | ||
{ | ||
"overrides": [{ | ||
"files": ".prettierrc", | ||
"options": { "parser": "json" } | ||
}] | ||
} | ||
``` | ||
|
||
For more information on how to use the CLI to locate a file, see the [CLI](cli.md) section. | ||
|
||
## Configuration Schema | ||
|
||
If you'd like a JSON schema to validate your configuration, one is available here: http://json.schemastore.org/prettierrc. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.