-
-
Notifications
You must be signed in to change notification settings - Fork 929
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Reinstate and document workaround feature #4592
Merged
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
015fd24
Recover removed workaround code
jeddy3 51bee1a
Document workaround feature
jeddy3 f5dc23c
Add new syntaxes page to toc
jeddy3 4d90f11
Update lib/lintSource.js
jeddy3 ef83331
Update docs/developer-guide/syntaxes.md
jeddy3 91732fa
Update docs/developer-guide/syntaxes.md
jeddy3 b4fe35c
Remove link to specific lines
jeddy3 ea7553b
Remove unused imports
jeddy3 c462005
Revert formatting changes
jeddy3 File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
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 |
---|---|---|
@@ -1,19 +1,18 @@ | ||
# Syntaxes | ||
|
||
There are many styling languages, ranging from CSS language extension like SCSS to entirely different notations like CSS-in-JS objects. These styling languages can be then be embedded within other languages, including HTML `<style>` tags, markdown fences and JavaScript variables. | ||
There are many styling languages, ranging from CSS language extensions like SCSS to entirely different notations, e.g. CSS-in-JS objects. | ||
|
||
We aim to support all these use cases, but it's a complicated task. | ||
These styling languages can be embedded within other languages too. For example: | ||
|
||
We use [PostCSS syntaxes](https://github.com/postcss/postcss#syntaxes) to transform these languages into something that resembles CSS, which is the language that: | ||
- HTML `<style>` tags | ||
- markdown fences | ||
- JavaScript template literals | ||
|
||
- underpins all the other styling languages | ||
- is best understood by stylelint | ||
We aim to support all these use cases in stylelint, but it's a complicated endeavor. | ||
|
||
We lean on [PostCSS syntaxes](https://github.com/postcss/postcss#syntaxes) to help us with this task. We use them to transform these languages into something that resembles CSS, which is the language that: | ||
|
||
We need your help to [support and improve](https://github.com/postcss/postcss/blob/master/docs/syntax.md) the following PostCSS syntaxes: | ||
- underpins all the other styling languages | ||
- is best understood by rules built into stylelint | ||
|
||
- [postcss-css-in-js](https://github.com/stylelint/postcss-css-in-js) | ||
- [postcss-html](https://github.com/gucong3000/postcss-html) | ||
- [postcss-less](https://github.com/webschik/postcss-less) | ||
- [postcss-markdown](https://github.com/stylelint/postcss-markdown) | ||
- [postcss-sass](https://github.com/AleshaOleg/postcss-sass) | ||
- [postcss-scss](https://github.com/postcss/postcss-scss) | ||
If you write your styles in anything other than CSS, please consider [contributing to these syntaxes](../developer-guide/syntaxes.md) so that they can remain compatible with stylelint. |
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,35 @@ | ||
# Working on syntaxes | ||
|
||
Please help us enhance and debug the [syntaxes](../about/syntaxes.md) we use in stylelint: | ||
|
||
- [postcss-css-in-js](https://github.com/stylelint/postcss-css-in-js) | ||
- [postcss-html](https://github.com/gucong3000/postcss-html) | ||
- [postcss-less](https://github.com/webschik/postcss-less) | ||
- [postcss-markdown](https://github.com/stylelint/postcss-markdown) | ||
- [postcss-sass](https://github.com/AleshaOleg/postcss-sass) | ||
- [postcss-scss](https://github.com/postcss/postcss-scss) | ||
|
||
To contribute to a syntax, you should: | ||
|
||
1. Familiarize yourself with PostCSS's [how to write custom syntax](https://github.com/postcss/postcss/blob/master/docs/syntax.md) guide. | ||
2. Use the [`syntax: *` labels](https://github.com/stylelint/stylelint/labels?utf8=%E2%9C%93&q=syntax%3A) to identify which syntax is behind an issue. | ||
3. Go to the repository for that syntax. | ||
4. Read their contributing guidelines. | ||
|
||
## Workarounds | ||
|
||
Fixing bugs in syntaxes can take time. stylelint can work around these bug by turning off autofix for incompatible sources. Autofix can then remain safe to use while contributors try to fix the underlying issue. | ||
|
||
### Current workarounds | ||
|
||
stylelint currently turns off autofix for sources that contain: | ||
|
||
- nested tagged template literals ([issue #4119](https://github.com/stylelint/stylelint/issues/4119)) | ||
|
||
### Add a workaround | ||
|
||
To add a new workaround, you should: | ||
|
||
1. Add code to [`lib/lintSource.js`](https://github.com/stylelint/stylelint/blob/master/lib/lintSource.js) to detect the incompatible pattern. | ||
2. Add a corresponding test to [`system-tests/fix/fix.test.js`](https://github.com/stylelint/stylelint/blob/master/system-tests/fix/fix.test.js). | ||
3. Document the workaround in [`docs/developer-guides/syntaxes.md`](https://github.com/stylelint/stylelint/blob/master/docs/developer-guide/syntaxes.md). |
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
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
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,12 @@ | ||
import * as postcss from 'postcss'; | ||
declare module 'postcss' { | ||
|
||
interface NodeSource { | ||
lang?: string; | ||
|
||
} | ||
|
||
interface Input { | ||
css?: string; | ||
} | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [note] This |
||
} |
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
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[note] This
lang
property seems an extension bypostcss-syntax
. I cannot find it in the PostCSS core repository.https://github.com/gucong3000/postcss-syntax/blob/0bca5a408f12891a622fd6149d8f23d3bd98df86/syntax.js#L17
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do you know what the best way of handling this is?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No, I'm not sure now. 😣
This solution seems best for us now.