markdown.js 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387
  1. const md = `---
  2. id: options
  3. title: Options
  4. ---
  5. Prettier ships with a handful of customizable format options, usable in both the CLI and API.
  6. ## Print Width
  7. Specify the line length that the printer will wrap on.
  8. > **For readability we recommend against using more than 80 characters:**
  9. >
  10. > In code styleguides, maximum line length rules are often set to 100 or 120. However, when humans write code, they don't strive to reach the maximum number of columns on every line. Developers often use whitespace to break up long lines for readability. In practice, the average line length often ends up well below the maximum.
  11. >
  12. > Prettier, on the other hand, strives to fit the most code into every line. With the print width set to 120, prettier may produce overly compact, or otherwise undesirable code.
  13. >
  14. > See the [print width rationale](rationale.md#print-width) for more information.
  15. | Default | CLI Override | API Override |
  16. | ------- | --------------------- | ------------------- |
  17. | \`80\` | \`--print-width <int>\` | \`printWidth: <int>\` |
  18. (If you don't want line wrapping when formatting Markdown, you can set the [Prose Wrap](#prose-wrap) option to disable it.)
  19. ## Tab Width
  20. Specify the number of spaces per indentation-level.
  21. | Default | CLI Override | API Override |
  22. | ------- | ------------------- | ----------------- |
  23. | \`2\` | \`--tab-width <int>\` | \`tabWidth: <int>\` |
  24. ## Tabs
  25. Indent lines with tabs instead of spaces.
  26. | Default | CLI Override | API Override |
  27. | ------- | ------------ | ----------------- |
  28. | \`false\` | \`--use-tabs\` | \`useTabs: <bool>\` |
  29. (Tabs will be used for _indentation_ but Prettier uses spaces to _align_ things, such as in ternaries.)
  30. ## Semicolons
  31. Print semicolons at the ends of statements.
  32. Valid options:
  33. - \`true\` - Add a semicolon at the end of every statement.
  34. - \`false\` - Only add semicolons at the beginning of lines that [may introduce ASI failures](rationale.md#semicolons).
  35. | Default | CLI Override | API Override |
  36. | ------- | ------------ | -------------- |
  37. | \`true\` | \`--no-semi\` | \`semi: <bool>\` |
  38. ## Quotes
  39. Use single quotes instead of double quotes.
  40. Notes:
  41. - JSX quotes ignore this option – see [jsx-single-quote](#jsx-quotes).
  42. - If the number of quotes outweighs the other quote, the quote which is less used will be used to format the string - Example: \`"I'm double quoted"\` results in \`"I'm double quoted"\` and \`"This \\"example\\" is single quoted"\` results in \`'This "example" is single quoted'\`.
  43. See the [strings rationale](rationale.md#strings) for more information.
  44. | Default | CLI Override | API Override |
  45. | ------- | ---------------- | --------------------- |
  46. | \`false\` | \`--single-quote\` | \`singleQuote: <bool>\` |
  47. ## Quote Props
  48. Change when properties in objects are quoted.
  49. Valid options:
  50. - \`"as-needed"\` - Only add quotes around object properties where required.
  51. - \`"consistent"\` - If at least one property in an object requires quotes, quote all properties.
  52. - \`"preserve"\` - Respect the input use of quotes in object properties.
  53. | Default | CLI Override | API Override |
  54. | ------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
  55. | \`"as-needed"\` | <code>--quote-props <as-needed&#124;consistent&#124;preserve></code> | <code>quoteProps: "<as-needed&#124;consistent&#124;preserve>"</code> |
  56. ## JSX Quotes
  57. Use single quotes instead of double quotes in JSX.
  58. | Default | CLI Override | API Override |
  59. | ------- | -------------------- | ------------------------ |
  60. | \`false\` | \`--jsx-single-quote\` | \`jsxSingleQuote: <bool>\` |
  61. ## Trailing Commas
  62. _Default value changed from \`none\` to \`es5\` in v2.0.0_
  63. Print trailing commas wherever possible when multi-line. (A single-line array, for example, never gets trailing commas.)
  64. Valid options:
  65. - \`"es5"\` - Trailing commas where valid in ES5 (objects, arrays, etc.)
  66. - \`"none"\` - No trailing commas.
  67. - \`"all"\` - Trailing commas wherever possible (including function arguments). This requires node 8 or a [transform](https://babeljs.io/docs/plugins/syntax-trailing-function-commas/).
  68. | Default | CLI Override | API Override |
  69. | ------- | ------------------------------------------------------ | ------------------------------------------------------ |
  70. | \`"es5"\` | <code>--trailing-comma <es5&#124;none&#124;all></code> | <code>trailingComma: "<es5&#124;none&#124;all>"</code> |
  71. ## Bracket Spacing
  72. Print spaces between brackets in object literals.
  73. Valid options:
  74. - \`true\` - Example: \`{ foo: bar }\`.
  75. - \`false\` - Example: \`{foo: bar}\`.
  76. | Default | CLI Override | API Override |
  77. | ------- | ---------------------- | ------------------------ |
  78. | \`true\` | \`--no-bracket-spacing\` | \`bracketSpacing: <bool>\` |
  79. ## JSX Brackets
  80. Put the \`>\` of a multi-line JSX element at the end of the last line instead of being alone on the next line (does not apply to self closing elements).
  81. Valid options:
  82. - \`true\` - Example:
  83. <!-- prettier-ignore -->
  84. \`\`\`jsx
  85. <button
  86. className="prettier-class"
  87. id="prettier-id"
  88. onClick={this.handleClick}>
  89. Click Here
  90. </button>
  91. \`\`\`
  92. - \`false\` - Example:
  93. <!-- prettier-ignore -->
  94. \`\`\`jsx
  95. <button
  96. className="prettier-class"
  97. id="prettier-id"
  98. onClick={this.handleClick}
  99. >
  100. Click Here
  101. </button>
  102. \`\`\`
  103. | Default | CLI Override | API Override |
  104. | ------- | ------------------------- | ---------------------------- |
  105. | \`false\` | \`--jsx-bracket-same-line\` | \`jsxBracketSameLine: <bool>\` |
  106. ## Arrow Function Parentheses
  107. _First available in v1.9.0, default value changed from \`avoid\` to \`always\` in v2.0.0_
  108. Include parentheses around a sole arrow function parameter.
  109. Valid options:
  110. - \`"always"\` - Always include parens. Example: \`(x) => x\`
  111. - \`"avoid"\` - Omit parens when possible. Example: \`x => x\`
  112. | Default | CLI Override | API Override |
  113. | ---------- | ----------------------------------------------- | ----------------------------------------------- |
  114. | \`"always"\` | <code>--arrow-parens <always&#124;avoid></code> | <code>arrowParens: "<always&#124;avoid>"</code> |
  115. At first glance, avoiding parentheses may look like a better choice because of less visual noise.
  116. However, when Prettier removes parentheses, it becomes harder to add type annotations, extra arguments or default values as well as making other changes.
  117. Consistent use of parentheses provides a better developer experience when editing real codebases, which justifies the default value for the option.
  118. ## Range
  119. Format only a segment of a file.
  120. These two options can be used to format code starting and ending at a given character offset (inclusive and exclusive, respectively). The range will extend:
  121. - Backwards to the start of the first line containing the selected statement.
  122. - Forwards to the end of the selected statement.
  123. These options cannot be used with \`cursorOffset\`.
  124. | Default | CLI Override | API Override |
  125. | ---------- | --------------------- | ------------------- |
  126. | \`0\` | \`--range-start <int>\` | \`rangeStart: <int>\` |
  127. | \`Infinity\` | \`--range-end <int>\` | \`rangeEnd: <int>\` |
  128. ## Parser
  129. Specify which parser to use.
  130. Prettier automatically infers the parser from the input file path, so you shouldn't have to change this setting.
  131. Both the \`babel\` and \`flow\` parsers support the same set of JavaScript features (including Flow type annotations). They might differ in some edge cases, so if you run into one of those you can try \`flow\` instead of \`babel\`. Almost the same applies to \`typescript\` and \`babel-ts\`. \`babel-ts\` might support JavaScript features (proposals) not yet supported by TypeScript, but it's less permissive when it comes to invalid code and less battle-tested than the \`typescript\` parser.
  132. Valid options:
  133. - \`"babel"\` (via [@babel/parser](https://github.com/babel/babel/tree/master/packages/babel-parser)) _Named \`"babylon"\` until v1.16.0_
  134. - \`"babel-flow"\` (same as \`"babel"\` but enables Flow parsing explicitly to avoid ambiguity) _First available in v1.16.0_
  135. - \`"babel-ts"\` (similar to \`"typescript"\` but uses Babel and its TypeScript plugin) _First available in v2.0.0_
  136. - \`"flow"\` (via [flow-parser](https://github.com/facebook/flow/tree/master/src/parser))
  137. - \`"typescript"\` (via [@typescript-eslint/typescript-estree](https://github.com/typescript-eslint/typescript-eslint)) _First available in v1.4.0_
  138. - \`"css"\` (via [postcss-scss](https://github.com/postcss/postcss-scss) and [postcss-less](https://github.com/shellscape/postcss-less), autodetects which to use) _First available in v1.7.1_
  139. - \`"scss"\` (same parsers as \`"css"\`, prefers postcss-scss) _First available in v1.7.1_
  140. - \`"less"\` (same parsers as \`"css"\`, prefers postcss-less) _First available in v1.7.1_
  141. - \`"json"\` (via [@babel/parser parseExpression](https://babeljs.io/docs/en/next/babel-parser.html#babelparserparseexpressioncode-options)) _First available in v1.5.0_
  142. - \`"json5"\` (same parser as \`"json"\`, but outputs as [json5](https://json5.org/)) _First available in v1.13.0_
  143. - \`"json-stringify"\` (same parser as \`"json"\`, but outputs like \`JSON.stringify\`) _First available in v1.13.0_
  144. - \`"graphql"\` (via [graphql/language](https://github.com/graphql/graphql-js/tree/master/src/language)) _First available in v1.5.0_
  145. - \`"markdown"\` (via [remark-parse](https://github.com/wooorm/remark/tree/master/packages/remark-parse)) _First available in v1.8.0_
  146. - \`"mdx"\` (via [remark-parse](https://github.com/wooorm/remark/tree/master/packages/remark-parse) and [@mdx-js/mdx](https://github.com/mdx-js/mdx/tree/master/packages/mdx)) _First available in v1.15.0_
  147. - \`"html"\` (via [angular-html-parser](https://github.com/ikatyang/angular-html-parser/tree/master/packages/angular-html-parser)) _First available in 1.15.0_
  148. - \`"vue"\` (same parser as \`"html"\`, but also formats vue-specific syntax) _First available in 1.10.0_
  149. - \`"angular"\` (same parser as \`"html"\`, but also formats angular-specific syntax via [angular-estree-parser](https://github.com/ikatyang/angular-estree-parser)) _First available in 1.15.0_
  150. - \`"lwc"\` (same parser as \`"html"\`, but also formats LWC-specific syntax for unquoted template attributes) _First available in 1.17.0_
  151. - \`"yaml"\` (via [yaml](https://github.com/eemeli/yaml) and [yaml-unist-parser](https://github.com/ikatyang/yaml-unist-parser)) _First available in 1.14.0_
  152. [Custom parsers](api.md#custom-parser-api) are also supported. _First available in v1.5.0_
  153. | Default | CLI Override | API Override |
  154. | ------- | ----------------------------------------------- | ---------------------------------------------------------- |
  155. | None | \`--parser <string>\`<br />\`--parser ./my-parser\` | \`parser: "<string>"\`<br />\`parser: require("./my-parser")\` |
  156. Note: the default value was \`"babylon"\` until v1.13.0.
  157. <a name="filepath"></a>
  158. ## File Path
  159. Specify the file name to use to infer which parser to use.
  160. For example, the following will use the CSS parser:
  161. \`\`\`bash
  162. cat foo | prettier --stdin-filepath foo.css
  163. \`\`\`
  164. | Default | CLI Override | API Override |
  165. | ------- | --------------------------- | ---------------------- |
  166. | None | \`--stdin-filepath <string>\` | \`filepath: "<string>"\` |
  167. ## Require pragma
  168. _First available in v1.7.0_
  169. Prettier can restrict itself to only format files that contain a special comment, called a pragma, at the top of the file. This is very useful when gradually transitioning large, unformatted codebases to prettier.
  170. For example, a file with the following as its first comment will be formatted when \`--require-pragma\` is supplied:
  171. \`\`\`js
  172. /**
  173. * @prettier
  174. */
  175. \`\`\`
  176. or
  177. \`\`\`js
  178. /**
  179. * @format
  180. */
  181. \`\`\`
  182. | Default | CLI Override | API Override |
  183. | ------- | ------------------ | ----------------------- |
  184. | \`false\` | \`--require-pragma\` | \`requirePragma: <bool>\` |
  185. ## Insert Pragma
  186. _First available in v1.8.0_
  187. Prettier can insert a special @format marker at the top of files specifying that the file has been formatted with prettier. This works well when used in tandem with the \`--require-pragma\` option. If there is already a docblock at the top of the file then this option will add a newline to it with the @format marker.
  188. | Default | CLI Override | API Override |
  189. | ------- | ----------------- | ---------------------- |
  190. | \`false\` | \`--insert-pragma\` | \`insertPragma: <bool>\` |
  191. ## Prose Wrap
  192. _First available in v1.8.2_
  193. By default, Prettier will wrap markdown text as-is since some services use a linebreak-sensitive renderer, e.g. GitHub comment and BitBucket. In some cases you may want to rely on editor/viewer soft wrapping instead, so this option allows you to opt out with \`"never"\`.
  194. Valid options:
  195. - \`"always"\` - Wrap prose if it exceeds the print width.
  196. - \`"never"\` - Do not wrap prose.
  197. - \`"preserve"\` - Wrap prose as-is. _First available in v1.9.0_
  198. | Default | CLI Override | API Override |
  199. | ------------ | ----------------------------------------------------------- | ----------------------------------------------------------- |
  200. | \`"preserve"\` | <code>--prose-wrap <always&#124;never&#124;preserve></code> | <code>proseWrap: "<always&#124;never&#124;preserve>"</code> |
  201. ## HTML Whitespace Sensitivity
  202. _First available in v1.15.0_
  203. Specify the global whitespace sensitivity for HTML files, see [whitespace-sensitive formatting] for more info.
  204. [whitespace-sensitive formatting]: https://prettier.io/blog/2018/11/07/1.15.0.html#whitespace-sensitive-formatting
  205. Valid options:
  206. - \`"css"\` - Respect the default value of CSS \`display\` property.
  207. - \`"strict"\` - Whitespaces are considered sensitive.
  208. - \`"ignore"\` - Whitespaces are considered insensitive.
  209. | Default | CLI Override | API Override |
  210. | ------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
  211. | \`"css"\` | <code>--html-whitespace-sensitivity <css&#124;strict&#124;ignore></code> | <code>htmlWhitespaceSensitivity: "<css&#124;strict&#124;ignore>"</code> |
  212. ## Vue files script and style tags indentation
  213. _First available in v1.19.0_
  214. Whether or not to indent the code inside \`<script>\` and \`<style>\` tags in Vue files. Some people (like [the creator of Vue](https://github.com/prettier/prettier/issues/3888#issuecomment-459521863)) don’t indent to save an indentation level, but this might break code folding in your editor.
  215. Valid options:
  216. - \`"false"\` - Do not indent script and style tags in Vue files.
  217. - \`"true"\` - Indent script and style tags in Vue files.
  218. | Default | CLI Override | API Override |
  219. | ------- | ------------------------------- | --------------------------------- |
  220. | \`false\` | \`--vue-indent-script-and-style\` | \`vueIndentScriptAndStyle: <bool>\` |
  221. ## End of Line
  222. _First available in v1.15.0, default value changed from \`auto\` to \`lf\` in v2.0.0_
  223. For historical reasons, there exist two common flavors of line endings in text files.
  224. That is \`\\n\` (or \`LF\` for _Line Feed_) and \`\\r\\n\` (or \`CRLF\` for _Carriage Return + Line Feed_).
  225. The former is common on Linux and macOS, while the latter is prevalent on Windows.
  226. Some details explaining why it is so [can be found on Wikipedia](https://en.wikipedia.org/wiki/Newline).
  227. When people collaborate on a project from different operating systems, it becomes easy to end up with mixed line endings in a shared git repository.
  228. It is also possible for Windows users to accidentally change line endings in a previously committed file from \`LF\` to \`CRLF\`.
  229. Doing so produces a large \`git diff\` and thus makes the line-by-line history for a file (\`git blame\`) harder to explore.
  230. If you want to make sure that your entire git repository only contains Linux-style line endings in files covered by Prettier:
  231. 1. Ensure Prettier’s \`endOfLine\` option is set to \`lf\` (this is a default value since v2.0.0)
  232. 1. Configure [a pre-commit hook](precommit.md) that will run Prettier
  233. 1. Configure Prettier to run in your CI pipeline using [\`--check\` flag](cli.md#--check). If you use Travis CI, set [the \`autocrlf\` option](https://docs.travis-ci.com/user/customizing-the-build#git-end-of-line-conversion-control) to \`input\` in \`.travis.yml\`.
  234. 1. Add \`* text=auto eol=lf\` to the repo's \`.gitattributes\` file.
  235. You may need to ask Windows users to re-clone your repo after this change to ensure git has not converted \`LF\` to \`CRLF\` on checkout.
  236. All modern text editors in all operating systems are able to correctly display line endings when \`\\n\` (\`LF\`) is used.
  237. However, old versions of Notepad for Windows will visually squash such lines into one as they can only deal with \`\\r\\n\` (\`CRLF\`).
  238. Valid options:
  239. - \`"lf"\` – Line Feed only (\`\\n\`), common on Linux and macOS as well as inside git repos
  240. - \`"crlf"\` - Carriage Return + Line Feed characters (\`\\r\\n\`), common on Windows
  241. - \`"cr"\` - Carriage Return character only (\`\\r\`), used very rarely
  242. - \`"auto"\` - Maintain existing line endings
  243. (mixed values within one file are normalised by looking at what's used after the first line)
  244. | Default | CLI Override | API Override |
  245. | ------- | ----------------------------------------------------------- | ---------------------------------------------------------- |
  246. | \`"lf"\` | <code>--end-of-line <lf&#124;crlf&#124;cr&#124;auto></code> | <code>endOfLine: "<lf&#124;crlf&#124;cr&#124;auto>"</code> |
  247. ## Embedded Language Formatting
  248. _First available in v2.1.0_
  249. Control whether Prettier formats quoted code embedded in the file.
  250. When Prettier identifies cases where it looks like you've placed some code it knows how to format within a string in another file, like in a tagged template in JavaScript with a tag named \`html\` or in code blocks in Markdown, it will by default try to format that code.
  251. Sometimes this behavior is undesirable, particularly in cases where you might not have intended the string to be interpreted as code. This option allows you to switch between the default behavior (\`auto\`) and disabling this feature entirely (\`off\`).
  252. Valid options:
  253. - \`"auto"\` – Format embedded code if Prettier can automatically identify it.
  254. - \`"off"\` - Never automatically format embedded code.
  255. | Default | CLI Override | API Override |
  256. | -------- | ------------------------------------ | ----------------------------------- |
  257. | \`"auto"\` | \`--embedded-language-formatting=off\` | \`embeddedLanguageFormatting: "off"\` |
  258. `;
  259. export default md;