Skip to content
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.

Sign up for GitHub

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

Try out standard indentation #57

Merged
merged 12 commits into from
Jun 1, 2023
Merged

Try out standard indentation #57

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
57ef8c1
Try out standard indentation
jgerigmeyer May 30, 2023
d8eec31
Strip indentation from more paired shortcodes.
jgerigmeyer May 31, 2023
a46eb6b
indentation for breaking-changes
jgerigmeyer May 31, 2023
fdcb4e4
indentation for cli docs
jgerigmeyer May 31, 2023
c146c76
indentation for style-rules docs
jgerigmeyer May 31, 2023
5bead6b
indentation for syntax docs
jgerigmeyer May 31, 2023
2646cc0
indentation for remainder of docs
jgerigmeyer May 31, 2023
3b97839
combine more markdown blocks
jgerigmeyer May 31, 2023
9f62b1d
Do not autoformat md files
jgerigmeyer May 31, 2023
d546a85
silence sass warnings
jgerigmeyer May 31, 2023
a331c72
add missing @use
jgerigmeyer May 31, 2023
b1dcf05
clearer example line breaks
jgerigmeyer May 31, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion source/documentation/at-rules/css.liquid
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ table_of_contents: true

{{ '## `@media`' | markdown }}

{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, `useMarkdown` boolean, additional details within %}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unrelated, but what do you think about changing {% compatibility %} to accept string arguments instead, and parse them in the TS implementation into a proper object:

{% compatibility 'dart:"1.11.0"', 'libsass:false', 'ruby:false', 'feature:"Range Syntax"', 'useMarkdown:false' %}

Advantages:

  • We can get rid of the comment before each invocation
  • No need to specify null for unused arguments, not including them should be enough
  • If 11ty lands support for kwargs, we can migrate to them with a regex that removes the single quotes

Copy link
Member Author

@jgerigmeyer jgerigmeyer May 31, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I love it! I'll try that out in this another PR.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Implemented in #59.

{% compatibility '1.11.0', false, null, '3.7.0', 'Range Syntax', false %}
{% markdown %}
LibSass and older versions of Dart Sass and Ruby Sass don't support media
Expand Down
78 changes: 39 additions & 39 deletions source/documentation/breaking-changes/bogus-combinators.liquid
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,62 +7,62 @@ introduction: >
---

{% markdown %}
Sass has historically supported three invalid uses of combinators:
Sass has historically supported three invalid uses of combinators:

* Leading combinators, as in `+ .error {color: red}`.
* Leading combinators, as in `+ .error {color: red}`.

* Trailing combinators, as in `.error + {color: red}`.
* Trailing combinators, as in `.error + {color: red}`.

* Repeated combinators, as in `div > > .error {color: red}`.
* Repeated combinators, as in `div > > .error {color: red}`.

None of these are valid CSS, and all of them will cause browsers to ignore the
style rule in question. Supporting them added a substantial amount of complexity
to Sass's implementation, and made it particularly difficult to fix various bugs
related to the `@extend` rule. As such, we [made the decision] to remove support
for these uses.
None of these are valid CSS, and all of them will cause browsers to ignore the
style rule in question. Supporting them added a substantial amount of
complexity to Sass's implementation, and made it particularly difficult to fix
various bugs related to the `@extend` rule. As such, we [made the decision] to
remove support for these uses.

[made the decision]: https://github.com/sass/sass/issues/3340
[made the decision]: https://github.com/sass/sass/issues/3340

**There is one major exception**: leading and trailing combinators may still be
used for nesting purposes. For example, the following is still very much
supported:
**There is one major exception**: leading and trailing combinators may still
be used for nesting purposes. For example, the following is still very much
supported:
{% endmarkdown %}

{% codeExample 'bogus-combinators' %}
.sidebar > {
.error {
color: red;
.sidebar > {
.error {
color: red;
}
}
}
===
.sidebar >
.error
color: red
===
.sidebar >
.error
color: red
{% endcodeExample %}

{% markdown %}
Sass will only produce an error if a selector still has a leading or trailing
combinator _after nesting is resolved_. Repeated combinators, on the other hand,
will always be errors.
Sass will only produce an error if a selector still has a leading or trailing
combinator _after nesting is resolved_. Repeated combinators, on the other
hand, will always be errors.

To make sure existing stylesheets who (likely accidentally) contain invalid
combinators, we'll support a transition period until the next major release of
Dart Sass.
To make sure existing stylesheets who (likely accidentally) contain invalid
combinators, we'll support a transition period until the next major release of
Dart Sass.

## Transition Period
## Transition Period

{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
{% compatibility '1.54.0', false, null, false %}{% endcompatibility %}
{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
{% compatibility '1.54.0', false, null, false %}{% endcompatibility %}

First, we'll emit deprecation warnings for all double combinators, as well as
leading or trailing combinators that end up in selectors after nesting is
resolved.
First, we'll emit deprecation warnings for all double combinators, as well as
leading or trailing combinators that end up in selectors after nesting is
resolved.

{% render 'documentation/snippets/silence-deprecations' %}
{% render 'documentation/snippets/silence-deprecations' %}

In addition, we'll immediately start omitting selectors that we know to be
invalid CSS from the compiled CSS, with one exception: we _won't_ omit selectors
that begin with a leading combinator, since they may be used from a nested
`@import` rule or `meta.load-css()` mixin. However, we don't encourage this
pattern and will drop support for it in Dart Sass 2.0.0.
In addition, we'll immediately start omitting selectors that we know to be
invalid CSS from the compiled CSS, with one exception: we _won't_ omit
selectors that begin with a leading combinator, since they may be used from a
nested `@import` rule or `meta.load-css()` mixin. However, we don't encourage
this pattern and will drop support for it in Dart Sass 2.0.0.
{% endmarkdown %}
161 changes: 81 additions & 80 deletions source/documentation/breaking-changes/css-vars.liquid
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,95 +11,96 @@ introduction: >
{% compatibility true, '3.5.0', null, '3.5.0' %}{% endcompatibility %}

{% markdown %}
The CSS spec allows almost any string of characters to be used in a custom
property declaration. Even though these values might not be meaningful for any
CSS property, they could be accessed from JavaScript. When they were parsed as
SassScript values, syntax that would have been valid plain CSS failed to parse.
For example, the [Polymer library][] used this to support plain-CSS mixins:

[Polymer library]: https://polymer-library.polymer-project.org/3.0/docs/devguide/custom-css-properties#use-custom-css-mixins
The CSS spec allows almost any string of characters to be used in a custom
property declaration. Even though these values might not be meaningful for any
CSS property, they could be accessed from JavaScript. When they were parsed as
SassScript values, syntax that would have been valid plain CSS failed to
parse. For example, the [Polymer library][] used this to support plain-CSS
mixins:

[Polymer library]: https://polymer-library.polymer-project.org/3.0/docs/devguide/custom-css-properties#use-custom-css-mixins
{% endmarkdown %}

{% codeExample 'css-vars', true, 'scss' %}
:root {
--flex-theme: {
border: 1px solid var(--theme-dark-blue);
font-family: var(--theme-font-family);
padding: var(--theme-wide-padding);
background-color: var(--theme-light-blue);
};
}
===
:root {
--flex-theme: {
border: 1px solid var(--theme-dark-blue);
font-family: var(--theme-font-family);
padding: var(--theme-wide-padding);
background-color: var(--theme-light-blue);
};
}
{% codeExample 'css-vars', false, 'scss' %}
:root {
--flex-theme: {
border: 1px solid var(--theme-dark-blue);
font-family: var(--theme-font-family);
padding: var(--theme-wide-padding);
background-color: var(--theme-light-blue);
};
}
===
:root {
--flex-theme: {
border: 1px solid var(--theme-dark-blue);
font-family: var(--theme-font-family);
padding: var(--theme-wide-padding);
background-color: var(--theme-light-blue);
};
}
{% endcodeExample %}

{% markdown %}
To provide maximum compatibility with plain CSS, more recent versions of Sass
require SassScript expressions in custom property values to be written within
[interpolation](/documentation/interpolation). Interpolation will also work for
older Sass versions, and so is recommended for all stylesheets.
To provide maximum compatibility with plain CSS, more recent versions of Sass
require SassScript expressions in custom property values to be written within
[interpolation](/documentation/interpolation). Interpolation will also work
for older Sass versions, and so is recommended for all stylesheets.
{% endmarkdown %}

{% codeExample 'css-vars-interpolation' %}
$accent-color: #fbbc04;

:root {
// WRONG, will not work in recent Sass versions.
--accent-color-wrong: $accent-color;

// RIGHT, will work in all Sass versions.
--accent-color-right: #{$accent-color};
}
===
$accent-color: #fbbc04

:root
// WRONG, will not work in recent Sass versions.
--accent-color-wrong: $accent-color

// RIGHT, will work in all Sass versions.
--accent-color-right: #{$accent-color}
===
:root {
--accent-color-wrong: $accent-color;
--accent-color-right: #fbbc04;
}
$accent-color: #fbbc04;

:root {
// WRONG, will not work in recent Sass versions.
--accent-color-wrong: $accent-color;

// RIGHT, will work in all Sass versions.
--accent-color-right: #{$accent-color};
}
===
$accent-color: #fbbc04

:root
// WRONG, will not work in recent Sass versions.
--accent-color-wrong: $accent-color

// RIGHT, will work in all Sass versions.
--accent-color-right: #{$accent-color}
===
:root {
--accent-color-wrong: $accent-color;
--accent-color-right: #fbbc04;
}
{% endcodeExample %}

{% headsUp false %}
{% markdown %}
Because interpolation removes quotation marks from quoted strings, it may be
necessary to wrap them in the [`meta.inspect()` function][] to preserve their
quotes.

[`meta.inspect()` function]: /documentation/modules/meta#inspect
{% endmarkdown %}

{% codeExample 'css-vars-heads-up' %}
@use "sass:meta";

$font-family-monospace: Menlo, Consolas, "Courier New", monospace;

:root {
--font-family-monospace: #{meta.inspect($font-family-monospace)};
}
===
@use "sass:meta"

$font-family-monospace: Menlo, Consolas, "Courier New", monospace

:root
--font-family-monospace: #{meta.inspect($font-family-monospace)}
===
:root {
--font-family-monospace: Menlo, Consolas, "Courier New", monospace;
}
{% endcodeExample %}
{% markdown %}
Because interpolation removes quotation marks from quoted strings, it may be
necessary to wrap them in the [`meta.inspect()` function][] to preserve
their quotes.

[`meta.inspect()` function]: /documentation/modules/meta#inspect
{% endmarkdown %}

{% codeExample 'css-vars-heads-up' %}
@use "sass:meta";

$font-family-monospace: Menlo, Consolas, "Courier New", monospace;

:root {
--font-family-monospace: #{meta.inspect($font-family-monospace)};
}
===
@use "sass:meta"

$font-family-monospace: Menlo, Consolas, "Courier New", monospace

:root
--font-family-monospace: #{meta.inspect($font-family-monospace)}
===
:root {
--font-family-monospace: Menlo, Consolas, "Courier New", monospace;
}
{% endcodeExample %}
{% endheadsUp %}
Loading