create-docusaurus 0.0.0-4378 → 0.0.0-4388

package/templates/facebook/node_modules/stylelint/docs/user-guide/usage/node-api.md

@@ -0,0 +1,169 @@
+# Node.js API
+
+The stylelint module includes a `lint()` function that provides the Node.js API.
+
+```js
+stylelint.lint(options).then(function (resultObject) {
+  /* .. */
+});
+```
+
+## Options
+
+In addition to the [standard options](options.md), the Node API accepts:
+
+### `config`
+
+A [configuration object](../configure.md).
+
+stylelint does not bother looking for a `.stylelintrc` file if you use this option.
+
+### `configOverrides`
+
+A partial stylelint configuration object whose properties override the existing config object, whether stylelint loads the config via the `config` option or a `.stylelintrc` file.
+
+### `code`
+
+A string to lint.
+
+### `files`
+
+A file glob, or array of [file globs](https://github.com/sindresorhus/globby).
+
+Relative globs are considered relative to `globbyOptions.cwd`.
+
+Though both `files` and `code` are "optional", you _must_ have one and _cannot_ have both.
+
+### `globbyOptions`
+
+The options that are passed with `files`.
+
+For example, you can set a specific `cwd` manually. Relative globs in `files` are considered relative to this path. And by default, `cwd` will be set by `process.cwd()`.
+
+For more detail usage, see [Globby Guide](https://github.com/sindresorhus/globby#options).
+
+## The returned promise
+
+`stylelint.lint()` returns a Promise that resolves with an object containing the following properties:
+
+### `errored`
+
+Boolean. If `true`, at least one rule with an "error"-level severity registered a violation.
+
+### `output`
+
+A string displaying the formatted violations (using the default formatter or whichever you passed).
+
+### `postcssResults`
+
+An array containing all the accumulated [PostCSS LazyResults](https://api.postcss.org/LazyResult.html).
+
+### `results`
+
+An array containing all the stylelint result objects (the objects that formatters consume).
+
+### `maxWarningsExceeded`
+
+An object containing the maximum number of warnings and the amount found, e.g. `{ maxWarnings: 0, foundWarnings: 12 }`.
+
+## Syntax errors
+
+`stylelint.lint()` does not reject the Promise when your CSS contains syntax errors.
+It resolves with an object (see [The returned promise](#the-returned-promise)) that contains information about the syntax error.
+
+## Usage examples
+
+### Example A
+
+As `config` contains no relative paths for `extends` or `plugins`, you do not have to use `configBasedir`:
+
+```js
+stylelint
+  .lint({
+    config: { rules: "color-no-invalid-hex" },
+    files: "all/my/stylesheets/*.css"
+  })
+  .then(function (data) {
+    // do things with data.output, data.errored,
+    // and data.results
+  })
+  .catch(function (err) {
+    // do things with err e.g.
+    console.error(err.stack);
+  });
+```
+
+### Example B
+
+If `myConfig` _does_ contain relative paths for `extends` or `plugins`, you _do_ have to use `configBasedir`:
+
+```js
+stylelint
+  .lint({
+    config: myConfig,
+    configBasedir: path.join(__dirname, "configs"),
+    files: "all/my/stylesheets/*.css"
+  })
+  .then(function () {
+    /* .. */
+  });
+```
+
+### Example C
+
+Using a string instead of a file glob, and the verbose formatter instead of the default JSON:
+
+```js
+stylelint
+  .lint({
+    code: "a { color: pink; }",
+    config: myConfig,
+    formatter: "verbose"
+  })
+  .then(function () {
+    /* .. */
+  });
+```
+
+### Example D
+
+Using your own custom formatter function and parse `.scss` source files:
+
+```js
+stylelint
+  .lint({
+    config: myConfig,
+    files: "all/my/stylesheets/*.scss",
+    formatter: function (stylelintResults) {
+      /* .. */
+    }
+  })
+  .then(function () {
+    /* .. */
+  });
+```
+
+### Example E
+
+Using a custom syntax:
+
+```js
+stylelint
+  .lint({
+    config: myConfig,
+    files: "all/my/stylesheets/*.css",
+    customSyntax: {
+      parse: (css, opts) => {
+        /* .. */
+      },
+      stringify: (root, builder) => {
+        /* .. */
+      }
+    }
+  })
+  .then(function () {
+    /* .. */
+  });
+```
+
+Note that the customSyntax option also accepts a string. [Refer to the options documentation for details](./options.md).

package/templates/facebook/node_modules/stylelint/docs/user-guide/usage/options.md

@@ -0,0 +1,208 @@
+# Options
+
+Options shared by the:
+
+- [CLI](cli.md)
+- [Node.js API](node-api.md)
+- [PostCSS plugin](postcss-plugin.md)
+
+## `configFile`
+
+CLI flag: `--config`
+
+Path to a JSON, YAML, or JS file that contains your [configuration object](../configure.md).
+
+Use this option if you don't want stylelint to search for a configuration file.
+
+The path should be either absolute or relative to the directory that your process is running from (`process.cwd()`).
+
+## `configBasedir`
+
+CLI flag: `--config-basedir`
+
+Absolute path to the directory that relative paths defining "extends" and "plugins" are _relative to_. Only necessary if these values are relative paths.
+
+## `fix`
+
+CLI flag: `--fix`
+
+Automatically fix, where possible, violations reported by rules.
+
+For CSS with standard syntax, stylelint uses [postcss-safe-parser](https://github.com/postcss/postcss-safe-parser) to fix syntax errors.
+
+If a source contains a:
+
+- scoped disable comment, e.g. `/* stylelint-disable indentation */`, any violations reported by the scoped rules will not be automatically fixed anywhere in the source
+- unscoped disable comment, i.e. `/* stylelint-disable */`, the entirety of source will not be automatically fixed
+
+This limitation in being tracked in [issue #2643](https://github.com/stylelint/stylelint/issues/2643).
+
+## `formatter`
+
+CLI flags: `--formatter, -f` | `--custom-formatter`
+
+Specify the formatter to format your results.
+
+Options are:
+
+- `compact`
+- `json` (default for Node API)
+- `string` (default for CLI)
+- `tap`
+- `unix`
+- `verbose`
+
+The `formatter` Node.js API option can also accept a function, whereas the `--custom-formatter` CLI flag accepts a path to a JS file exporting one. The function in both cases must fit the signature described in the [Developer Guide](../../developer-guide/formatters.md).
+
+## `cache`
+
+CLI flag: `--cache`
+
+Store the results of processed files so that stylelint only operates on the changed ones. By default, the cache is stored in `./.stylelintcache` in `process.cwd()`.
+
+Enabling this option can dramatically improve stylelint's speed because only changed files are linted.
+
+_If you run stylelint with `cache` and then run stylelint without `cache`, stylelint deletes the `.stylelintcache` because we have to assume that that second command invalidated `.stylelintcache`._
+
+## `cacheLocation`
+
+CLI flag: `--cache-location`
+
+Path to a file or directory for the cache location.
+
+If a directory is specified, stylelint creates a cache file inside the specified folder. The name of the file is based on the hash of `process.cwd()` (e.g. `.cache_hashOfCWD`) so that stylelint can reuse a single location for a variety of caches from different projects.
+
+_If the directory of `cacheLocation` does not exist, make sure you add a trailing `/` on \*nix systems or `\` on Windows. Otherwise, stylelint assumes the path to be a file._
+
+## `maxWarnings`
+
+CLI flags: `--max-warnings, --mw`
+
+Set a limit to the number of warnings accepted.
+
+It is useful when setting [`defaultSeverity`](../configure.md#defaultseverity) to `"warning"` and expecting the process to fail on warnings (e.g. CI build).
+
+If the number of warnings exceeds this value, the:
+
+- CLI process exits with code `2`
+- Node.js API adds a [`maxWarningsExceeded`](node-api.md#maxwarningsexceeded) property to the returned data
+
+## `syntax`
+
+CLI flags: `--syntax, -s`
+
+Specify a syntax. Options:
+
+- `css`
+- `css-in-js`
+- `html`
+- `less`
+- `markdown`
+- `sass`
+- `scss`
+- `sugarss`
+
+If you do not specify a syntax, stylelint will automatically infer the syntaxes.
+
+Only use this option if you want to force a specific syntax.
+
+## `customSyntax`
+
+CLI flag: `--custom-syntax`
+
+Specify a custom syntax to use on your code. Use this option if you want to force a specific syntax that's not already built into stylelint.
+
+This option should be a string that resolves to a JS module that exports a [PostCSS-compatible syntax](https://github.com/postcss/postcss#syntaxes). The string can be a module name (like `my-module`) or a path to a JS file (like `path/to/my-module.js`).
+
+Using the Node.js API, the `customSyntax` option can also accept a [Syntax object](https://github.com/postcss/postcss/blob/abfaa7122a0f480bc5be0905df3c24a6a51a82d9/lib/postcss.d.ts#L223-L232). Stylelint treats the `parse` property as a required value.
+
+Note that stylelint can provide no guarantee that core rules work with syntaxes other than the defaults listed for the `syntax` option above.
+
+## `disableDefaultIgnores`
+
+CLI flags: `--disable-default-ignores, --di`
+
+Disable the default ignores. stylelint will not automatically ignore the contents of `node_modules`.
+
+## `ignorePath`
+
+CLI flags: `--ignore-path, -i`
+
+A path to a file containing patterns describing files to ignore. The path can be absolute or relative to `process.cwd()`. By default, stylelint looks for `.stylelintignore` in `process.cwd()`.
+
+## `ignoreDisables`
+
+CLI flags: `--ignore-disables, --id`
+
+Ignore `styleline-disable` (e.g. `/* stylelint-disable block-no-empty */`) comments.
+
+You can use this option to see what your linting results would be like without those exceptions.
+
+## `reportNeedlessDisables`
+
+CLI flags: `--report-needless-disables, --rd`
+
+Produce a report to clean up your codebase, keeping only the `stylelint-disable` comments that serve a purpose.
+
+If needless disables are found, the:
+
+- CLI process exits with code `2`
+- Node.js API adds errors to the returned data
+
+## `reportInvalidScopeDisables`
+
+CLI flags: `--report-invalid-scope-disables, --risd`
+
+Produce a report of the `stylelint-disable` comments that used for rules that don't exist within the configuration object.
+
+If invalid scope disables are found, the:
+
+- CLI process exits with code `2`
+- Node.js API adds errors to the returned data
+
+## `reportDescriptionlessDisables`
+
+CLI flags: `--report-descriptionless-disables, --rdd`
+
+Produce a report of the `stylelint-disable` comments without a description.
+
+For example, when the configuration `{ block-no-empty: true }` is given, the following patterns are reported:
+
+<!-- prettier-ignore -->
+```css
+/* stylelint-disable */
+a {}
+```
+
+<!-- prettier-ignore -->
+```css
+/* stylelint-disable-next-line block-no-empty */
+a {}
+```
+
+But, the following patterns (`stylelint-disable -- <description>`) are _not_ reported:
+
+<!-- prettier-ignore -->
+```css
+/* stylelint-disable -- This violation is ignorable. */
+a {}
+```
+
+<!-- prettier-ignore -->
+```css
+/* stylelint-disable-next-line block-no-empty -- This violation is ignorable. */
+a {}
+```
+
+If descriptionless disables are found, the:
+
+- CLI process exits with code `2`
+- Node.js API adds errors to the returned data
+
+## `codeFilename`
+
+CLI flag: `--stdin-filename`
+
+A filename to assign the input.
+
+If using `code` or `stdin` to pass a source string directly, you can use `codeFilename` to associate that code with a particular filename.

package/templates/facebook/node_modules/stylelint/docs/user-guide/usage/postcss-plugin.md

@@ -0,0 +1,84 @@
+# PostCSS plugin
+
+As with any other [PostCSS plugin](https://github.com/postcss/postcss#plugins), you can use stylelint's PostCSS plugin either with a [PostCSS runner](https://github.com/postcss/postcss#runners) or with the PostCSS JS API directly.
+
+_However, if a dedicated stylelint task runner plugin [is available](../integrations/task-runner.md) (e.g. [gulp-stylelint](https://github.com/olegskl/gulp-stylelint)) we recommend you use that rather than this plugin, as they provide better reporting._
+
+## Options
+
+The PostCSS plugin uses the [standard options](options.md), _except the `syntax` and `customSyntax` options_. Instead, the syntax must be set within the [PostCSS options](https://github.com/postcss/postcss#options) as there can only be one parser/syntax in a pipeline.
+
+## Usage examples
+
+We recommend you lint your CSS before applying any transformations. You can do this by either:
+
+- creating a separate lint task that is independent of your build one.
+- using the [`plugins` option](https://github.com/postcss/postcss-import#plugins) of [`postcss-import`](https://github.com/postcss/postcss-import) or [`postcss-easy-import`](https://github.com/TrySound/postcss-easy-import) to lint your files before any transformations.
+- placing stylelint at the beginning of your plugin pipeline.
+
+You'll also need to use a reporter. _The stylelint plugin registers warnings via PostCSS_. Therefore, you'll want to use it with a PostCSS runner that prints warnings or another PostCSS plugin whose purpose is to format and print warnings (e.g. [`postcss-reporter`](https://github.com/postcss/postcss-reporter)).
+
+### Example A
+
+A separate lint task that uses the plugin via the PostCSS JS API to lint Less using [`postcss-less`](https://github.com/shellscape/postcss-less).
+
+```js
+const fs = require("fs");
+const less = require("postcss-less");
+const postcss = require("postcss");
+
+// Code to be processed
+const code = fs.readFileSync("input.less", "utf8");
+
+postcss([
+  require("stylelint")({
+    /* your options */
+  }),
+  require("postcss-reporter")({ clearReportedMessages: true })
+])
+  .process(code, {
+    from: "input.less",
+    syntax: less
+  })
+  .then(() => {})
+  .catch((err) => console.error(err.stack));
+```
+
+The same pattern can be used to lint Less, SCSS or [SugarSS](https://github.com/postcss/sugarss) syntax.
+
+### Example B
+
+A combined lint and build task where the plugin is used via the PostCSS JS API, but within [`postcss-import`](https://github.com/postcss/postcss-import) (using the its `plugins` option) so that the source files are linted before any transformations.
+
+```js
+const fs = require("fs");
+const postcss = require("postcss");
+const stylelint = require("stylelint");
+
+// CSS to be processed
+const css = fs.readFileSync("lib/app.css", "utf8");
+
+postcss([
+  require("postcss-import")({
+    plugins: [
+      require("stylelint")({
+        /* your options */
+      })
+    ]
+  }),
+  require("postcss-preset-env"),
+  require("postcss-reporter")({ clearReportedMessages: true })
+])
+  .process(css, {
+    from: "lib/app.css",
+    to: "app.css"
+  })
+  .then((result) => {
+    fs.writeFileSync("app.css", result.css);
+
+    if (result.map) {
+      fs.writeFileSync("app.css.map", result.map);
+    }
+  })
+  .catch((err) => console.error(err.stack));
+```