diff --git a/doc-src/content/tutorials/configuration-reference.markdown b/doc-src/content/tutorials/configuration-reference.markdown new file mode 100644 index 00000000..d3a2d1f2 --- /dev/null +++ b/doc-src/content/tutorials/configuration-reference.markdown @@ -0,0 +1,234 @@ +--- +title: Configuration Reference +layout: tutorial +classnames: + - tutorial +--- +# Configuration Reference + +The compass configuration file is a ruby file, which means that we can do some +clever things if we want to. But don’t let it frighten you; it’s really quite +easy to set up your project. + +## Basic format + +Most configuration properties are a simple assignment to a configuration property. +For example: + + css_dir = "stylesheets" + +Most configuration properties have a value that is a “basic” type. There are three +basic types that can be set to a property: + +* **String** – Text is surrounded by either single or double quotes. + E.g. `"this is a string"` +* **Symbol** – A symbol starts with a colon and has no spaces in it. + Symbols are used to represent values where the set of possible values are limited. + E.g. `:foo` or `:foo_bar_baz` +* **Boolean** – `true` or `false` + +There are two kinds of composite values: + +* **Array** – An Array is a comma delimited list of basic values surrounded by + square brackets. E.g. `["one", "two", "three"]`. +* **Hash** – A Hash is an association or mapping of one value to another. + It is a comma delimited list of associations surrounded by curly brackets. + An association is two values separated by `=>`. E.g. `{:foo => "aaa", :bar => "zzz"}` + +## Comments + +Use the hash sign `#` to comment out everything from the hash sign to the end +of the line. + +## Import Note for Windows Users + +The backslash character (`\`) is a special character in a string delimited by +double quotes (`"`). If you are working with folders in your paths, you should +either use **single quotes** to delimit your strings or escape your backslash +by doubling it like `"some\\path"`. + +## Loading Compass Plugins + +Compass relies on the ruby `require` mechanism to load other libraries of code. +To load a compass-compatible plugin, simply require it at the top of your +configuration file. If you used the -r option to access another library at project +creation time, this will already be set up for you. + +Example: + + require 'ninesixty' + require 'susy' + +## Overriding Configuration Settings + +When using the compass command line, configuration options that you set on the +command line will override the corresponding settings in your configuration file. + +## Configuration Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Property NameType Description
project_type Symbol Can be :stand_alone or + :rails. Defaults to :stand_alone. +
environment Symbol The environment mode. + Defaults to :production, can also be :development +
project_path String Not needed in :stand_alone mode + where it can be inferred by context. Sets the path to the root of the project. +
http_path String The path to the project when running within the + web server. Defaults to "/". +
css_dir String The directory where the css stylesheets are kept. + It is relative to the project_path. + Defaults to "stylesheets". +
sass_dir String The directory where the sass stylesheets are kept. + It is relative to the project_path. Defaults to "src". +
images_dir String The directory where the images are kept. + It is relative to the project_path. + Defaults to "images". +
javascripts_dir String The directory where the javascripts are kept. + It is relative to the project_path. Defaults to + "javascripts". +
output_style Symbol The output style for the compiled css. + One of: :nested, :expanded, :compact, + or :compressed. +
relative_assets Boolean Indicates whether the compass helper functions + should generate relative urls from the generated css to assets, or absolute urls + using the http path for that asset type. +
http_images_path String The full http path to images on the web server. + Defaults to http_path + "/" + images_dir. +
http_stylesheets_path String The full http path to stylesheets on the web server. Defaults to http_path + "/" + css_dir.
http_javascripts_path String The full http path to javascripts on the web server. + Defaults to http_path + "/" + javascripts_dir. +
additional_import_paths Array of Strings Other paths on your system from which to import + sass files. See the add_import_path function for a simpler + approach. +
sass_options Hash These options are passed directly to the + Sass compiler. For more details on the format of sass options, please read the + sass options documentation. +
line_comments Boolean Indicates whether line comments should be added + to compiled css that says where the selectors were defined. Defaults to false + in production mode, true in development mode. +
+ +## Configuration Functions + +**`add_import_path`** – Call this function to add a path to the list of sass import +paths for your compass project. E.g.: + + add_import_path "/Users/chris/work/shared_sass" + +--- + +**`asset_host`** – Pass this function a block of code that will define the asset +host url to be used. The block must return a string that starts with a protocol +(E.g. http). The block will be passed the root-relative url of the asset. +For example, this picks one of four asset hosts numbered 0-3, depending on +the name of the asset: + + asset_host do |asset| + "http://assets%d.example.com" % (asset.hash % 4) + end + +By default there is no asset host used. When `relative_assets` is true +the asset host configuration is ignored. + +--- + +**`asset_cache_buster`** – Pass this function a block of code that defines the +cache buster strategy to be used. The block must return nil or a string that can +be appended to a url as a query parameter. The returned string must not include +the starting `?`. The block will be passed the root-relative url of the asset. +If the block accepts two arguments, it will also be passed a path +that points to the asset on disk — which may or may not exist. + + # Increment the deploy_version before every release to force cache busting. + deploy_version = 1 + asset_cache_buster do |http_path, real_path| + if File.exists?(real_path) + File.mtime(real_path).strftime("%s") + else + "v=#{deploy_version}" + end + end