From a53f2fd14e602ebff2f998423455aed9bcaf1581 Mon Sep 17 00:00:00 2001 From: Ed Rivas Date: Tue, 23 May 2023 23:48:36 +0000 Subject: [PATCH 1/9] Add custom slugify function --- source/helpers/engines.ts | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/source/helpers/engines.ts b/source/helpers/engines.ts index 78d2eda..6b6235d 100644 --- a/source/helpers/engines.ts +++ b/source/helpers/engines.ts @@ -7,12 +7,25 @@ import path from 'path'; import { renderPermalink } from './components/anchors'; +/** + * Identical to `markdown-it-anchor`'s default slugify function, but removes + * leading dashes to match the behavior of the old Ruby site. + * @see https://github.com/valeriangalliat/markdown-it-anchor/blob/649582d58185b00cfb2ceee9b6b4cd6aafc645b7/index.js#L3 + */ +function slugify(s: string): string { + const slug = encodeURIComponent( + String(s).trim().toLowerCase().replace(/\s+/g, '-'), + ); + return slug.replace(/^-+/, ''); +} + /** * Returns Markdown engine with custom configuration and plugins. * * @see https://github.com/markdown-it/markdown-it * @see https://github.com/markdown-it/markdown-it-deflist * @see https://github.com/arve0/markdown-it-attrs + * @see https://github.com/valeriangalliat/markdown-it-anchor */ export const markdownEngine = markdown({ html: true, @@ -23,6 +36,7 @@ export const markdownEngine = markdown({ .use(markdownAnchor, { level: 2, permalink: renderPermalink, + slugify, }); /** From 6f34fb304aa77d57e74534e970905192bcdf3775 Mon Sep 17 00:00:00 2001 From: Ed Rivas Date: Tue, 23 May 2023 23:50:18 +0000 Subject: [PATCH 2/9] Remove extra white space from compatibility tag --- source/_includes/compatibility.liquid | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/source/_includes/compatibility.liquid b/source/_includes/compatibility.liquid index 45e6cde..982ff39 100644 --- a/source/_includes/compatibility.liquid +++ b/source/_includes/compatibility.liquid @@ -2,40 +2,40 @@
Compatibility{% if feature %} ({{ feature }}){% endif %}:
- {% if dart != null %} + {%- if dart != null -%}
Dart Sass
{{ dart | implStatus }}
- {% endif %} - {% if libsass != null %} + {%- endif -%} + {%- if libsass != null -%}
LibSass
{{ libsass | implStatus }}
- {% endif %} - {% if node != null %} + {%- endif -%} + {%- if node != null -%}
Node Sass
{{ node | implStatus }}
- {% endif %} - {% if ruby != null %} + {%- endif -%} + {%- if ruby != null -%}
Ruby Sass
{{ ruby | implStatus }}
- {% endif %} - {% if details | strip %} + {%- endif -%} + {%- if details | strip -%}
{% # The no-op href here ensures that this toggle is focusable in browsers. %} β–Ά
- {% endif %} + {%- endif -%} -{% if details | strip %} +{%- if details | strip -%}
{{ details | markdown }}
-{% endif %} +{%- endif -%} From f24d6c74581be09bef7a3f53b1a964cb61153120 Mon Sep 17 00:00:00 2001 From: Ed Rivas Date: Tue, 23 May 2023 23:50:31 +0000 Subject: [PATCH 3/9] Port cli/dart-sass --- source/documentation/cli/dart-sass.liquid | 626 ++++++++++++++++++ source/documentation/cli/index.md | 13 + .../documentation/snippets/source-maps.liquid | 7 + 3 files changed, 646 insertions(+) create mode 100644 source/documentation/cli/dart-sass.liquid create mode 100644 source/documentation/cli/index.md create mode 100644 source/documentation/snippets/source-maps.liquid diff --git a/source/documentation/cli/dart-sass.liquid b/source/documentation/cli/dart-sass.liquid new file mode 100644 index 0000000..e3810f5 --- /dev/null +++ b/source/documentation/cli/dart-sass.liquid @@ -0,0 +1,626 @@ +--- +title: Dart Sass Command-Line Interface +table_of_contents: true +complementary_content: | + +--- + +{% markdown %} +## Usage + +The Dart Sass executable can be invoked in one of two modes. + +### One-to-One Mode + +``` +sass [output.css] +``` + +One-to-one mode compiles a single input file (`input.scss`) to a single output +location (`output.css`). If no output location is passed, the compiled CSS is +printed to the terminal. + +The input file is parsed as [SCSS][] if its extension is `.scss`, as the +[indented syntax][] if its extension is `.sass`, or as [plain CSS][] if its +extension is `.css`. If it doesn't have one of these three extensions, or if it +comes from standard input, it's parsed as SCSS by default. This can be +controlled with the [`--indented` flag][]. + +[SCSS]: /documentation/syntax#scss +[indented syntax]: /documentation/syntax#the-indented-syntax +[plain CSS]: /documentation/at-rules/import#importing-css +[`--indented` flag]: #indented + +The special string `-` can be passed in place of the input file to tell Sass to +read the input file from [standard input][]. Sass will default to parsing it as +SCSS unless the [`--indented` flag][] is passed. + +[standard input]: https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin) + +### Many-to-many Mode + +{% compatibility '1.4.0' %}{% endcompatibility %} + +``` +sass [:] [:]... +``` + +Many-to-many mode compiles one or more input files to one or more output files. +The inputs are separated from the outputs with colons. It can also compile all +Sass files in a directory to CSS files with the same names in another directory. + +```shellsession +​# Compiles style.scss to style.css. +$ sass style.scss:style.css + +​# Compiles light.scss and dark.scss to light.css and dark.css. +$ sass light.scss:light.css dark.scss:dark.css + +​# Compiles all Sass files in themes/ to CSS files in public/css/. +$ sass themes:public/css +``` + +When compiling whole directories, Sass will ignore [partial files][] whose names +begin with `_`. You can use partials to separate out your stylesheets without +creating a bunch of unnecessary output files. + +[partial files]: /documentation/at-rules/import#partials + +## Options + +### Input and Output + +These options control how Sass loads its input files and how it produces output +files. + +#### `--stdin` + +This flag is an alternative way of telling Sass that it should read its input +file from [standard input][]. When it's passed, no input file may be passed. + +```shellsession +$ echo "h1 {font-size: 40px}" | sass --stdin h1.css +$ echo "h1 {font-size: 40px}" | sass --stdin +h1 { + font-size: 40px; +} +``` + +The `--stdin` flag may not be used with [many-to-many mode][]. + +[many-to-many mode]: #many-to-many-mode + +#### `--indented` + +This flag tells Sass to parse the input file as the [indented syntax][]. If it's +used in [many-to-many mode][], all input files are parsed as the indented +syntax, although files they [use][] will have their syntax determined as usual. +The inverse, `--no-indented`, can be used to force all input files to be parsed +as [SCSS][] instead. + +[use]: /documentation/at-rules/use + +The `--indented` flag is mostly useful when the input file is coming from +[standard input][], so its syntax can't be automatically determined. + +```shellsession +$ echo -e 'h1\n font-size: 40px' | sass --indented - +h1 { + font-size: 40px; +} +``` + +#### `--load-path` + +This option (abbreviated `-I`) adds an additional [load path][] for Sass to look +for stylesheets. It can be passed multiple times to provide multiple load paths. +Earlier load paths will take precedence over later ones. + +[load path]: /documentation/at-rules/use#load-paths + +```shellsession +$ sass --load-path=node_modules/bootstrap/dist/css style.scss style.css +``` + +#### `--style` + +This option (abbreviated `-s`) controls the output style of the resulting CSS. +Dart Sass supports two output styles: + +- `expanded` (the default) writes each selector and declaration on its own line. +- `compressed` removes as many extra characters as possible, and writes the + entire stylesheet on a single line. + +```shellsession +$ sass --style=expanded style.scss +h1 { + font-size: 40px; +} + +$ sass --style=compressed style.scss +h1{font-size:40px} +``` + +#### `--no-charset` + +{% compatibility '1.19.0' %}{% endcompatibility %} + +This flag tells Sass never to emit a `@charset` declaration or a UTF-8 +[byte-order mark][]. By default, or if `--charset` is passed, Sass will insert +either a `@charset` declaration (in expanded output mode) or a byte-order mark +(in compressed output mode) if the stylesheet contains any non-ASCII characters. + +[byte-order mark]: https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8 + +```shellsession +$ echo 'h1::before {content: "πŸ‘­"}' | sass --no-charset +h1::before { + content: "πŸ‘­"; +} + +$ echo 'h1::before {content: "πŸ‘­"}' | sass --charset +@charset "UTF-8"; +h1::before { + content: "πŸ‘­"; +} +``` + +#### `--error-css` + +{% compatibility '1.20.0' %}{% endcompatibility %} + +This flag tells Sass whether to emit a CSS file when an error occurs during +compilation. This CSS file describes the error in a comment _and_ in the +`content` property of `body::before`, so that you can see the error message in +the browser without needing to switch back to the terminal. + +By default, error CSS is enabled if you're compiling to at least one file on +disk (as opposed to standard output). You can pass `--error-css` explicitly to +enable it even when you're compiling to standard out, or `--no-error-css` to +disable it everywhere. When it's disabled, the [`--update` flag][] and +[`--watch` flag][] will delete CSS files instead when an error occurs. + +[`--watch` flag]: #watch + +```shellsession +$ sass --error-css style.scss style.css +/* Error: Incompatible units em and px. + * , + * 1 | $width: 15px + 2em; + * | ^^^^^^^^^^ + * ' + * test.scss 1:9 root stylesheet */ + +body::before { + font-family: "Source Code Pro", "SF Mono", Monaco, Inconsolata, "Fira Mono", + "Droid Sans Mono", monospace, monospace; + white-space: pre; + display: block; + padding: 1em; + margin-bottom: 1em; + border-bottom: 2px solid black; + content: "Error: Incompatible units em and px.\a \2577 \a 1 \2502 $width: 15px + 2em;\a \2502 ^^^^^^^^^^\a \2575 \a test.scss 1:9 root stylesheet"; +} +Error: Incompatible units em and px. + β•· +1 β”‚ $width: 15px + 2em; + β”‚ ^^^^^^^^^^ + β•΅ + test.scss 1:9 root stylesheet +``` + +#### `--update` + +{% compatibility '1.4.0' %}{% endcompatibility %} + +If the `--update` flag is passed, Sass will only compile stylesheets whose +dependencies have been modified more recently than the corresponding CSS file +was generated. It will also print status messages when updating stylesheets. + +```shellsession +$ sass --update themes:public/css +Compiled themes/light.scss to public/css/light.css. +``` + +### Source Maps + +{% compatibility '1.3.0' %}{% endcompatibility %} + +{% include 'documentation/snippets/source-maps.liquid' %} + +Dart Sass generates source maps by default for every CSS file it emits. + +#### `--no-source-map` + +If the `--no-source-map` flag is passed, Sass won't generate any source maps. it +cannot be passed along with other source map options. + +```shellsession +$ sass --no-source-map style.scss style.css +``` + +#### `--source-map-urls` + +This option controls how the source maps that Sass generates link back to the +Sass files that contributed to the generated CSS. Dart Sass supports two types +of URLs: + +- `relative` (the default) uses relative URLs from the location of the source + map file to the locations of the Sass source file. +- `absolute` uses the absolute [`file:` URLs][] of the Sass source files. Note + that absolute URLs will only work on the same computer that the CSS was + compiled. + +[`file:` URLs]: https://en.wikipedia.org/wiki/File_URI_scheme + +```shellsession +​# Generates a URL like /documentation/sass/style.scss". +$ sass --source-map-urls=relative sass/style.scss css/style.css + +​# Generates a URL like "file:///home/style-wiz/sassy-app/sass/style.scss". +$ sass --source-map-urls=absolute sass/style.scss css/style.css +``` + +#### `--embed-sources` + +This flag tells Sass to embed the entire contents of the Sass files that +contributed to the generated CSS in the source map. This may produce very large +source maps, but it guarantees that the source will be available on any computer +no matter how the CSS is served. + +```shellsession +$ sass --embed-sources sass/style.scss css.style.css +``` + +#### `--embed-source-map` + +This flag tells Sass to embed the contents of the source map file in the +generated CSS, rather than creating a separate file and linking to it from the +CSS. + +```shellsession +$ sass --embed-source-map sass/style.scss css.style.css +``` + +### Other Options + +#### `--watch` + +{% compatibility '1.6.0' %}{% endcompatibility %} + +This flag (abbreviated `-w`) acts like the [`--update` flag][], but after the +first round compilation is done Sass stays open and continues compiling +stylesheets whenever they or their dependencies change. + +[`--update` flag]: #update + +Sass watches only the directories that you pass as-is on the command line, +parent directories of filenames you pass on the command line, and load paths. It +does not watch additional directories based on a file's `@import`/`@use`/ +`@forward` rules. + +```shellsession +$ sass --watch themes:public/css +Compiled themes/light.scss to public/css/light.css. + +​# Then when you edit themes/dark.scss... +Compiled themes/dark.scss to public/css/dark.css. +``` + +#### `--poll` + +{% compatibility '1.8.0' %}{% endcompatibility %} + +This flag, which may only be passed along with `--watch`, tells Sass to manually +check for changes to the source files every so often instead of relying on the +operating system to notify it when something changes. This may be necessary if +you're editing Sass on a remote drive where the operating system's notification +system doesn't work. + +```shellsession +$ sass --watch --poll themes:public/css +Compiled themes/light.scss to public/css/light.css. + +​# Then when you edit themes/dark.scss... +Compiled themes/dark.scss to public/css/dark.css. +``` + +#### `--stop-on-error` + +{% compatibility '1.8.0' %}{% endcompatibility %} + +This flag tells Sass to stop compiling immediately when an error is detected, +rather than trying to compile other Sass files that may not contain errors. It's +mostly useful in [many-to-many mode][]. + +```shellsession +$ sass --stop-on-error themes:public/css +Error: Expected expression. + β•· +42 β”‚ h1 {font-face: } + β”‚ ^ + β•΅ + themes/light.scss 42:16 root stylesheet +``` + +#### `--interactive` + +{% compatibility '1.5.0' %}{% endcompatibility %} + +This flag (abbreviated `-i`) tells Sass to run in interactive mode, where you +can write [SassScript expressions][] and see their results. Interactive mode +also supports [variables][] and [`@use` rules][]. + +[SassScript expressions]: /documentation/syntax/structure#expressions +[variables]: /documentation/variables +[`@use` rules]: /documentation/at-rules/use + +```shellsession +$ sass --interactive +>> 1px + 1in +97px +>> @use "sass:map" +>> $map: ("width": 100px, "height": 70px) +("width": 100px, "height": 70px) +>> map.get($map, "width") +100px +``` + +#### `--color` + +This flag (abbreviated `-c`) tells Sass to emit [terminal colors][], and the +inverse `--no-color` tells it not to emit colors. By default, it will emit +colors if it looks like it's being run on a terminal that supports them. + +[terminal colors]: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors + +
$ sass --color style.scss style.css
+Error: Incompatible units em and px.
+  β•·
+1 β”‚ $width: 15px + 2em
+  β”‚         ^^^^^^^^^^
+  β•΅
+  style.scss 1:9  root stylesheet
+
+$ sass --no-color style.scss style.css
+Error: Incompatible units em and px.
+  β•·
+1 β”‚ $width: 15px + 2em
+  β”‚         ^^^^^^^^^^
+  β•΅
+  style.scss 1:9  root stylesheet
+ +#### `--no-unicode` + +{% compatibility '1.17.0' %}{% endcompatibility %} + +This flag tells Sass only to emit ASCII characters to the terminal as part of +error messages. By default, or if `--unicode` is passed, Sass will emit non-ASCII +characters for these messages. This flag does not affect the CSS output. + +```shellsession +$ sass --no-unicode style.scss style.css +Error: Incompatible units em and px. + , +1 | $width: 15px + 2em; + | ^^^^^^^^^^ + ' + test.scss 1:9 root stylesheet + +$ sass --unicode style.scss style.css +Error: Incompatible units em and px. + β•· +1 β”‚ $width: 15px + 2em; + β”‚ ^^^^^^^^^^ + β•΅ + test.scss 1:9 root stylesheet +``` + +#### `--quiet` + +This flag (abbreviated `-q`) tells Sass not to emit any warnings when compiling. +By default, Sass emits warnings when deprecated features are used or when the +[`@warn` rule][] is encountered. It also silences the [`@debug` rule][]. + +[`@warn` rule]: /documentation/at-rules/warn +[`@debug` rule]: /documentation/at-rules/debug + +```shellsession +$ sass --quiet style.scss style.css +``` + +#### `--quiet-deps` + +This flag tells Sass not to emit deprecation warnings that come from +dependencies. It considers any file that's transitively imported through a [load +path] to be a "dependency". This flag doesn't affect the [`@warn` rule] or the +[`@debug` rule]. + +```shellsession +$ sass --load-path=node_modules --quiet-deps style.scss style.css +``` + +#### `--fatal-deprecation` + +{% compatibility '1.59.0' %}{% endcompatibility %} + +This option tells Sass to treat a particular type of deprecation warning as +an error. For example, this command tells Sass to treat deprecation +warnings for `/`-as-division as errors: + +```shellsession +$ sass --fatal-deprecation=slash-div style.scss style.css +Error: Using / for division outside of calc() is deprecated and will be removed in Dart Sass 2.0.0. + +Recommendation: math.div(4, 2) or calc(4 / 2) + +More info and automated migrator: https://sass-lang.com/d/slash-div + +This is only an error because you've set the slash-div deprecation to be fatal. +Remove this setting if you need to keep using this feature. + β•· +1 β”‚ a { b: (4/2); } + β”‚ ^^^ + β•΅ + style.scss 1:9 root stylesheet +``` + +The following deprecation IDs can be passed to this option: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDVersionDescription
call-string0.0.0Passing a string directly to meta.call().
elseif1.3.2Using @elseif instead of @else if.
moz-document1.7.2Using @-moz-document (except for the empty url prefix hack).
new-global1.17.2Declaring new variables with !global.
color-module-compat1.23.0Using color module functions in place of plain CSS functions.
slash-div1.33.0Using the / operator for division.
bogus-combinators1.54.0Leading, trailing, and repeated combinators.
strict-unary1.55.0Ambiguous + and - operators.
function-units1.56.0Passing invalid units to built-in functions.
duplicate-var-flags1.62.0Using multiple copies of !global or !default in a single variable declaration.
+ +Alternatively, you can pass a Dart Sass version to treat all deprecations that +were present in that version as errors. For example, +`--fatal-deprecation=1.33.0` would treat all deprecations in the +table above up to and including `slash-div` as errors, but leave any newer +deprecations as warnings. + +#### `--trace` + +This flag tells Sass to print the full Dart or JavaScript stack trace when an +error is encountered. It's used by the Sass team for debugging errors. + +```shellsession +$ sass --trace style.scss style.css +Error: Expected expression. + β•· +42 β”‚ h1 {font-face: } + β”‚ ^ + β•΅ + themes/light.scss 42:16 root stylesheet + +package:sass/src/visitor/evaluate.dart 1846:7 _EvaluateVisitor._addExceptionSpan +package:sass/src/visitor/evaluate.dart 1128:12 _EvaluateVisitor.visitBinaryOperationExpression +package:sass/src/ast/sass/expression/binary_operation.dart 39:15 BinaryOperationExpression.accept +package:sass/src/visitor/evaluate.dart 1097:25 _EvaluateVisitor.visitVariableDeclaration +package:sass/src/ast/sass/statement/variable_declaration.dart 50:15 VariableDeclaration.accept +package:sass/src/visitor/evaluate.dart 335:13 _EvaluateVisitor.visitStylesheet +package:sass/src/visitor/evaluate.dart 323:5 _EvaluateVisitor.run +package:sass/src/visitor/evaluate.dart 81:10 evaluate +package:sass/src/executable/compile_stylesheet.dart 59:9 compileStylesheet +package:sass/src/executable.dart 62:15 main +``` + +#### `--help` + +This flag (abbreviated `-h`) prints a summary of this documentation. + +```shellsession +$ sass --help +Compile Sass to CSS. + +Usage: sass [output.css] + sass : + : + +... +``` + +#### `--version` + +This flag prints the current version of Sass. + +```shellsession +$ sass --version +{{ releases['dart-sass'].version }} +``` +{% endmarkdown %} diff --git a/source/documentation/cli/index.md b/source/documentation/cli/index.md new file mode 100644 index 0000000..bf318bc --- /dev/null +++ b/source/documentation/cli/index.md @@ -0,0 +1,13 @@ +--- +title: Command-Line Interface +introduction: > + Different implementations of Sass have different interfaces when using them + from the command line: +overview: true +--- + +- [Dart Sass](/documentation/cli/dart-sass) has the same command-line interface no matter how + you [install it](/dart-sass). + +- [Ruby Sass](/documentation/cli/ruby-sass) is [deprecated](/ruby-sass), and we + recommend you move to a different implementation. diff --git a/source/documentation/snippets/source-maps.liquid b/source/documentation/snippets/source-maps.liquid new file mode 100644 index 0000000..c6c273e --- /dev/null +++ b/source/documentation/snippets/source-maps.liquid @@ -0,0 +1,7 @@ +Source maps are files that tell browsers or other tools that consume CSS how +that CSS corresponds to the Sass files from which it was generated. They make it +possible to see and even edit your Sass files in browsers. See instructions for +using source maps in [Chrome][] and [Firefox][]. + +[Chrome]: https://developers.google.com/web/tools/chrome-devtools/javascript/source-maps +[Firefox]: https://developer.mozilla.org/en-US/docs/Tools/Style_Editor#Source_map_support From efd3e6774fa8b8b37f57b6e191f52a1f77f60b61 Mon Sep 17 00:00:00 2001 From: Ed Rivas Date: Wed, 24 May 2023 00:17:27 +0000 Subject: [PATCH 4/9] Por cli/migrator --- .../example-module-migrator.liquid | 25 + source/documentation/cli/migrator.liquid | 491 ++++++++++++++++++ 2 files changed, 516 insertions(+) create mode 100644 source/code-snippets/example-module-migrator.liquid create mode 100644 source/documentation/cli/migrator.liquid diff --git a/source/code-snippets/example-module-migrator.liquid b/source/code-snippets/example-module-migrator.liquid new file mode 100644 index 0000000..02b7a5f --- /dev/null +++ b/source/code-snippets/example-module-migrator.liquid @@ -0,0 +1,25 @@ +```shellsession +$ cat style.scss +$body-bg: #000; +$body-color: #111; + +@import "bootstrap"; + +@include media-breakpoint-up(sm) { + .navbar { + display: block; + } +} +$ sass-migrator --migrate-deps module style.scss +$ cat style.scss +@use "bootstrap" with ( + $body-bg: #000, + $body-color: #111 +); + +@include bootstrap.media-breakpoint-up(sm) { + .navbar { + display: block; + } +} +``` diff --git a/source/documentation/cli/migrator.liquid b/source/documentation/cli/migrator.liquid new file mode 100644 index 0000000..5a740ad --- /dev/null +++ b/source/documentation/cli/migrator.liquid @@ -0,0 +1,491 @@ +--- +title: "Migrator" +table_of_contents: true +introduction: > + The Sass migrator automatically updates your Sass files to help you move on to + the latest and greatest version of the language. Each of its commands migrates + a single feature, to give you as much control as possible over what you update + and when. +complementary_content: | + +--- +{% markdown %} +## Usage + +To use the Sass migrator, tell it [which migration][] you want to run and what +Sass files you want to migrate: + +[which migration]: #migrations + +``` +sass-migrator +``` + +By default, the migrator will only change files that you explicitly pass on the +command line. Passing the [`--migrate-deps` option][] tells the migrator to also +change all the stylesheets that are loaded using the [`@use` rule][], +[`@forward` rule][], or [`@import` rule][]. And if you want to do a test run to +see what changes will be made without actually saving them, you can pass +[--dry-run][] [--verbose][] (or `-nv` for short). + +[`--migrate-deps` option]: #migrate-deps +[`@use` rule]: /documentation/at-rules/use +[`@forward` rule]: /documentation/at-rules/forward +[`@import` rule]: /documentation/at-rules/import +[--dry-run]: #dry-run +[--verbose]: #verbose + +{% include 'code-snippets/example-module-migrator' %} + +## Installation + +You can install the Sass migrator from most of the same places that you can +install [Dart Sass](/dart-sass): + +### Standalone + +You can install the Sass migrator on Windows, Mac, or Linux by downloading the +package for your operating system [from GitHub][] and [adding it to your +`PATH`][]. + +[from GitHub]: {{ releases['migrator'].url }} +[adding it to your `PATH`]: https://katiek2.github.io/path-doc/ + +### npm + +If you use Node.js, you can also install the Sass migrator using [npm][] by +running + +[npm]: https://www.npmjs.com + +``` +npm install -g sass-migrator +``` + +### Chocolatey + +If you use [the Chocolatey package manager][] for Windows, you can install the +Sass migrator by running + +[the Chocolatey package manager]: https://chocolatey.org + +``` +choco install sass-migrator +``` + +### Homebrew + +If you use [the Homebrew package manager][] for Mac OS X, you can install Dart +Sass by running + +[the Homebrew package manager]: https://brew.sh + +``` +brew install sass/sass/migrator +``` + +## Global Options + +These options are available for all migrators. + +### `--migrate-deps` + +This option (abbreviated `-d`) tells the migrator to change not just the +stylesheets that are explicitly passed on the command line, but also any +stylesheets that they depend on using the [`@use` rule][], [`@forward` rule][], +or [`@import` rule][]. + +```shellsession +$ sass-migrator module --verbose style.scss +Migrating style.scss +$ sass-migrator module --verbose --migrate-deps style.scss +Migrating style.scss +Migrating _theme.scss +Migrating _fonts.scss +Migrating _grid.scss +``` + +{% headsUp %} + The [module migrator][] assumes that any stylesheet that is depended on using + a [`@use` rule][] or a [`@forward` rule][] has already been migrated to the + module system, so it won't attempt to migrate them, even when the + `--migrate-deps` option is passed. + + [module migrator]: #module + [`@use` rule]: /documentation/at-rules/use + [`@forward` rule]: /documentation/at-rules/forward +{% endheadsUp %} + +### `--load-path` + +This option (abbreviated `-I`) tells the migrator a [load path][] where it +should look for stylesheets. It can be passed multiple times to provide multiple +load paths. Earlier load paths will take precedence over later ones. + +Dependencies loaded from load paths are assumed to be third-party libraries, so +the migrator will not migrate them even when the [`--migrate-deps` option][] is +passed. + +[load path]: /documentation/at-rules/use#load-paths + +### `--dry-run` + +This flag (abbreviated `-n`) tells the migrator not to save any changes to +disk. It instead prints the list of files that it would have changed. This is +commonly paired with the [`--verbose` option][] to print the contents of the +changes that would have been made as well. + +[`--verbose` option]: #verbose + +```shellsession +$ sass-migrator module --dry-run --migrate-deps style.scss +Dry run. Logging migrated files instead of overwriting... + +style.scss +_theme.scss +_fonts.scss +_grid.scss +``` + +#### `--no-unicode` + +This flag tells the Sass migrator only to emit ASCII characters to the terminal +as part of error messages. By default, or if `--unicode` is passed, the migrator +will emit non-ASCII characters for these messages. This flag does not affect the +CSS output. + +```shellsession +$ sass-migrator --no-unicode module style.scss +line 1, column 9 of style.scss: Error: Could not find Sass file at 'typography'. + , +1 | @import "typography"; + | ^^^^^^^^^^^^ + ' +Migration failed! +$ sass-migrator --unicode module style.scss +line 1, column 9 of style.scss: Error: Could not find Sass file at 'typography'. + β•· +1 β”‚ @import "typography"; + β”‚ ^^^^^^^^^^^^ + β•΅ +Migration failed! +``` + +### `--verbose` + +This flag (abbreviated `-v`) tells the migrator to print extra information to +the console. By default, it just prints the name of files that are changed, but +when combined with the [`--dry-run` option][] it also prints those files' new +contents. + +[`--dry-run` option]: #dry-run + +``` +$ sass-migrator module --verbose --dry-run style.scss +Dry run. Logging migrated files instead of overwriting... +<==> style.scss +@use "bootstrap" with ( + $body-bg: #000, + $body-color: #111 +); + +@include bootstrap.media-breakpoint-up(sm) { + .navbar { + display: block; + } +} +$ sass-migrator module --verbose style.scss +Migrating style.scss +``` + +## Migrations + +### Division + +This migration converts stylesheets that use [`/` as division] to use the +built-in `math.div` function instead. + +[`/` as division]: /documentation/breaking-changes/slash-div + +#### `--pessimistic` + +By default, the migrator converts `/` operations to `math.div` even when it +isn't sure that it will be division when evaluated. It only leaves them as-is +when it can statically determine that they're doing something else (such as when +there's no SassScript involved, or when one of the operands is a string). The +`math.div` function currently functions identically to the `/` operator, so +this is safe to do, but may result in new warnings if one of the arguments to +`math.div` at runtime is not a number. + +If you want to avoid this behavior, you can pass the `--pessimistic` flag. With +this flag, the migrator will only convert `/` operations that it knows for sure +are doing division. This will prevent any unnecessary `math.div` conversions, +but it's likely to leave some division unmigrated if it can't be statically +determined. + +### Module + +This migration converts stylesheets that use the old [`@import` rule][] to load +dependencies so that they use the Sass module system via the [`@use` rule][] +instead. It doesn't just naΓ―vely change `@import`s to `@use`sβ€”it updates +stylesheets intelligently so that they keep working the same way they did +before, including: + +* Adding namespaces to uses of members (variables, mixins, and functions) from + other modules. + +* Adding new `@use` rules to stylesheets that were using members without + importing them. + +* Converting overridden default variables to [`with` clauses][]. + + [`with` clauses]: /documentation/at-rules/use#configuration + +* Automatically removing `-` and `_` prefixes from members that are used from + other files (because otherwise they'd be considered [private][] and could only + be used in the module they're declared). + + [private]: /documentation/at-rules/use#private-members + +* Converting [nested imports][] to use the [`meta.load-css()` mixin][] instead. + + [nested imports]: /documentation/at-rules/import#nesting + [`meta.load-css()` mixin]: /documentation/modules/meta#load-css + +{% headsUp %} + Because the module migrator may need to modify both member definitions *and* + member names, it's important to either run it with the [`--migrate-deps` + option][] or ensure that you pass it all the stylesheets in your package or + application. + + [`--migrate-deps` option]: #migrate-deps +{% endheadsUp %} + +{% include 'code-snippets/example-module-migrator' %} + +#### Loading Dependencies + +The module migrator needs to be able to read all of the stylesheets depended on +by the ones it's migrating, even if the [`--migrate-deps` option][] is not +passed. If the migrator fails to find a dependency, you'll get an error. + +```shellsession +$ ls . +style.scss node_modules +$ sass-migrator module style.scss +Error: Could not find Sass file at 'dependency'. + , +1 | @import "dependency"; + | ^^^^^^^^^^^^ + ' + style.scss 1:9 root stylesheet +Migration failed! +$ sass-migrator --load-path node_modules module style.scss +``` + +If you use a [load path][] when compiling your stylesheets, make sure to pass +that to the migrator using the [`--load-path` option][]. + +Unfortunately, the migrator does not support custom importers, but it does have +built-in support for resolving URLs starting with `~` by searching in +`node_modules`, similar to [what Webpack supports][]. + +[load path]: /documentation/at-rules/use#load-paths +[`--load-path` option]: #load-path +[what Webpack supports]: https://github.com/webpack-contrib/sass-loader#resolving-import-at-rules + +#### `--remove-prefix` + +This option (abbreviated `-p`) takes an identifier prefix to remove from the +beginning of all variable, mixin, and function names when they're migrated. +Members that don't start with this prefix will remain unchanged. + +The [`@import` rule][] put all top-level members in one global scope, so when it +was the standard way of loading stylesheets, everyone was incentivized to add +prefixes to all their member names to avoid accidentally redefining some other +stylesheet's. The module system solves this problem, so it's useful to +automatically strip those old prefixes now that they're unnecessary. + +```shellsession +$ cat style.scss +@import "theme"; + +@mixin app-inverted { + color: $app-bg-color; + background-color: $app-color; +} +$ sass-migrator --migrate-deps module --remove-prefix=app- style.scss +$ cat style.scss +@import "theme"; + +@mixin inverted { + color: theme.$bg-color; + background-color: theme.$color; +} +``` + +When you pass this option, the migrator will also generate an [import-only +stylesheet][] that [forwards][] all the members with the prefix added back, to +preserve backwards-compatibility for users who were importing the library. + +[import-only stylesheet]: /documentation/at-rules/import#import-only-files +[forwards]: /documentation/at-rules/forward + +This option may be passed multiple times, or with multiple values separated by +commas. Each prefix will be removed from any members that have it. If a member +matches multiple prefixes, the longest matching prefix will be removed. + +#### `--forward` + +This option tells the migrator which members to forward using the [`@forward` +rule][]. It supports the following settings: + +* `none` (the default) doesn't forward any members. + +* `all` forwards all members except those that started with `-` or `_` in the + original stylesheet, since that was commonly used to mark a package-private + member before the module system was introduced. + +* `prefixed` forwards only members that begin with the prefix passed to the + [`--remove-prefix` option][]. This option may only be used in conjunction with + the `--remove-prefix` option. + + [`--remove-prefix` option]: #remove-prefix + +All files that are passed explicitly on the command line will forward members +that are transitively loaded by those files using the `@import` rule. Files +loaded using the [`--migrate-deps` option][] will not forward any new members. +This option is particularly useful when migrating a Sass library, because it +ensures that users of that library will still be able to access all the members +it defines. + +```shellsession +$ cat _index.scss +@import "theme"; +@import "typography"; +@import "components"; +$ sass-migrator --migrate-deps module --forward=all style.scss +$ cat _index.scss +@forward "theme"; +@forward "typography"; +@forward "components"; +``` + +### Namespace + +This migration allows you to easily change the [namespaces][] of the `@use` +rules in a stylesheet. This is useful if the namespaces that the module migrator +generates to resolve conflicts are non-ideal, or if you don't want to use the +default namespace that Sass determines based on the rule's URL. + +[namespaces]: /documentation/at-rules/use#choosing-a-namespace + +#### `--rename` + +You can tell the migrator which namespace(s) you want it to change by passing +expressions to the `--rename` option. + +These expressions are of the form ` to ` or +`url to `. In these expressions, `` and +`` are [regular expressions][] which match against the entirety of the +existing namespace or the `@use` rule's URL, respectively. + +[regular expressions]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions + +For simple use cases, this just looks like `--rename 'old to new'`, which would +rename a `@use` rule with the namespace `old` to instead be `new`. + +However, you can also do this to accomplish more complicated renames. For +instance, say that you previously had a stylesheet that looked like this: + +```scss +@import "components/button/lib/mixins"; +@import "components/input/lib/mixins"; +@import "components/table/lib/mixins"; +// ... +``` + +Since all of these URLs would have the default namespace `mixins` when migrated +to `@use` rules, the module migrator may end up generating something like this: + +```scss +@use "components/button/lib/mixins" as button-lib-mixins; +@use "components/input/lib/mixins" as input-lib-mixins; +@use "components/table/lib/mixins" as table-lib-mixins; +// ... +``` + +This is valid code since the namespaces don't conflict, but they're way more +complicated than they need to be. The relevant part of the URL is the component +name, so we can use the namespace migrator to extract that part out. + +If we run the namespace migrator with +`--rename 'url components/(\w+)/lib/mixins to \1'`, we'll end up with: + +```scss +@use "components/button/lib/mixins" as button; +@use "components/input/lib/mixins" as input; +@use "components/table/lib/mixins" as table; +// ... +``` + +The rename script here says to find all of the `@use` rules whose URLs look like +`components/(\w+)/lib/mixins` (`\w+` in a regular expression means to match any +word of one or more characters). The `\1` in the output clause means to +substitute in the contents of the first set of parentheses in the regular +expression (called a [group][]). + +[group]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Groups_and_Ranges + +If you wish to apply multiple renames, you can pass the `--rename` option +multiple times, or separate them with a semicolon or a line break. Only the +first rename that applies to a given rule will be used, so you could pass +something like `--rename 'a to b; b to a'` to swap the namespaces `a` and `b`. + +#### `--force` + +By default, if two or more `@use` rules have the same namespace after the +migration, the migrator will fail, and no changes will be made. + +In this case, you'll usually want to adjust your `--rename` script to avoid +creating conflicts, but if you'd prefer to force the migration, you can instead +pass `--force`. + +With `--force`, if any conflicts are encountered, the first `@use` rule will +get its preferred namespace, while subsequent `@use` rules with the same +preferred namespace will instead have a numerical suffix added to them. + +{% endmarkdown %} From db46cc7ed1cc51ad5e2c49605bfb1625d9e5fb73 Mon Sep 17 00:00:00 2001 From: Ed Rivas Date: Wed, 24 May 2023 00:26:45 +0000 Subject: [PATCH 5/9] Port cli/ruby-sass --- source/documentation/cli/ruby-sass.liquid | 544 ++++++++++++++++++++++ 1 file changed, 544 insertions(+) create mode 100644 source/documentation/cli/ruby-sass.liquid diff --git a/source/documentation/cli/ruby-sass.liquid b/source/documentation/cli/ruby-sass.liquid new file mode 100644 index 0000000..9005b1a --- /dev/null +++ b/source/documentation/cli/ruby-sass.liquid @@ -0,0 +1,544 @@ +--- +title: Ruby Sass Command-Line Interface +table_of_contents: true +complementary_content: | + +--- +{% markdown %} +{% headsUp %} +[Ruby Sass has reached end of life][] and is now totally unmaintained. Please +switch to [Dart Sass][] or [LibSass][] at your earliest convenience. + +[Ruby Sass has reached end of life]: /blog/ruby-sass-is-unsupported +[Dart Sass]: /dart-sass +[LibSass]: /libsass +{% endheadsUp %} + +## Usage + +The Ruby Sass executable can be invoked in one of two modes. + +### One-to-One Mode + +``` +sass [input.scss] [output.css] +``` + +One-to-one mode compiles a single input file (`input.scss`) to a single output +location (`output.css`). If no output location is passed, the compiled CSS is +printed to the terminal. If no input *or* output is passed, the CSS is read from +[standard input][] and printed to the terminal. + +[standard input]: https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin) + +The input file is parsed as [SCSS][] if its extension is `.scss` or as the +[indented syntax][] if its extension is `.sass`. If it doesn't have one of these +two extensions, or if it comes from standard input, it's parsed as the +indented syntax by default. This can be controlled with the [`--scss` flag][]. + +[SCSS]: /documentation/syntax#scss +[indented syntax]: /documentation/syntax#the-indented-syntax +[`--scss` flag]: #scss + +### Many-to-Many Mode + +``` +sass [:] [:] [input.css] [input/]... +``` + +Many-to-many mode compiles one or more input files to one or more output files. +The inputs are separated from the outputs with colons. It can also compile all +Sass files in a directory to CSS files with the same names in another directory. +Many-to-many mode is enabled when any argument contains a colon, *or* when the +[`--update` flag][] or the [`--watch` flag][] is passed. + +[`--update` flag]: #update +[`--watch` flag]: #watch + +If an input file is passed without a corresponding output file, it's compiled to +a CSS file named after the input file, but with the extension replaced with +`.css`. If an input directory is passed without a corresponding output +directory, all the Sass files within it are compiled to CSS files in the same +directory. + +```shellsession +$ sass style.scss:style.css + write style.css + write style.css.map +$ sass light.scss:light.css dark.scss:dark.css + write light.css + write light.css.map + write dark.css + write dark.css.map +$ sass themes:public/css + write public/css/light.css + write public/css/light.css.map + write public/css/dark.css + write public/css/dark.css.map +``` + +When compiling whole directories, Sass will ignore [partial files][] whose names +begin with `_`. You can use partials to separate out your stylesheets without +creating a bunch of unnecessary output files. + +[partial files]: /documentation/at-rules/use#partials + +Many-to-many mode will only compile stylesheets whose dependencies have been +modified more recently than the corresponding CSS file was generated. It will +also print status messages when updating stylesheets. + +## Options + +### Common + +#### `--load-path` + +This option (abbreviated `-I`) adds an additional [load path][] for Sass to look +for stylesheets. It can be passed multiple times to provide multiple load paths. +Earlier load paths will take precedence over later ones. + +[load path]: /documentation/at-rules/use#load-paths + +```shellsession +$ sass --load-path=node_modules/bootstrap/dist/css style.scss style.css +``` + +Load paths are also loaded from the `SASS_PATH` [environment variable][], if +it's set. This variable should be a list of paths separated by `;` (on Windows) +or `:` (on other operating systems). Load paths on `SASS_PATH` take precedence +over load paths passed on the command line. + +[environment variable]: https://en.wikipedia.org/wiki/Environment_variable + +```shellsession +$ SASS_PATH=node_modules/bootstrap/dist/css sass style.scss style.css +``` + +#### `--require` + +This option (abbreviated `-r`) loads a [Ruby gem][] before running Sass. It can +be used to load functions defined in Ruby into your Sass environment. + +[Ruby gem]: https://rubygems.org/ + +```shellsession +$ sass --require=rails-sass-images style.scss style.css +``` + +#### `--compass` + +This flag loads the [Compass framework][] and makes its mixins and functions +available for use in Sass. + +[Compass framework]: http://compass-style.org/ + +```shellsession +$ sass --compass style.scss style.css +``` + +#### `--style` + +This option (abbreviated `-t`) controls the output style of the resulting CSS. +Ruby Sass supports four output styles: + +* `nested` (the default) indents CSS rules to match the nesting of the Sass + source. +* `expanded` writes each selector and declaration on its own line. +* `compact` puts each CSS rule on its own single line. +* `compressed` removes as many extra characters as possible, and writes the + entire stylesheet on a single line. + +```shellsession +$ sass --style=nested +h1 { + font-size: 40px; } + h1 code { + font-face: Roboto Mono; } + +$ sass --style=expanded style.scss +h1 { + font-size: 40px; +} +h1 code { + font-face: Roboto Mono; +} + +$ sass --style=compact style.scss +h1 { font-size: 40px; } +h1 code { font-face: Roboto Mono; } + +$ sass --style=compressed style.scss +h1{font-size:40px}h1 code{font-face:Roboto Mono} +``` + +#### `--help` + +This flag (abbreviated `-h` and `-?`) prints a summary of this documentation. + +```shellsession +$ sass --help +Usage: sass [options] [INPUT] [OUTPUT] + +Description: + Converts SCSS or Sass files to CSS. + +... +``` + +#### `--version` + +This flag prints the current version of Sass. + +```shellsession +$ sass --version +Sass 3.7.4 +``` + +### Watching and Updating + +These options affect [many-to-many mode][]. + +[many-to-many mode]: #many-to-many-mode + +#### `--watch` + +Enables [many-to-many mode][], and causes Sass to stay open and continue +compiling stylesheets whenever they or their dependencies change. + +```shellsession +$ sass --watch themes:public/css + write public/css/light.css + write public/css/light.css.map + +​# Then when you edit themes/dark.scss... + write public/css/dark.css + write public/css/dark.css.map +``` + +#### `--poll` + +This flag, which may only be passed along with `--watch`, tells Sass to manually +check for changes to the source files every so often instead of relying on the +operating system to notify it when something changes. This may be necessary if +you're editing Sass on a remote drive where the operating system's notification +system doesn't work. + +```shellsession +$ sass --watch --poll themes:public/css + write public/css/light.css + write public/css/light.css.map + +​# Then when you edit themes/dark.scss... + write public/css/dark.css + write public/css/dark.css.map +``` + +#### `--update` + +This flag enables [many-to-many mode][], even if none of the arguments are +colon-separated pairs. + +```shellsession +$ sass --update style.scss + write style.css + write style.css.map +``` + +#### `--force` + +This flag (abbreviated `-f`) may only be passed in [many-to-many mode][]. It +causes Sass files to *always* be compiled to CSS files, instead of only being +compiled when the source files are more up-to-date than the output. + +The `--force` flag may not be passed alongside the [`--watch` flag][]. + +```shellsession +$ sass --force style.scss:style.css + write style.css + write style.css.map +``` + +#### `--stop-on-error` + +This flag may only be passed in [many-to-many mode][]. It tells Sass to stop +compiling immediately when an error is detected, rather than trying to compile +other Sass files that may not contain errors. + +```shellsession +$ sass --stop-on-error themes:public/css +Error: Invalid CSS after "h1 {font-size: ": expected expression (e.g. 1px, bold), was "}" + on line 1 of test.scss + Use --trace for backtrace. +``` + +### Input and Output + +These options control how Sass loads its input files and how it produces output +files. + +#### `--scss` + +This flag tells Sass to parse [standard input][] as [SCSS][]. + +```shellsession +$ echo "h1 {font-size: 40px}" | sass --scss +h1 { + font-size: 40px; +} +``` + +#### `--sourcemap` + +This option controls how Sass generates source maps, which are files that tell +browsers or other tools that consume CSS how that CSS corresponds to the Sass +files from which it was generated. They make it possible to see and even edit +your Sass files in browsers. See instructions for using source maps in +[Chrome][] and [Firefox][]. It has four possible values: + +[Chrome]: https://developers.google.com/web/tools/chrome-devtools/javascript/source-maps +[Firefox]: https://developer.mozilla.org/en-US/docs/Tools/Style_Editor#Source_map_support + +* `auto` (the default) uses relative URLs to link from the source map to the + Sass stylesheets where possible, and absolute [`file:` URLs][] otherwise. +* `file` always uses absolute absolute `file:` URLs to link from the source map + to the Sass stylesheets. +* `inline` includes the text of the Sass stylehseets in the source map directly. +* `none` doesn't generate source maps at all. + +[`file:` URLs]: https://en.wikipedia.org/wiki/File_URI_scheme + +```shellsession +​# Generates a URL like "/documentation/sass/style.scss". +$ sass --sourcemap=auto sass/style.scss css/style.css + +​# Generates a URL like "file:///home/style-wiz/sassy-app/sass/style.scss". +$ sass --sourcemap=file sass/style.scss css/style.css + +​# Includes the full text of sass/style.scss in the source map. +$ sass --sourcemap=inline sass/style.scss css/style.css + +​# Doesn't generate a source map. +$ sass --sourcemap=none sass/style.scss css/style.css +``` + +#### `--stdin` + +This flag (abbreviated `-s`) is tells Sass to read its input file from [standard +input][]. When it's passed, no input file may be passed. + +```shellsession +$ echo -e 'h1\n font-size: 40px' | sass --stdin +h1 { + font-size: 40px; +} +``` + +The `--stdin` flag may not be used with [many-to-many mode][]. + +#### `--default-encoding` + +This option (abbreviated `-E`) controls the default [character encoding][] that +Sass will use to load source files that don't [explicitly specify][] a character +encoding. It defaults to the operating system's default encoding. + +[character encoding]: https://en.wikipedia.org/wiki/Character_encoding +[explicitly specify]: /documentation/syntax/parsing#input-encoding + +```shellsession +$ sass --default-encoding=Shift-JIS style.scss style.css +``` + +#### `--unix-newlines` + +This flag tells Sass to generate output files with whose lines are separated +with the U+000A LINE FEED character, as opposed to the operating system default +(on Windows, this is U+000D CARRIAGE RETURN followed by U+000A LINE FEED). It's +always true on systems that default to Unix-style newlines. + +```shellsession +$ sass --unix-newlines style.scss style.css +``` + +#### `--debug-info` + +This flag (abbreviated `-g`) causes Sass to emit dummy `@media` queries that +indicate where each style rule was defined in the source stylehseet. + +{% headsUp %} +This flag only exists for backwards-compatibility. Source maps are now the +recommended way of mapping CSS back to the Sass that generated it. +{% endheadsUp %} + +```shellsession +$ sass --debug-info style.scss +@media -sass-debug-info{filename{font-family:file\:\/\/\/home\/style-wiz\/sassy-app\/style\.scss}line{font-family:\000031}} +h1 { + font-size: 40px; } +``` + +#### `--line-comments` + +This flag (also available as `--line-numbers`, abbreviated as `-l`) causes Sass +to emit comments for every style rule that indicate where each style rule was +defined in the source stylesheet. + +```shellsession +$ sass --line-numbers style.scss +/* line 1, style.scss */ +h1 { + font-size: 40px; } +``` + +### Other Options + +#### `--interactive` + +This flag (abbreviated `-i`) tells Sass to run in interactive mode, where you +can write [SassScript expressions][] and see their results. Interactive mode +also supports [variables][]. + +[SassScript expressions]: /documentation/syntax/structure#expressions +[variables]: /documentation/variables + +```shellsession +$ sass --interactive +>> 1px + 1in +97px +>> $map: ("width": 100px, "height": 70px) +("width": 100px, "height": 70px) +>> map-get($map, "width") +100px +``` + +#### `--check` + +This flag (abbreviated `-c`) tells Sass to verify that the syntax of its input +file is valid without executing that file. If the syntax is valid, it exits with +[status][] 0. It can't be used in [many-to-many mode][]. + +[status]: https://en.wikipedia.org/wiki/Exit_status + +```shellsession +$ sass --check style.scss +``` + +#### `--precision` + +This option tells Sass how many digits of [precision][] to use when emitting +decimal numbers. + +[precision]: /documentation/values/numbers#precision + +```shellsession +$ echo -e 'h1\n font-size: (100px / 3)' | sass --precision=20 +h1 { + font-size: 33.333333333333336px; } +``` + +#### `--cache-location` + +This option tells Sass where to store its cache of parsed files, so it can +run faster in future invocations. It defaults to `.sass-cache`. + +```shellsession +$ sass --cache-location=/tmp/sass-cache style.scss style.css +``` + +#### `--no-cache` + +This flag (abbreviated `-C`) tells Sass not to cache parsed files at all. + +```shellsession +$ sass --no-cache style.scss style.css +``` + +#### `--trace` + +This flag tells Sass to print the full Ruby stack trace when an error is +encountered. It's used by the Sass team for debugging errors. + +```shellsession +Traceback (most recent call last): + 25: from /usr/share/gems/sass/bin/sass:13:in `
' + 24: from /usr/share/gems/sass/lib/sass/exec/base.rb:18:in `parse!' + 23: from /usr/share/gems/sass/lib/sass/exec/base.rb:50:in `parse' + 22: from /usr/share/gems/sass/lib/sass/exec/sass_scss.rb:63:in `process_result' + 21: from /usr/share/gems/sass/lib/sass/exec/sass_scss.rb:396:in `run' + 20: from /usr/share/gems/sass/lib/sass/engine.rb:290:in `render' + 19: from /usr/share/gems/sass/lib/sass/engine.rb:414:in `_to_tree' + 18: from /usr/share/gems/sass/lib/sass/scss/parser.rb:41:in `parse' + 17: from /usr/share/gems/sass/lib/sass/scss/parser.rb:137:in `stylesheet' + 16: from /usr/share/gems/sass/lib/sass/scss/parser.rb:697:in `block_contents' + 15: from /usr/share/gems/sass/lib/sass/scss/parser.rb:707:in `block_child' + 14: from /usr/share/gems/sass/lib/sass/scss/parser.rb:681:in `ruleset' + 13: from /usr/share/gems/sass/lib/sass/scss/parser.rb:689:in `block' + 12: from /usr/share/gems/sass/lib/sass/scss/parser.rb:697:in `block_contents' + 11: from /usr/share/gems/sass/lib/sass/scss/parser.rb:708:in `block_child' + 10: from /usr/share/gems/sass/lib/sass/scss/parser.rb:743:in `declaration_or_ruleset' + 9: from /usr/share/gems/sass/lib/sass/scss/parser.rb:820:in `try_declaration' + 8: from /usr/share/gems/sass/lib/sass/scss/parser.rb:1281:in `rethrow' + 7: from /usr/share/gems/sass/lib/sass/scss/parser.rb:807:in `block in try_declaration' + 6: from /usr/share/gems/sass/lib/sass/scss/parser.rb:999:in `value!' + 5: from /usr/share/gems/sass/lib/sass/scss/parser.rb:1161:in `sass_script' + 4: from /usr/share/gems/sass/lib/sass/script/parser.rb:68:in `parse' + 3: from /usr/share/gems/sass/lib/sass/script/parser.rb:855:in `assert_expr' + 2: from /usr/share/gems/sass/lib/sass/script/lexer.rb:240:in `expected!' + 1: from /usr/share/gems/sass/lib/sass/scss/parser.rb:1305:in `expected' +test.scss:1: Invalid CSS after "h1 {font-size: ": expected expression (e.g. 1px, bold), was "}" (Sass::SyntaxError) +``` +#### `--quiet` + +This flag (abbreviated `-q`) tells Sass not to emit any warnings when compiling. +By default, Sass emits warnings when deprecated features are used or when the +[`@warn` rule][] is encountered. It also silences the [`@debug` rule][]. + +[`@warn` rule]: /documentation/at-rules/warn +[`@debug` rule]: /documentation/at-rules/debug + +```shellsession +$ sass --quiet style.scss style.css +``` +{% endmarkdown %} From 95824e63c1d1a6bd5c011f87c44a0d30a434f2a2 Mon Sep 17 00:00:00 2001 From: Ed Rivas Date: Thu, 25 May 2023 18:32:37 +0000 Subject: [PATCH 6/9] Trigger CI From aed800efdcfbef4615da41a31fd829c5b0d6249e Mon Sep 17 00:00:00 2001 From: Jonny Gerig Meyer Date: Thu, 25 May 2023 16:46:25 -0400 Subject: [PATCH 7/9] review --- .../cli/{dart-sass.liquid => dart-sass.md} | 54 ++----------------- source/documentation/cli/index.md | 5 +- .../cli/{migrator.liquid => migrator.md} | 45 ++-------------- .../cli/{ruby-sass.liquid => ruby-sass.md} | 50 +---------------- 4 files changed, 13 insertions(+), 141 deletions(-) rename source/documentation/cli/{dart-sass.liquid => dart-sass.md} (90%) rename source/documentation/cli/{migrator.liquid => migrator.md} (91%) rename source/documentation/cli/{ruby-sass.liquid => ruby-sass.md} (90%) diff --git a/source/documentation/cli/dart-sass.liquid b/source/documentation/cli/dart-sass.md similarity index 90% rename from source/documentation/cli/dart-sass.liquid rename to source/documentation/cli/dart-sass.md index e3810f5..b65594e 100644 --- a/source/documentation/cli/dart-sass.liquid +++ b/source/documentation/cli/dart-sass.md @@ -1,50 +1,8 @@ --- title: Dart Sass Command-Line Interface table_of_contents: true -complementary_content: | - --- -{% markdown %} ## Usage The Dart Sass executable can be invoked in one of two modes. @@ -76,7 +34,7 @@ SCSS unless the [`--indented` flag][] is passed. [standard input]: https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin) -### Many-to-many Mode +### Many-to-Many Mode {% compatibility '1.4.0' %}{% endcompatibility %} @@ -265,7 +223,7 @@ Compiled themes/light.scss to public/css/light.css. {% compatibility '1.3.0' %}{% endcompatibility %} -{% include 'documentation/snippets/source-maps.liquid' %} +{% render 'documentation/snippets/source-maps' %} Dart Sass generates source maps by default for every CSS file it emits. @@ -293,7 +251,7 @@ of URLs: [`file:` URLs]: https://en.wikipedia.org/wiki/File_URI_scheme ```shellsession -​# Generates a URL like /documentation/sass/style.scss". +​# Generates a URL like "../sass/style.scss". $ sass --source-map-urls=relative sass/style.scss css/style.css ​# Generates a URL like "file:///home/style-wiz/sassy-app/sass/style.scss". @@ -413,7 +371,7 @@ colors if it looks like it's being run on a terminal that supports them. [terminal colors]: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors -
$ sass --color style.scss style.css
+
$ sass --color style.scss style.css
 Error: Incompatible units em and px.
   β•·
 1 β”‚ $width: 15px + 2em
@@ -609,8 +567,7 @@ $ sass --help
 Compile Sass to CSS.
 
 Usage: sass  [output.css]
-       sass :
-       :
+       sass : :
 
 ...
 ```
@@ -623,4 +580,3 @@ This flag prints the current version of Sass.
 $ sass --version
 {{ releases['dart-sass'].version }}
 ```
-{% endmarkdown %}
diff --git a/source/documentation/cli/index.md b/source/documentation/cli/index.md
index bf318bc..2b2f1c0 100644
--- a/source/documentation/cli/index.md
+++ b/source/documentation/cli/index.md
@@ -3,11 +3,10 @@ title: Command-Line Interface
 introduction: >
   Different implementations of Sass have different interfaces when using them
   from the command line:
-overview: true
 ---
 
-- [Dart Sass](/documentation/cli/dart-sass) has the same command-line interface no matter how
-  you [install it](/dart-sass).
+- [Dart Sass](/documentation/cli/dart-sass) has the same command-line interface
+  no matter how you [install it](/dart-sass).
 
 - [Ruby Sass](/documentation/cli/ruby-sass) is [deprecated](/ruby-sass), and we
   recommend you move to a different implementation.
diff --git a/source/documentation/cli/migrator.liquid b/source/documentation/cli/migrator.md
similarity index 91%
rename from source/documentation/cli/migrator.liquid
rename to source/documentation/cli/migrator.md
index 5a740ad..50a1d04 100644
--- a/source/documentation/cli/migrator.liquid
+++ b/source/documentation/cli/migrator.md
@@ -6,43 +6,8 @@ introduction: >
   the latest and greatest version of the language. Each of its commands migrates
   a single feature, to give you as much control as possible over what you update
   and when.
-complementary_content: |
-  
 ---
-{% markdown %}
+
 ## Usage
 
 To use the Sass migrator, tell it [which migration][] you want to run and what
@@ -68,7 +33,7 @@ see what changes will be made without actually saving them, you can pass
 [--dry-run]: #dry-run
 [--verbose]: #verbose
 
-{% include 'code-snippets/example-module-migrator' %}
+{% render 'code-snippets/example-module-migrator' %}
 
 ## Installation
 
@@ -213,7 +178,7 @@ contents.
 
 [`--dry-run` option]: #dry-run
 
-```
+```shellsession
 $ sass-migrator module --verbose --dry-run style.scss
 Dry run. Logging migrated files instead of overwriting...
 <==> style.scss
@@ -294,7 +259,7 @@ before, including:
   [`--migrate-deps` option]: #migrate-deps
 {% endheadsUp %}
 
-{% include 'code-snippets/example-module-migrator' %}
+{% render 'code-snippets/example-module-migrator' %}
 
 #### Loading Dependencies
 
@@ -487,5 +452,3 @@ pass `--force`.
 With `--force`, if any conflicts are encountered, the first `@use` rule will
 get its preferred namespace, while subsequent `@use` rules with the same
 preferred namespace will instead have a numerical suffix added to them.
-
-{% endmarkdown %}
diff --git a/source/documentation/cli/ruby-sass.liquid b/source/documentation/cli/ruby-sass.md
similarity index 90%
rename from source/documentation/cli/ruby-sass.liquid
rename to source/documentation/cli/ruby-sass.md
index 9005b1a..99052e0 100644
--- a/source/documentation/cli/ruby-sass.liquid
+++ b/source/documentation/cli/ruby-sass.md
@@ -1,53 +1,8 @@
 ---
 title: Ruby Sass Command-Line Interface
 table_of_contents: true
-complementary_content: |
-  
 ---
-{% markdown %}
+
 {% headsUp %}
 [Ruby Sass has reached end of life][] and is now totally unmaintained. Please
 switch to [Dart Sass][] or [LibSass][] at your earliest convenience.
@@ -351,7 +306,7 @@ your Sass files in browsers. See instructions for using source maps in
 [`file:` URLs]: https://en.wikipedia.org/wiki/File_URI_scheme
 
 ```shellsession
-​# Generates a URL like "/documentation/sass/style.scss".
+​# Generates a URL like "../sass/style.scss".
 $ sass --sourcemap=auto sass/style.scss css/style.css
 
 ​# Generates a URL like "file:///home/style-wiz/sassy-app/sass/style.scss".
@@ -541,4 +496,3 @@ By default, Sass emits warnings when deprecated features are used or when the
 ```shellsession
 $ sass --quiet style.scss style.css
 ```
-{% endmarkdown %}

From de8ff743068e1c61ef6b95474ecabae41930d190 Mon Sep 17 00:00:00 2001
From: Jonny Gerig Meyer 
Date: Thu, 25 May 2023 16:47:19 -0400
Subject: [PATCH 8/9] no need for quotes

---
 source/documentation/cli/migrator.md | 62 ++++++++++++++--------------
 1 file changed, 32 insertions(+), 30 deletions(-)

diff --git a/source/documentation/cli/migrator.md b/source/documentation/cli/migrator.md
index 50a1d04..6cddb6e 100644
--- a/source/documentation/cli/migrator.md
+++ b/source/documentation/cli/migrator.md
@@ -1,5 +1,5 @@
 ---
-title: "Migrator"
+title: Migrator
 table_of_contents: true
 introduction: >
   The Sass migrator automatically updates your Sass files to help you move on to
@@ -104,14 +104,15 @@ Migrating _grid.scss
 ```
 
 {% headsUp %}
-  The [module migrator][] assumes that any stylesheet that is depended on using
-  a [`@use` rule][] or a [`@forward` rule][] has already been migrated to the
-  module system, so it won't attempt to migrate them, even when the
-  `--migrate-deps` option is passed.
+The [module migrator][] assumes that any stylesheet that is depended on using
+a [`@use` rule][] or a [`@forward` rule][] has already been migrated to the
+module system, so it won't attempt to migrate them, even when the
+`--migrate-deps` option is passed.
+
+[module migrator]: #module
+[`@use` rule]: /documentation/at-rules/use
+[`@forward` rule]: /documentation/at-rules/forward
 
-  [module migrator]: #module
-  [`@use` rule]: /documentation/at-rules/use
-  [`@forward` rule]: /documentation/at-rules/forward
 {% endheadsUp %}
 
 ### `--load-path`
@@ -229,34 +230,35 @@ instead. It doesn't just naΓ―vely change `@import`s to `@use`sβ€”it updates
 stylesheets intelligently so that they keep working the same way they did
 before, including:
 
-* Adding namespaces to uses of members (variables, mixins, and functions) from
+- Adding namespaces to uses of members (variables, mixins, and functions) from
   other modules.
 
-* Adding new `@use` rules to stylesheets that were using members without
+- Adding new `@use` rules to stylesheets that were using members without
   importing them.
 
-* Converting overridden default variables to [`with` clauses][].
+- Converting overridden default variables to [`with` clauses][].
 
   [`with` clauses]: /documentation/at-rules/use#configuration
 
-* Automatically removing `-` and `_` prefixes from members that are used from
+- Automatically removing `-` and `_` prefixes from members that are used from
   other files (because otherwise they'd be considered [private][] and could only
   be used in the module they're declared).
 
   [private]: /documentation/at-rules/use#private-members
 
-* Converting [nested imports][] to use the [`meta.load-css()` mixin][] instead.
+- Converting [nested imports][] to use the [`meta.load-css()` mixin][] instead.
 
   [nested imports]: /documentation/at-rules/import#nesting
   [`meta.load-css()` mixin]: /documentation/modules/meta#load-css
 
 {% headsUp %}
-  Because the module migrator may need to modify both member definitions *and*
-  member names, it's important to either run it with the [`--migrate-deps`
-  option][] or ensure that you pass it all the stylesheets in your package or
-  application.
+Because the module migrator may need to modify both member definitions _and_
+member names, it's important to either run it with the [`--migrate-deps`
+option][] or ensure that you pass it all the stylesheets in your package or
+application.
+
+[`--migrate-deps` option]: #migrate-deps
 
-  [`--migrate-deps` option]: #migrate-deps
 {% endheadsUp %}
 
 {% render 'code-snippets/example-module-migrator' %}
@@ -338,13 +340,13 @@ matches multiple prefixes, the longest matching prefix will be removed.
 This option tells the migrator which members to forward using the [`@forward`
 rule][]. It supports the following settings:
 
-* `none` (the default) doesn't forward any members.
+- `none` (the default) doesn't forward any members.
 
-* `all` forwards all members except those that started with `-` or `_` in the
+- `all` forwards all members except those that started with `-` or `_` in the
   original stylesheet, since that was commonly used to mark a package-private
   member before the module system was introduced.
 
-* `prefixed` forwards only members that begin with the prefix passed to the
+- `prefixed` forwards only members that begin with the prefix passed to the
   [`--remove-prefix` option][]. This option may only be used in conjunction with
   the `--remove-prefix` option.
 
@@ -397,9 +399,9 @@ However, you can also do this to accomplish more complicated renames. For
 instance, say that you previously had a stylesheet that looked like this:
 
 ```scss
-@import "components/button/lib/mixins";
-@import "components/input/lib/mixins";
-@import "components/table/lib/mixins";
+@import 'components/button/lib/mixins';
+@import 'components/input/lib/mixins';
+@import 'components/table/lib/mixins';
 // ...
 ```
 
@@ -407,9 +409,9 @@ Since all of these URLs would have the default namespace `mixins` when migrated
 to `@use` rules, the module migrator may end up generating something like this:
 
 ```scss
-@use "components/button/lib/mixins" as button-lib-mixins;
-@use "components/input/lib/mixins" as input-lib-mixins;
-@use "components/table/lib/mixins" as table-lib-mixins;
+@use 'components/button/lib/mixins' as button-lib-mixins;
+@use 'components/input/lib/mixins' as input-lib-mixins;
+@use 'components/table/lib/mixins' as table-lib-mixins;
 // ...
 ```
 
@@ -421,9 +423,9 @@ If we run the namespace migrator with
 `--rename 'url components/(\w+)/lib/mixins to \1'`, we'll end up with:
 
 ```scss
-@use "components/button/lib/mixins" as button;
-@use "components/input/lib/mixins" as input;
-@use "components/table/lib/mixins" as table;
+@use 'components/button/lib/mixins' as button;
+@use 'components/input/lib/mixins' as input;
+@use 'components/table/lib/mixins' as table;
 // ...
 ```
 

From e0587e493b49be62c721be028aff82b69be7601d Mon Sep 17 00:00:00 2001
From: Jonny Gerig Meyer 
Date: Thu, 25 May 2023 16:49:55 -0400
Subject: [PATCH 9/9] lint

---
 source/documentation/cli/ruby-sass.md | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/source/documentation/cli/ruby-sass.md b/source/documentation/cli/ruby-sass.md
index 99052e0..0a78cf4 100644
--- a/source/documentation/cli/ruby-sass.md
+++ b/source/documentation/cli/ruby-sass.md
@@ -10,6 +10,7 @@ switch to [Dart Sass][] or [LibSass][] at your earliest convenience.
 [Ruby Sass has reached end of life]: /blog/ruby-sass-is-unsupported
 [Dart Sass]: /dart-sass
 [LibSass]: /libsass
+
 {% endheadsUp %}
 
 ## Usage
@@ -24,7 +25,7 @@ sass [input.scss] [output.css]
 
 One-to-one mode compiles a single input file (`input.scss`) to a single output
 location (`output.css`). If no output location is passed, the compiled CSS is
-printed to the terminal. If no input *or* output is passed, the CSS is read from
+printed to the terminal. If no input _or_ output is passed, the CSS is read from
 [standard input][] and printed to the terminal.
 
 [standard input]: https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)
@@ -47,7 +48,7 @@ sass [:] [:] [input.css] [input/]...
 Many-to-many mode compiles one or more input files to one or more output files.
 The inputs are separated from the outputs with colons. It can also compile all
 Sass files in a directory to CSS files with the same names in another directory.
-Many-to-many mode is enabled when any argument contains a colon, *or* when the
+Many-to-many mode is enabled when any argument contains a colon, _or_ when the
 [`--update` flag][] or the [`--watch` flag][] is passed.
 
 [`--update` flag]: #update
@@ -139,11 +140,11 @@ $ sass --compass style.scss style.css
 This option (abbreviated `-t`) controls the output style of the resulting CSS.
 Ruby Sass supports four output styles:
 
-* `nested` (the default) indents CSS rules to match the nesting of the Sass
+- `nested` (the default) indents CSS rules to match the nesting of the Sass
   source.
-* `expanded` writes each selector and declaration on its own line.
-* `compact` puts each CSS rule on its own single line.
-* `compressed` removes as many extra characters as possible, and writes the
+- `expanded` writes each selector and declaration on its own line.
+- `compact` puts each CSS rule on its own single line.
+- `compressed` removes as many extra characters as possible, and writes the
   entire stylesheet on a single line.
 
 ```shellsession
@@ -245,7 +246,7 @@ $ sass --update style.scss
 #### `--force`
 
 This flag (abbreviated `-f`) may only be passed in [many-to-many mode][]. It
-causes Sass files to *always* be compiled to CSS files, instead of only being
+causes Sass files to _always_ be compiled to CSS files, instead of only being
 compiled when the source files are more up-to-date than the output.
 
 The `--force` flag may not be passed alongside the [`--watch` flag][].
@@ -296,12 +297,12 @@ your Sass files in browsers. See instructions for using source maps in
 [Chrome]: https://developers.google.com/web/tools/chrome-devtools/javascript/source-maps
 [Firefox]: https://developer.mozilla.org/en-US/docs/Tools/Style_Editor#Source_map_support
 
-* `auto` (the default) uses relative URLs to link from the source map to the
+- `auto` (the default) uses relative URLs to link from the source map to the
   Sass stylesheets where possible, and absolute [`file:` URLs][] otherwise.
-* `file` always uses absolute absolute `file:` URLs to link from the source map
+- `file` always uses absolute absolute `file:` URLs to link from the source map
   to the Sass stylesheets.
-* `inline` includes the text of the Sass stylehseets in the source map directly.
-* `none` doesn't generate source maps at all.
+- `inline` includes the text of the Sass stylehseets in the source map directly.
+- `none` doesn't generate source maps at all.
 
 [`file:` URLs]: https://en.wikipedia.org/wiki/File_URI_scheme
 
@@ -484,6 +485,7 @@ Traceback (most recent call last):
          1: from /usr/share/gems/sass/lib/sass/scss/parser.rb:1305:in `expected'
 test.scss:1: Invalid CSS after "h1 {font-size: ": expected expression (e.g. 1px, bold), was "}" (Sass::SyntaxError)
 ```
+
 #### `--quiet`
 
 This flag (abbreviated `-q`) tells Sass not to emit any warnings when compiling.