repository·master·Indexed 21 days ago
https://github.com/rails/sass-railsOfficial integration between the Ruby on Rails asset pipeline and the Sass stylesheet language. Includes guidance on installation, configuration of Sass options, using native Sass @import and glob imports, and utilizing asset helpers like asset-path, asset-url, and asset-data-url.
Do NOT use Sprockets directives like require, require_tree, or require_self inside your .sass or .scss files. These are primitive and do not work well with Sass.
Instead, use the native Sass @import directive. sass-rails has customized @import to integrate with Rails project conventions.
In Rails, you can use a special glob import syntax to import files relative to the current stylesheet's folder. This is useful for importing library files (mixins and variables), but use caution with files containing actual styles to avoid unpredictable cascade ordering.
Supported patterns:
@import "mixins/*": Imports all files in the mixins folder.@import "mixins/**/*": Imports all files in the mixins tree.Any valid Ruby glob can be used, and imports are sorted alphabetically.
@import "mixins/*"For new Rails projects (Rails 3.1+), Sass integration is configured by default. If you are upgrading an existing project to Rails 3.1, add the following to your Gemfile:
gem 'sass-rails'You can configure Sass properties by setting config.sass in your application or environment configuration files.
preferred_syntax: Determines the default Sass syntax and file extensions used by Rails generators. Options are :scss (default) or :sass.Note that the following standard Sass options are not supported by sass-rails because they are managed by the Rails environment or Sprockets:
:style (Managed by Rails: :expanded in development, :compressed otherwise):never_update (Use config.assets.enabled = false instead):always_update (Managed by Sprockets):always_check (Managed by Sprockets):syntax (Determined by file extension):filename (Determined by file name):line (Provided by the template handler)MyProject::Application.configure do
config.sass.preferred_syntax = :sass
config.sass.line_comments = false
config.sass.cache = false
endWhen referencing assets in Sass, you must use asset helpers to ensure paths are correctly rewritten by the asset pipeline. Note that Ruby underscores (_) become hyphens (-) in Sass.
asset-path($relative-asset-path): Returns a string path (e.g., asset-path("rails.png") $\rightarrow$ "/assets/rails.png").asset-url($relative-asset-path): Returns a CSS url() reference (e.g., asset-url("rails.png") $\rightarrow$ url(/assets/rails.png)).asset-data-url($relative-asset-path): Returns a Base64-encoded data URL.For convenience, use these specific helpers for different asset types:
image-path() / image-url()font-path() / font-url()video-path() / video-url()audio-path() / audio-url()javascript-path() / javascript-url()stylesheet-path() / stylesheet-url()/* Examples */
.icon {
background-image: image-url("logo.png");
}
.font {
src: font-url("myfont.woff");
}The current version of the sass-rails gem is defined in the Sass::Rails::VERSION constant.
Sass::Rails::VERSION
# => "6.0.0"