Permalink
Browse files

Prepare docs for #2067 (#2127)

* Remove support for trailing spaces in markdown files

* Move benchmarks doc to "working with rules" and tweak copy

* Tweak order of user guide items for better grouping

* Patch links in FAQ

* Add link to about rules from rules

Closes #2066

* Update link to benchmark section

* Plugin copy tweaks and more linkable headers

* Comp tools copy tweaks

* Use relative URLs with docs

* Add remark-validate-links
  • Loading branch information...
1 parent 3a48050 commit ab20f8cefeec71e729c6500e7110ae8967d2bbb9 @jeddy3 jeddy3 committed on GitHub Nov 27, 2016
View
@@ -8,6 +8,3 @@ indent_size = 2
indent_style = space
insert_final_newline = true
trim_trailing_whitespace = true
-
-[*.md]
-trim_trailing_whitespace = false
View
@@ -38,7 +38,7 @@ With stylelint, it's easy to start linting your CSS:
- To extend a shared config, we recommend using [`stylelint-config-standard`](https://github.com/stylelint/stylelint-config-standard). It includes over 80 of stylelint's rules with sensible defaults. (You can always override specific rules after extending the config.) We update the config with each new release of stylelint. Alternately, you can [search for](https://www.npmjs.com/browse/keyword/stylelint-config) a community config and [extend](/docs/user-guide/configuration.md#extends) that instead.
- To craft your own config, first [learn about how rules are named and how they work together](/docs/user-guide/about-rules.md), then either:
- Start small and only learn about [the rules](/docs/user-guide/rules.md) you want to turn on and enforce. *All of the rules are off by default*, and so you can start small, growing your config over time as you have a chance to explore more of the rules.
- - Or copy-paste [this example configuration](/docs/user-guide/example-config.md), which lists all of stylelint's rules and their primary options. Then you can edit the options of each rule to your liking, and remove (or turn off with `null`) the rules that you don't care to enforce.
+ - Or copy-paste [this example configuration](docs/user-guide/example-config.md), which lists all of stylelint's rules and their primary options. Then you can edit the options of each rule to your liking, and remove (or turn off with `null`) the rules that you don't care to enforce.
3. Lint!
## Guides
@@ -64,7 +64,7 @@ There is always a lot of work to do, and already well over 150 rules to maintain
- Create, enhance, and debug rules (see our guide to ["Working on rules"](docs/developer-guide/rules.md)).
- Improve [documentation](docs/).
- Add new tests to *absolutely anything*.
-- Work on [improving performance of rules](docs/developer-guide/benchmarks.md).
+- Work on [improving performance of rules](docs/developer-guide/rules.md#improving-the-performance-of-new-and-existing-rules).
- Open new issues about your ideas for making stylelint better, and pull requests to show us how your idea works.
- Create or contribute to ecosystem tools, like the plugins for [Atom](https://github.com/AtomLinter/linter-stylelint) and [Sublime Text](https://github.com/kungfusheep/SublimeLinter-contrib-stylelint).
@@ -1,8 +1,7 @@
# Developer guide
-- [Rules](/docs/developer-guide/rules.md): Working on stylelint's rules.
-- [Plugins](/docs/developer-guide/plugins.md): Writing your own plugins.
-- [Processors](/docs/developer-guide/processors.md): Writing your own processors.
-- [Formatters](/docs/developer-guide/formatters.md): Writing your own formatters.
-- [Rule testers](/docs/developer-guide/rule-testers.md): Using and writing rule testers.
-- [Benchmarks](/docs/developer-guide/benchmarks.md): Running benchmarks on rules.
+- [Rules](developer-guide/rules.md): Working on stylelint's rules.
+- [Plugins](developer-guide/plugins.md): Writing your own plugins.
+- [Processors](developer-guide/processors.md): Writing your own processors.
+- [Formatters](developer-guide/formatters.md): Writing your own formatters.
+- [Rule testers](developer-guide/rule-testers.md): Using and writing rule testers.
@@ -1,43 +0,0 @@
-# Benchmarks
-
-There's a simple way to run benchmarks on any given rule with any valid config for it:
-
-```shell
-npm run benchmark-rule -- [rule-name] [config]
-```
-
-If the `config` argument is anything other than a string or a boolean, it must be valid JSON wrapped in quotation marks.
-
-```shell
-npm run benchmark-rule -- selector-combinator-space-after never
-```
-
-```shell
-npm run benchmark-rule -- selector-combinator-space-after always
-```
-
-```shell
-npm run benchmark-rule -- selector-no-combinator true
-```
-
-```shell
-npm run benchmark-rule -- block-opening-brace-space-before "[\"always\", {\"ignoreAtRules\": [\"else\"]}]"
-```
-
-The script loads Bootstrap's CSS (from its CDN) and runs it through the configured rule.
-
-It will end up printing some simple stats like this:
-
-```shell
-Warnings: 1441
-Mean: 74.17598357142856 ms
-Deviation: 16.63969674310928 ms
-```
-
-What can you do with this? **When writing new rules or refactoring existing rules, use these measurements to determine the efficiency of your code.**
-
-A stylelint rule can repeat it's core logic many, many times (e.g. checking every value node of every declaration in a vast CSS codebase). So it's worth paying attention to performance and doing what we can to improve it!
-
-**This is a great way to contribute if you just want a quick little project.** Try picking a rule and seeing if there's anything you can do to speed it up.
-
-Make sure to include benchmark measurements in your PR's!
@@ -1,48 +1,50 @@
# Writing plugins
-Plugins are rules and sets of rules built by the community. We recommend adhering to stylelint's [conventions for writing rules](/docs/developer-guide/rules.md#come-up-with-a-name), including conventions for names, options, messages, tests and docs. These will help create a consistent user experience.
+Plugins are rules and sets of rules built by the community.
+
+We recommend familiarising yourself and adhering to stylelint's [conventions for writing rules](rules.md), including those for names, options, messages, tests and docs.
## The anatomy of a plugin
```js
// Abbreviated example
var stylelint = require("stylelint")
-var ruleName = "plugin/foobar"
-
-stylelint.utils.ruleMessages(ruleName, {
+var ruleName = "plugin/foo-bar"
+var messages = stylelint.utils.ruleMessages(ruleName, {
expected: "Expected ...",
})
-var myPluginRule = stylelint.createPlugin(ruleName, function(primaryOption, secondaryOptionObject) {
+module.exports = stylelint.createPlugin(ruleName, function(primaryOption, secondaryOptionObject) {
return function(postcssRoot, postcssResult) {
var validOptions = stylelint.utils.validateOptions(postcssResult, ruleName, { .. })
if (!validOptions) { return }
// ... some logic ...
stylelint.utils.report({ .. })
}
})
+
+module.exports.ruleName = ruleName
+module.exports.messages = messages
```
Your plugin's rule name must be namespaced, e.g. `your-namespace/your-rule-name`. If your plugin provides only a single rule or you can't think of a good namespace, you can simply use `plugin/my-rule`. This namespace ensures that plugin rules will never clash with core rules. *Make sure you document your plugin's rule name (and namespace) for users, because they will need to use it in their config.*
`stylelint.createPlugin(ruleName, ruleFunction)` ensures that your plugin will be setup properly alongside other rules.
-In order for your plugin rule to work with the standard configuration format, (e.g. `["tab", { hierarchicalSelectors: true }]`), `ruleFunction` should accept 2 arguments: the primary option (e.g. `"tab"`) and, optionally, an secondary options object (e.g. `{ hierarchicalSelectors: true }`).
+In order for your plugin rule to work with the [standard configuration format](../user-guide/configuration.md#rules), `ruleFunction` should accept 2 arguments: the primary option and, optionally, an secondary options object.
-`ruleFunction` should return a function that is essentially a little PostCSS plugin: it takes 2 arguments: the PostCSS Root (the parsed AST), and the PostCSS LazyResult. You'll have to [learn about the PostCSS API](https://github.com/postcss/postcss/blob/master/docs/api.md).
+`ruleFunction` should return a function that is essentially a little [PostCSS plugin](https://github.com/postcss/postcss/blob/master/docs/writing-a-plugin.md): it takes 2 arguments: the PostCSS Root (the parsed AST), and the PostCSS LazyResult. You'll have to [learn about the PostCSS API](https://github.com/postcss/postcss/blob/master/docs/api.md).
## `stylelint.utils`
-A few of stylelint's internal utilities are exposed publicly in `stylelint.utils`, to help you write plugin rules. For details about the APIs of these functions, please look at comments in the source code and examples in the standard rules.
-
-You will want to use:
+Three of stylelint's internal utilities are exposed publicly in `stylelint.utils` and should be used:
- `report`: Report your linting warnings. *Do not use `node.warn()` directly.* If you use `report`, your plugin will respect disabled ranges and other possible future features of stylelint, so it will fit in better with the standard rules.
- `ruleMessages`: Tailor your messages to look like the messages of other stylelint rules.
- `validateOptions`: Help your user's out by checking that the options they've submitted are valid.
-**`stylelint.util.styleSearch` is deprecated and will be removed in v7. Use the external module [style-search](https://github.com/davidtheclark/style-search) instead.**
+For details about the APIs of these functions, please look at comments in the source code and examples in the standard rules.
## `stylelint.rules`
@@ -66,11 +68,11 @@ export default stylelint.createPlugin(ruleName, function (expectation) {
## Allow primary option arrays
-If your plugin can accept an array as its primary option, you must designate this by setting the property `primaryOptionArray = true` on your rule function. For more information, check out the ["Working on rules"](/docs/developer-guide/rules.md#primary) doc.
+If your plugin can accept an array as its primary option, you must designate this by setting the property `primaryOptionArray = true` on your rule function. For more information, check out the ["Working on rules"](rules.md#primary) doc.
## External helper modules
-In addition to the standard parsers mentioned in the ["Working on rules"](/docs/developer-guide/rules.md) doc, there are other external modules used within stylelint that we recommend using. These include:
+In addition to the standard parsers mentioned in the ["Working on rules"](rules.md) doc, there are other external modules used within stylelint that we recommend using. These include:
- [normalize-selector](https://github.com/getify/normalize-selector): Normalize CSS selectors.
- [postcss-resolve-nested-selector](https://github.com/davidtheclark/postcss-resolve-nested-selector): Given a (nested) selector in a PostCSS AST, return an array of resolved selectors.
@@ -89,4 +91,4 @@ To make a single module provide multiple rules, simply export an array of plugin
## Sharing plugins and plugin packs
- Use the `stylelint-plugin` keyword within your `package.json`.
-- Once your plugin is published, please send us a Pull Request to add your plugin to [the list](/docs/user-guide/plugins.md).
+- Once your plugin is published, please send us a Pull Request to add your plugin to [the list](../user-guide/plugins.md).
@@ -36,4 +36,4 @@ Processors can enable stylelint to lint the CSS within non-stylesheet files. For
## Sharing processors
- Use the `stylelint-processor` keyword within your `package.json`.
-- Once your processor is published, please send us a Pull Request to add your processor to [the list](/docs/user-guide/processors.md).
+- Once your processor is published, please send us a Pull Request to add your processor to [the list](../user-guide/processors.md).
Oops, something went wrong.

0 comments on commit ab20f8c

Please sign in to comment.