pax_global_header00006660000000000000000000000064126514576170014530gustar00rootroot0000000000000052 comment=6c10e82e69d3cb03a487c99bb752485a25a58113 susy-2.2.12/000077500000000000000000000000001265145761700126175ustar00rootroot00000000000000susy-2.2.12/.gitignore000066400000000000000000000002011265145761700146000ustar00rootroot00000000000000susy-*.gem *~ *.DS_Store .sass-cache .rvmrc pkg/ *.sublime-* docs/_build/ bower_components/ node_modules/ Gemfile.lock *.css.map susy-2.2.12/.npmignore000066400000000000000000000001141265145761700146120ustar00rootroot00000000000000**/.* docs pkg bower_components node_modules test Rakefile *.json *.gemspec susy-2.2.12/.travis.yml000066400000000000000000000001251265145761700147260ustar00rootroot00000000000000language: ruby before_script: - npm install -g bower script: "rake" rvm: - 2.0.0 susy-2.2.12/CODE_OF_CONDUCT.md000066400000000000000000000021461265145761700154210ustar00rootroot00000000000000# Susy Contributor Code of Conduct Susy is driven by the community of individuals that power its development and use every day. As a community, we want to embrace the very differences that have made our collaboration so powerful, and work together to provide the best environment for learning, growing, and sharing of ideas. It is imperative that we keep Sass a fun, welcoming, challenging, and fair place to play. As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities. We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality. [The full community guidelines can be found on the Sass website.][link] [link]: http://sass-lang.com/community-guidelines susy-2.2.12/CONTRIBUTING.md000066400000000000000000000062321265145761700150530ustar00rootroot00000000000000Contributing to Susy ==================== Susy exists because of people contributing ideas, code, issues, and sites. Have you built a [site using Susy](http://susy.oddbird.net/sites-using-susy/)? [Add it to the list](https://github.com/oddbird/susysite/tree/master/content/sites-using-susy.rst). We are committed to making participation in this project a harassment-free experience for everyone. Please reference the [contributor code of conduct](CODE_OF_CONDUCT.md) for our contributor expectations. Having issues? -------------- First, try searching for similar questions/answers that are already online. If you don't see anything, let us know. We're always happy to help! If it looks like a bug, post it in the [GitHub issue tracker](https://github.com/oddbird/susy/issues). If you're just looking for advice on creative uses of Susy, maybe [Stack Overflow](http://stackoverflow.com/questions/tagged/susy-sass) is the place for you. Don't worry, we'll field questions posted in either locations. Make sure you explain the context around your problem with code examples, screenshots, or other relevant details. Best if you can provide a simple code sample that recreates the bug consistently. The more you tell us, and the more specific you are, the better we can help. Have an idea? ------------- Susy wouldn't exist in it's current form, without the ideas and feature requests that people have sent in. If you want to do something, and don't see a good way to do it, [please tell us](https://github.com/oddbird/susy/issues) Fix a bug or typo? ------------------ Thanks! Submit a pull request against the `master` branch, and we'll take a look. If you think it might affect the tests, or change functionality in some way, see below. Code a new feature? ------------------- We love getting pull requests from the community. If you have some code, please send us a pull request. It's likely that we'll ask for a few adjustments, but don't take it personally — we often do that to each other as well. We use [Compass](http://compass-style.org) and [True](http://miriamsuzanne.com/true) in development, managed through [bundler](http://bundler.io/), to test Susy and make sure everything is working properly. We wont merge a pull request that breaks the test, or adds a feature that is untested, but you are welcome to submit a work in progress, and we'll help you sort out the details. We'll also ask you to update the docs. When submitting a pull request, consider: - Make sure the tests are up to date and passing - Update the docs - Add your changes to the [changelog](https://github.com/oddbird/susy/blob/master/docs/changelog.rst). Documentation ------------- The docs are written as reStructuredText ([rst](http://docutils.sourceforge.net/rst.html)), and built with [sphinx](http://sphinx-doc.org/). To build them locally: ```bash cd docs pip install -r requirements.txt make html ``` The docs are built into the `_build` directory, as a static site you can open in your browser. Running tests: -------------- ```bash # command line gem install bundler rake test ``` You can also run `compass watch` from the test directory if you want the tests running in the background while you work. susy-2.2.12/Gemfile000066400000000000000000000000631265145761700141110ustar00rootroot00000000000000source "http://rubygems.org" gemspec :path => '.' susy-2.2.12/LICENSE.txt000066400000000000000000000027641265145761700144530ustar00rootroot00000000000000Copyright (c) 2015, Miriam Eric Suzanne All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the author nor the names of other contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. susy-2.2.12/README.md000066400000000000000000000013511265145761700140760ustar00rootroot00000000000000Power Tools For The Web ======================= [![Build Status](https://travis-ci.org/oddbird/susy.png?branch=susy-next)](https://travis-ci.org/oddbird/susy) Susy is an agnostic set of tools for creating powerful, custom layouts. We provide the language, but you provide all the opinions. Use a grid, don't use a grid, or use a combination of grids — it's all up to you. We didn't want to build another system, we wanted to build power tools that you could use in any system. Your markup, your layout | *our math* Resources --------- - [Website](http://susy.oddbird.net/) - [Documentation](http://susydocs.oddbird.net/) - [Sites using Susy](http://susy.oddbird.net/sites-using-susy/) - [Twitter @SassSusy](http://twitter.com/Sasssusy/) susy-2.2.12/Rakefile000066400000000000000000000040461265145761700142700ustar00rootroot00000000000000require 'rubygems/package_task' task :default => :test spec = eval(File.read("susy.gemspec"), binding, "susy.gemspec") def spec.bump! segments = version.to_s.split(".") segments[-1] = segments.last.succ self.version = Gem::Version.new(segments.join(".")) end # Set SAME_VERSION when moving to a new major version and you want to specify the new version # explicitly instead of bumping the current version. # E.g. rake build SAME_VERSION=True spec.bump! unless ENV["SAME_VERSION"] desc "Run tests and build susy-#{spec.version}.gem" task :build => [:test, :gem] desc "Make make the prebuilt gem susy-#{spec.version}.gem public." task :publish => [:record_version, :push_gem, :tag] desc "Build & Publish version #{spec.version}" task :release => [:build, :publish] Gem::PackageTask.new(spec) do |pkg| pkg.need_zip = true pkg.need_tar = true end desc "run the tests" task :test do sh "bundle install --quiet && npm install && cd test && bundle exec sass scss/test.scss css/test.css 2> error.output > /dev/null --force && cd - > /dev/null", :verbose => false open("test/error.output") do |f| if f.read =~ /(.*):\d+.* (\d+) Passed.* (\d+) Failed/ unless $3 == "0" puts File.read("test/css/test.css") fail "#{$3} Tests Failed" else puts "#{$2} Tests Passed" end else raise "unexpected output" end end sh "rm test/error.output", :verbose => false end desc "Record the new version in version control for posterity" task :record_version do unless ENV["SAME_VERSION"] open(FileList["VERSION"].first, "w") do |f| f.write(spec.version.to_s) end sh "git add VERSION bower.json" sh %Q{git commit -am "Bump version to #{spec.version}."} end end desc "Tag the repo as #{spec.version} and push the code and tag." task :tag do sh "git tag -a -m 'Version #{spec.version}' #{spec.version}" sh "git push --tags origin #{`git rev-parse --abbrev-ref HEAD`}" end desc "Push susy-#{spec.version}.gem to the rubygems server" task :push_gem do sh "gem push pkg/susy-#{spec.version}.gem" end susy-2.2.12/VERSION000066400000000000000000000000061265145761700136630ustar00rootroot000000000000002.2.12susy-2.2.12/bower.json000066400000000000000000000006751265145761700146400ustar00rootroot00000000000000{ "name": "susy", "description": "Sass power-tools for web layout.", "authors": [ "Miriam Eric Suzanne " ], "main": "sass/_susy.scss", "homepage": "http://susy.oddbird.net", "keywords": [ "layout", "grid", "sass", "responsive", "rwd", "semantic" ], "license": "BSD-3-Clause", "ignore": [ "**/.*", "docs", "test", "Rakefile", "*.json", "*.gemspec" ] } susy-2.2.12/docs/000077500000000000000000000000001265145761700135475ustar00rootroot00000000000000susy-2.2.12/docs/Makefile000066400000000000000000000151421265145761700152120ustar00rootroot00000000000000# Makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build # User-friendly check for sphinx-build ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) endif # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @echo " pickle to make pickle files" @echo " json to make JSON files" @echo " htmlhelp to make HTML files and a HTML help project" @echo " qthelp to make HTML files and a qthelp project" @echo " devhelp to make HTML files and a Devhelp project" @echo " epub to make an epub" @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" @echo " latexpdf to make LaTeX files and run them through pdflatex" @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" @echo " text to make text files" @echo " man to make manual pages" @echo " texinfo to make Texinfo files" @echo " info to make Texinfo files and run them through makeinfo" @echo " gettext to make PO message catalogs" @echo " changes to make an overview of all changed/added/deprecated items" @echo " xml to make Docutils-native XML files" @echo " pseudoxml to make pseudoxml-XML files for display purposes" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: rm -rf $(BUILDDIR)/* html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." singlehtml: $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." pickle: $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." json: $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." htmlhelp: $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." qthelp: $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Susy.qhcp" @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Susy.qhc" devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @echo "To view the help file:" @echo "# mkdir -p $$HOME/.local/share/devhelp/Susy" @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Susy" @echo "# devhelp" epub: $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." latex: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Run \`make' in that directory to run these through (pdf)latex" \ "(use \`make latexpdf' here to do that automatically)." latexpdf: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." latexpdfja: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through platex and dvipdfmx..." $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." text: $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." man: $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." texinfo: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." @echo "Run \`make' in that directory to run these through makeinfo" \ "(use \`make info' here to do that automatically)." info: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo "Running Texinfo files through makeinfo..." make -C $(BUILDDIR)/texinfo info @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." gettext: $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale @echo @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." linkcheck: $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." xml: $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml @echo @echo "Build finished. The XML files are in $(BUILDDIR)/xml." pseudoxml: $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml @echo @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." susy-2.2.12/docs/changelog.rst000066400000000000000000000636711265145761700162450ustar00rootroot00000000000000Changelog ========= 2.2.11 - Jan 15 2016 -------------------- - Fix bug with `susy-inspect`. 2.2.10 - Jan 7 2016 ------------------- - Add `$pixel-values-only` setting to SusyOne, for turning off Compass `rem` support. 2.2.6 - Sep 1 2015 ------------------ - Fix a bug with overlay grids. - Fix a bug with 0-width split gutters. - Other small bug fixes. 2.2.5 - May 14 2015 ------------------- - Pass grid arguments to overlay positioning mixin. 2.2.3 - Apr 28 2015 ------------------- - Work around libsass fraction bug. 2.2.2 - Jan 23 2015 ------------------- - Fix bug in npm package. 2.2.1 - Jan 14 2015 ------------------- - Release npm ``susy`` package. - Add global ``$susy-media`` map for creating named breakpoints. - Add internal media-query support for ``susy-breakpoint`` without requiring the Breakpoint plugin. - ``susy-breakpoint`` mixin no longer requires ``$layout`` argument. By default, no changes will be made to your existing layout. - Update ``global-box-sizing`` and the legacy ``border-box-sizing`` mixins to optionally take another argument, ``$inherit``. This new argument is a boolean value that defaults to ``false``, meaning the behavior of these mixins will not change by default. The default behavior sets all elements to use the specified ``box-sizing``, which can only be changed explicitly on a per-element basis. By passing in ``$inherit`` as ``true``, the ``box-sizing`` is set on the ``html`` element, and all other elements inherit this property. This means that the ``box-sizing`` can be changed at the component level and all nested elements will inherit this change. This cascading effect can be prevented by explicitly setting ``box-sizing`` on the exceptions within the nested context. - Add ``su`` import at root level. - Both ``su`` and ``susy`` work with the latest LibSass master branch (3.0.2+). There are a few exceptions: + The ``susysone`` syntax + ``overlay`` grid output + The ``inherit`` option for ``global-box-sizing`` & ``border-box-sizing`` 2.1.3 - Jul 16 2014 ------------------- - Baseline grid image uses `px` instead of `%`. - Updated Sass dependency to work with 3.4. 2.1.2 - Apr 28 2014 ------------------- - ``first`` and ``last`` keywords output ``0`` margins instead of ``null`` so they can be used to override previous span settings. - Output ``:before`` / ``:after`` rather than ``::before`` / ``::after`` to support IE8. - Load Susy paths in Compass if required, otherwise add it to SASS_PATH. [`Adrien Antoine `_] - Compass 1.0 config no longer needs to ``require 'susy'``. Susy is registered with Compass automatically. - Add ``$clean`` argument to ``layout`` and ``with-layout`` mixins, for creating new layout contexts from a clean slate. 2.1.1 - Mar 13 2014 ------------------- - Rename core math functions, and prepare for decomposition. + ``column-count()`` => ``susy-count()`` + ``column-sum()`` => ``susy-sum()`` + ``column-span()`` => ``susy-slice()`` + ``column-span-sum()`` => ``susy()`` - Add tests for core math validation. 2.0.0 — Mar 10 2014 ------------------- - New susyone tests for split-columns, is-default-layout, medialayout, columns, relative-width, columns width and nth-of-type (using True). - Sass 3.3.0 (Maptastic Maple) - Rename local 2.0 variables that conflict with global susyone settings. - Susyone container mixin applies full container settings at every breakpoint. 2.0.0.rc.2 — Mar 4 2014 ----------------------- - Fix `templates_path` and compass project templates - Fix Compass "rem" integration to respect ``$rhythm-units`` setting. 2.0.0.rc.1 — Feb 7 2014 ----------------------- - Add browser support module with settings to ``use-custom`` mixins for ``background-image``, ``background-options`` (``-size``, ``-clip``, ``-origin``), ``box-sizing``, ``clearfix``, and ``rem``. If you set to ``false``, we'll make sure everything works well on modern browsers. If you set to ``true``, we'll check for existing mixins (e.g. from Compass or Bourbon) to provide more powerful legacy support. .. code-block: scss $susy: ( use-custom: ( clearfix: false, background-image: true, background-options: false, box-sizing: true, rem: true, ), ); - Fix bugs caused by Sass changes to ``str-index()``, ``#{&}``, and ``@at-root``. - Fix Bower dependencies, and add support for Sache. - Remove legacy Compass polyfils from susyone code. 2.0.0.beta.3 — Jan 10 2014 -------------------------- - Fix a bug making ``show-grid`` unaware of local ``debug/output`` keywords. - Added Susyone syntax for those that need to use the old Susy syntax, with updated Sass and Compass. + ``@import 'susyone';`` 2.0.0.beta.2 — Jan 6 2014 ------------------------- - Allow nesting of Susy settings. - ``show-grid`` mixin can output either background or overlay grids. - Add ``isolate`` function to return isolation offset width. - Fix a bug with ``last`` output for ``split``-gutter layouts. - Fix a bug with split-gutter ``span()``, and ``narrow``/``wider`` keywords. - Fix a bug with ``bleed`` and ``null`` + ``inside`` gutters. - ``bleed`` output uses TRBL shorthand when possible. - Clean up and document the core math functions. - Document upgrade path, core-math, and DIY grids. BREAKING: - Move debug settings into ``$susy: (debug: ());``. - Replace ``show-grid`` setting with new ``debug: image`` setting. - Add ``debug: output`` setting and keywords to toggle between ``background`` and ``overlay`` grid images. - Remove ``grid-overlay`` mixin. + Becomes part of ``show-grid`` mixin. + Doesn't take ``$selector`` argument — should be nested instead. + Can still be used multiple times. - ``isolate`` mixin now interprets span argument as location, unless location is otherwise specified. + ``isolate(2)`` is the same as ``isolate(at 2)``. + ``isolate(25%)`` will isolate *at* ``25%``. - Rename setting controls for consistency. + ``set-grid`` => ``layout`` + ``use-grid`` => ``with-layout`` - ``pad`` and ``squish`` use RL shorthand for shared context. + ``pad(1, 3 of 12)`` => ``pad(1 3 of 12)`` 2.0.0.beta.1 — Dec 24 2013 -------------------------- - Add ``susy-breakpoint`` mixin for basic integration with `Breakpoint`_. + Syntax: ``breakpoint($query, $layout, $no-query)`` where ``$query`` and ``no-query`` follow the Breakpoint syntax, and ``$layout`` uses the Susy syntax for defining grids. - Add ``layout`` function to convert layouts from shorthand syntax to map. - Add ``full`` keyword shortcut for full-width spans. - BREAKING: Remove unclear ``row`` and ``unrow`` mixins. - Add ``break`` and ``nobreak`` mixins/keywords to create a new line before any element in the layout. - BREAKING: Rename ``is-container: container`` setting/value to ``role: nest``. - BREAKING: Rename ``layout-method`` setting to ``output``. - BREAKING: Rename ``layout-math`` setting to ``math``. - Clean up division between math/output/syntax layers. - ``gutters`` and ``container-position`` can be set to ``null``. - If ``gutters`` are set to ``0`` or ``null``, they will have no output. - BREAKING: ``full`` output matches span patterns. - BREAKING: Debug grids are hidden by default. - BREAKING: Remove ``nth-last``/``-omega``/``-first``/``-alpha`` as confusing & out-of-scope. Format your nth-selectors manually to apply ``first``/``last`` mixins. - Gutter mixins/functions can accept context-only (without the "of" syntax): + ``gutters(of 10 .25)`` == ``gutters(10 .25)`` + Unitless numbers are used for context. + Lengths (with units) are used as explicit gutter-overrides. - BREAKING: Re-purposed ``susy-set`` as reverse of ``susy-get`` — to adjust a single setting. Example: ``@include susy-set(gutter-position, inside);`` - Replace global ``box-sizing`` setting with ``global-box-sizing``. + Let Susy know what box model you are using globally. + ``box-sizing`` can still be passed as a keyword argument. - Add ``global-box-sizing()`` mixin to set your global box model. + Example: ``@include global-box-sizing(border-box);`` + You can still use the legacy ``@include border-box-sizing;`` as a shortcut. + Uses your global setting as a default. + Updates your global setting to match, if you pass a different value. - ``gallery`` and ``span`` mixins take global-box-sizing into account. .. _Breakpoint: http://breakpoint-sass.com/ 2.0.0.alpha.6 — Dec 5 2013 -------------------------- - Rewrite syntax parsing so parser and resulting maps are shared across Susy. - Fix explicit-span bug causing large gutters. - Padding mixins now respect inside gutters. Backwards Incompatible: - Removed ``gutters $n`` keyword in shorthand syntax for setting explicit gutters. Use ``(gutter-override: $n)`` map instead. 2.0.0.alpha.5 — Nov 25 2013 --------------------------- - Compass is no longer a dependency. + Only registers as a compass extension if compass is present. - Any mixin/function that accepts natural language syntax also accepts maps. - Maps and natural language can be mixed: + ``$large: (columns: 12, gutters: .5);`` + ``span(3 $large no-gutters)`` - Add ``full`` mixin for full-width spans. Backwards Incompatible: - Requires Sass 3.3 - Default settings are handled with a Sass map on the ``$susy`` variable. Example: ``$susy: (columns: 12, gutters: .25)`` etc. - ``bleed`` now takes standard span syntax, with multiple (TRBL) spans. + e.g. ``bleed(1em 2 of 8)`` for 1em top/bottom and 2-columns left/right. + Add ``bleed-x``/``bleed-y`` mixins for horizontal and vertical shortcuts. - Span arguments now accept ``narrow``, ``wide``, or ``wider`` keywords. + The ``wide`` keyword replaces the old ``outer`` keyword. + This setting has been re-named from ``outer`` to ``spread``. - Re-wrote grid debugging + More concise & accurate output for symmetrical grids. + Changed ``grid-background()`` to ``show-grid()``/``show-grids()`` + Changed ``overlay-grid()`` to ``grid-overlay()`` + Moved settings into ``$debug: (color: rgba(#66f, .25), toggle: top right);`` + Removed overlay-position setting. + Only display vertical-rhythms when ``$base-line-height`` is available. - ``split`` gutters are no longer removed at the grid edges. + ``first`` and ``last`` are not special cases for split gutter-handling. + pass the ``container`` argument to wrappers you plan to nest inside. - ``first``/``alpha``/``last``/``omega``/``nth-`` mixins require grid context. 2.0.0.alpha.4 — Sept 4 2013 --------------------------- - Add ``bleed`` mixin. - Fix bug with fluid inside-gutter calculations. - ``$last-flow`` setting controls the flow direction of row-ending elements. - ``background-grid-output`` now accepts ``$line-height`` argument. - Compass modules are imported as needed. - ``grid-background``, ``grid-overlay``, ``grid-background-output``, & ``$grid-background-color`` have been renamed to remiain consistent and avoid conflicts with Compass: + ``grid-background`` => ``background-grid`` + ``grid-overlay`` => ``overlay-grid`` + ``grid-background-output`` => ``background-grid-output`` + ``$grid-background-color`` => ``$grid-color`` - ``span`` mixing accepts nested ``@content``, and uses nested context. - Add ``inside-static`` option for static gutters in otherwise fluid grids. - ``gutters`` mixin uses span syntax, accepts explicit gutter span. - Explicit gutter-overrides are divided when gutters are ``split``/``inside``. 2.0.0.alpha.3 — July 9 2013 --------------------------- - ``row`` now includes clearfix, and ``unrow`` removes clearfix. - ``gallery`` output should override previous gallery settings. - Removed ``nth-gallery`` and ``isolate-gallery`` in favor of single, isolated ``gallery`` mixin. - Add padding-span syntax: ``prefix``, ``suffix``, and ``pad``. - Add margin-span syntax: ``pre``, ``post``, ``push``, ``pull``, and ``squish``. - New ``gutters`` mixin adds gutters to an element. - ``gutter`` function now returns half-widths when using split/inside gutters. - Add ``outer`` keyword to ``span`` syntax, to return span-width including gutters. + Works with both span mixin and span function. + Replaces Susy 1.0 ``space`` function. - Add comrehensive unit tests, using `True`_. - Improve fall-abck handling of ommitted arguments. - Add ``container`` function to return a given container's width. - Add ``auto`` keyword to override ``$container-width``, otherwise respect existing width. - Renamed ``$isolate`` to ``$layout-method`` + No longer accepts boolean. + Accepts keywords ``isolate`` and (default) ``float``. - Renamed ``$static`` to ``$layout-math`` + No longer accepts boolean. + Accepts keywords ``static`` (use given units) and (default) ``fluid`` (use % units). - Add ``show-columns`` and ``show-baseline`` keywords to ``$show-grids`` setting. ``show`` will show both columns/baseline, default is ``show-columns``. .. _True: http://miriamsuzanne.com/true/ 2.0.0.alpha.2 — May 7 2013 -------------------------- - Added ``gutter ``/``gutters `` to override the attached gutter width on a single span. NOTE: ``gutters 0`` is not the same as ``no-gutters``. ``0`` is an output value, ``no-gutters`` removes output. - Added ``container`` span option to remove inside gutters from nesting containers. - Added ``before``/``after``/``split``/``inside``/``no-gutters`` gutter options. - Added ``gallery`` mixin for auto-generating gallery layouts. - Moved grid-backgrounds into language layer, and made them syntax-aware. - Added ``row``/``unrow``, ``first``/``last``, ``alpha``/``omega``, ``nth-first``/``nth-last``, and ``nth-alpha``/``nth-omega``. - Added ``container`` and ``span`` mixins with new syntax. - Added syntax-aware math functions (``span``/``gutter``/``outer-span``). - Added rough ``translate-susy1-settings`` mixin. - Moved syntax-specific math into language layer. - Fleshed-out new language syntax. - Added ``get-grid``, ``set-grid``, and ``use-grid`` and declaring and managing settings. - Remove breakpoint core requirement (will come back as option) 2.0.0.alpha.1 — Jan 26 2013 --------------------------- **Susy 2.0 was re-written from the ground up.** - Functioning math engine - Initial string parsing for natural syntax - Float/Isolation output methods - Removed all ECHOE/RAKE stuff in favor of vanilla .gemspec - Added Ruby based String Split function - Added Sass based ``grid-add`` function, to add grids à la Singularity - Added default variables 1.0.5 — Nov 27 2012 ------------------- - Add support for rem-units. - Clean-up quoted arguments. - Fix a few bugs related to the override settings. 1.0.4 — Nov 3 2012 ------------------- - Fix bug in nested mixins that adjust support (e.g. ``nth-omeg`` inside ``at-breakpoint``). - Remove non-ie experimental support in ``at-breakpoint`` ie-fallback output. 1.0.3 — Oct 20 2012 ------------------- - Fix Compass dependencies. 1.0.2 — Oct 20 2012 ------------------- - Fix a bug with ``container-outer-width`` ignoring ``$columns`` argument. - Turn off legacy-ie support inside CSS3 selectors (``nth-omega`` etc). 1.0.1 — Sept 12 2012 -------------------- - Fix a bug in the relationship between ``$container-width`` and ``$border-box-sizing``, so that grid-padding is subtracted from the width in certain cases. - Reset right margin to ``auto`` rather than ``0`` with ``remove-omega``. 1.0 — Aug 14 2012 ----------------- This release is loaded with new features, but don't let that fool you. Susy just became shockingly simple to use. The gem name has changed from ``compass-susy-plugin`` to ``susy``. First uninstall the old gem, then install the new one. If you have both gems installed, you will get errors. Semantics: We re-arranged the code in order to make the syntax simpler and more consistent: - ``$total-cols`` is now ``$total-columns``. - ``$col-width`` is now ``$column-width``. - ``$side-gutter-width`` is now ``$grid-padding`` and gets applied directly to the grid container. - ``un-column`` & ``reset-column`` mixins have merged into ``reset-columns``. - ``columns`` has been renamed ``span-columns`` to resolve the conflict with CSS3 columns. See other improvements to span-columns below. We also removed several bothersome requirements: - The ``alpha`` mixin is no longer needed. Ever. - The ``omega`` no longer takes a ``$context`` argument. - ``full`` has been removed entirely. Elements will be full-width by default. You can add ``clear: both;`` back in as needed. - ``side-gutter()`` is no longer needed. You can use the ``$grid-padding`` setting directly. Upgrade: That's all you need in order to upgrade from Susy 0.9. 1. Uninstall and re-install the gem. 2. Find and replace the semantic changes listed above. You're done! Stop worrying about all that "nested vs. root" bullshit, and start playing with the new toys! If you use the ``$from`` directional arguments directly in the ``span-columns`` mixin, there may be one more change to make. See below: New Features: - ``span-columns`` supports new features: + "omega" can be applied directly through the ``$columns`` argument. + Internal padding can be added through the ``$padding`` argument. + This pushes the ``$from`` argument from third position into fourth. - ``at-breakpoint`` allows you to change layouts at media breakpoints. - ``container`` accepts multiple media-layout combinations as a shortcut. - ``layout`` allows you to use a different layout at any time. - ``with-grid-settings`` allows you to change any or all grid settings. - ``set-container-width`` does what it says, without the other container code. - ``$breakpoint-media-output``, ``$breakpoint-ie-output``, and ``$breakpoint-raw-output`` settings help manage the different outputs from ``at-breakpoint`` when you have IE-overrides living in a file of their own. - ``border-box-sizing`` will apply the popular ``* { box-sizing: border-box }`` universal box-model fix, as well as changing the Susy ``$border-box-model`` setting for you, so Susy knows to adjust some math. - The ``space()`` function can be used anywhere you need column+gutter math. - ``push``/``pull``/``pre``/``post``/``squish`` mixins help manage margins. - use the ``nth-omega`` mixin to set omega on any nth-child, nth-of-type, first, last, or only element. - ``remove-omega`` and ``remove-nth-omega`` will remove the omega-specific styles from an element. - ``$container-width`` will override the width of your container with any arbitrary length. - ``$container-style`` will override the type of grid container (magic, fluid, fixed, static, etc) to use. 0.9 — Apr 25 2011 ----------------- Everything here is about simplicity. Susy has scaled back to it's most basic function: providing flexible grids. That is all. Deprecated: - The ``susy/susy`` import is deprecated in favor of simply importing ``susy``. - The ``show-grid`` import is deprecated in favor of CSS3 gradient-based grid-images. You can now use the ``susy-grid-background`` mixin. See below. Removed: - Susy no longer imports all of compass. - Susy no longer establishes your baseline and no longer provides a reset. All of that is in the Compass core. You can (and should!) keep using them, but you will need to import them from compass. New: - Use ``susy-grid-background`` mixin on any ``container`` to display the grid. This toggles on and off with the same controls that are used by the compass grid-background module. 0.9.beta.3 — Mar 16 2011 ------------------------ Deprecated: - The ``susy/reset`` import has been deprecated in favor of the Compass core ``compass/reset`` import. - The ``susy`` mixin has been deprecated. If you plan to continue using vertical-rhythms, you should replace it with the ``establish-baseline`` mixin from the Compass Core. Removed: - The ``vertical-rhythm`` module has moved into compass core. The API remains the same, but if you were importing it directly, you will have to update that import. (``$px2em`` was removed as part of this, but didn't make it into core). - The ``defaults`` template has been removed as 'out-of-scope'. This will not effect upgrading in any way, but new projects will not get a template with default styles. New Features: - Susy now supports RTL grids and bi-directional sites using the ``$from-direction`` variable (default: left) and an optional additional from-direction argument on all affected mixins. Thanks to @bangpound for the initial implementation. - Susy is now written in pure Sass! No extra Ruby functions included! Thanks to the Sass team for making it possible. 0.8.1 — Sep 24 2010 ------------------- - Fixed typos in tutorial and ``_defaults.scss`` 0.8.0 — Aug 13 2010 ------------------- Deprecated: - The ``skip-link`` was deprecated as it doesn't belong in Susy. - All the IE-specific mixins have been deprecated, along with the ``$hacks`` variable. Hacks are now used in the default mixins as per Compass. - The ``hide`` mixin was deprecated in favor of the Compass ``hide-text`` mixin. Other Changes: - ``inline-block-list`` will be moved to the compass core soon. In preparation, I've cleaned it up some. You can now apply a padding of "0" to override previous padding arguments. You can also use ``inline-block-list-container`` and ``inline-block-list-item`` as you would with the Compass ``horizontal-list`` mixins. - The ``$align`` arguments have been removed from both the ``susy`` and ``container`` mixins. Text-alignment is no longer used or needed in achieving page centering. That was a cary-over from the IE5 Mac days. - The ``container`` mixin now uses the ``pie-clearfix`` compass mixin to avoid setting the overflow to hidden. - Default styles have been cleaned up to account for better font stacks and typography, html5 elements, vertically-rhythmed forms, expanded print styles, use of ``@extend``, and overall simplification. 0.7.0 — Jun 01 2010 ------------------- - updated documentation 0.7.0.rc2 — May 13 2010 ----------------------- - Fixes a bug with grid.png and a typo in the readme. Nothing major here. 0.7.0.rc1 — May 12 2010 ----------------------- - template cleanup & simplification - no more pushing CSSEdit comments, etc. - expanded base and defaults with better fonts & styles out-of-the-box - expanded readme documentation. This will expand out into a larger docs/tutorial site in the next week. 0.7.0.pre8 — Apr 20 2010 ------------------------ - mostly syntax and gem cleanup - added ``un-column`` mixin to reset elements previously declared as columns. - added ``rhythm`` mixin as shortcut for leaders/trailers. accepts 4 args: leader, padding-leader, padding-trailer, trailer. - added a warning on ``alpha`` to remind you that ``alpha`` is not needed at nested levels. 0.7.0.pre7 — Apr 13 2010 ------------------------ - *Requires HAML 3 and Compass 0.10.0.rc2* - Internal syntax switched to scss. This will have little or no effect on users. You can still use Susy with either (Sass/Scss) syntax. - ``$default-rhythm-border-style`` overrides default rhythm border styles - Better handling of sub-pixel rounding for IE6 0.7.0.pre6 — Mar 29 2010 ------------------------ - Added ``+h-borders()`` shortcut for vertical_rhythm ``+horizontal-borders()`` - Fixed vertical rhythm font-size typo (thanks @oscarduignan) - Added to template styles, so susy is already in place from the start 0.7.0.pre5 — Mar 19 2010 ------------------------ - Expanded and adjusted ``_vertical_rhythm.sass`` in ways that are not entirely backwards compatible. Check the file for details. - ``_defaults.sass`` is re-ordered from inline to block. - ``:focus`` defaults cleaned up. - README and docs updated. 0.7.0.pre4 — Jan 20 2010 ------------------------ Update: pre2 was missing a file in the manifest. Use pre4. *Update:* Forgot to note one change: ``+susy`` is no longer assigned to the ``body`` tag, but instead at the top level of the document (not nested under anything). Warning: This update is not backwards compatible. We've changed some things. You'll have to change some things. Our changes were fairly major in cleaning up the code - yours will be minor and also clean up some code. Added: - new ``_vertical_rhythm.sass`` (thanks to Chris Eppstein) provides better establishing of the baseline grid, as well as mixins to help you manage it. - ``!px2em`` has replaced ``px2em()`` - see below. Removed: - ``px2em()`` has been removed and replaced with a simple variable ``!px2em`` which returns the size of one pixel relative to your basic em-height. Multiply against your desired px dimensions (i.e. ``border-width = !px2em*5px`` will output the em-equivalent of 5px). - ``!base_font_size_px`` and ``!base_line_height_px`` have been replaced with ``!base_font_size`` and ``!base_line_height`` which take advantage of sass's built-in unit handling. - ``!grid_units`` is not needed, as you can now declare your units directly in the other grid ``_width`` variables. Use any one type of units in declaring your grid. The units you use will be used in setting the container size. Once you've upgraded, before you compile your files, make these changes: - remove the "_px" from the font-size and line-height variables, and add "px" to their values. - remove the ``!grid_units`` variable and add units to your grid variable values. - find any uses of ``px2em()`` and replace them with something. - enjoy! 0.7.0.pre1 — Nov 30 2009 ------------------------ Not a lot of new functionality here – it all moved over to Compass 0.10.0 – mostly just cleaning it up to match. - simplified the default styles and gave them their own project template (``_defaults.sass``). - defaults not imported by ``ie.sass``, as ``ie.sass`` should be cascading on top of ``screen.sass`` anyway - changed the syntax to match CSS and Compass (``property:`` replaces ``:property``) - added more inline documentation and brought tutorial up to date - moved CSS3 module over to Compass - import the compass HTML5 reset along with the normal reset by default (because Susy loves the future) - little internal management fixes and so on and so on… Older ----- Not documented here. Check the commit log... susy-2.2.12/docs/conf.py000066400000000000000000000204251265145761700150510ustar00rootroot00000000000000# -*- coding: utf-8 -*- # # Susy documentation build configuration file, created by # sphinx-quickstart on Wed Dec 11 12:58:59 2013. # # This file is execfile()d with the current directory set to its # containing dir. # # Note that not all possible configuration values are present in this # autogenerated file. # # All configuration values have a default; values that are commented out # serve to show the default. import sys import os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. #sys.path.insert(0, os.path.abspath('.')) # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. #needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' # The encoding of source files. #source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' # General information about the project. project = u'Susy' copyright = u'2015 | Miriam Eric Suzanne' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. version = '2.2' # The full version, including alpha/beta/rc tags. release = '2.2.12' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: #today = '' # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = ['_build'] # The reST default role (used for this markup: `text`) to use for all # documents. #default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. #add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). #add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. #show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] # If true, keep warnings as "system message" paragraphs in the built documents. #keep_warnings = False # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org on_rtd = os.environ.get('READTHEDOCS', None) == 'True' if not on_rtd: import sphinx_rtd_theme html_theme = 'sphinx_rtd_theme' html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". #html_title = None # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. #html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. #html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". # html_static_path = ['_static'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. #html_extra_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. #html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. #html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. #html_additional_pages = {} # If false, no module index is generated. #html_domain_indices = True # If false, no index is generated. #html_use_index = True # If true, the index is split into individual pages for each letter. #html_split_index = False # If true, links to the reST sources are added to the pages. #html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. #html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. #html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. #html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). #html_file_suffix = None # Output file base name for HTML help builder. htmlhelp_basename = 'Susydoc' # -- Options for LaTeX output --------------------------------------------- latex_elements = { # The paper size ('letterpaper' or 'a4paper'). #'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). #'pointsize': '10pt', # Additional stuff for the LaTeX preamble. #'preamble': '', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ ('index', 'Susy.tex', u'Susy Documentation', u'Miriam Eric Suzanne and contributors', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of # the title page. #latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. #latex_use_parts = False # If true, show page references after internal links. #latex_show_pagerefs = False # If true, show URL addresses after external links. #latex_show_urls = False # Documents to append as an appendix to all manuals. #latex_appendices = [] # If false, no module index is generated. #latex_domain_indices = True # -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'susy', u'Susy Documentation', [u'Miriam Eric Suzanne and contributors'], 1) ] # If true, show URL addresses after external links. #man_show_urls = False # -- Options for Texinfo output ------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ ('index', 'Susy', u'Susy Documentation', u'Miriam Eric Suzanne and contributors', 'Susy', 'One line description of project.', 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. #texinfo_appendices = [] # If false, no module index is generated. #texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False susy-2.2.12/docs/diy.rst000066400000000000000000000157011265145761700150720ustar00rootroot00000000000000DIY Susy ======== Susy is built in three distinct modules: math, output, and syntax. The math and output layers form the core of Susy — so abstract that they could be used for any grid system. That's exactly what we hope will happen. The syntax modules hold it all together. In the same way that you can theme a website, applying different CSS to the same markup, you can theme Susy by writing your own syntax (or extending one of ours). We've written a powerful new :doc:`Default Syntax `, and we're keeping the old :doc:`susyone` available as well. But why stop there? You can *create your own unique syntax*, or port over the language of existing tools like `oocss`_, `singularity`_, `zurb`_, `neat`_, `zen`_, `blueprint`_, `960gs`_, etc., without ever leaving Susy. .. _oocss: http://oocss.org/ .. _singularity: http://singularity.gs/ .. _zurb: http://foundation.zurb.com/ .. _neat: http://neat.bourbon.io/ .. _zen: http://zengrids.com/ .. _blueprint: http://www.blueprintcss.org/ .. _960gs: http://960.gs/ ------------------------------------------------------------------------- .. _core-settings: Core Settings ------------- While the Susy language module is built to support layouts of all kinds, we only need the math module for grid basics. The Susy core has two settings: :ref:`columns `, and :ref:`gutters `. .. code-block:: scss $symmetrical: ( columns: 12, gutters: 1/4, ); $asymmetrical: ( columns: (1 3 4 6 2), gutters: .5, ); Both ``columns`` and ``gutters`` are set as unitless numbers, but you can think of them as "grid units" — as they are all relative to each other. ``1/4`` gutter is a quarter the size of ``1`` column. ------------------------------------------------------------------------- .. _core-is-symmetrical: Is Symmetrical -------------- Returns ``null`` if a grid is asymmetrical. - ``$columns``: ```` | ```` It's not a difficult test, but it's important to know what you're dealing with. .. code-block:: scss // input $sym: is-symmetrical(12); $asym: is-symmetrical(2 4 6 3); // output $sym: 12; $asym: null; ------------------------------------------------------------------------- .. _core-susy-count: Susy Count ---------- Find the number of columns in a given layout. - ``$columns``: ```` | ```` This is only necessary for asymmetrical grids, since symmetrical are already defined by their count, but the function handles both styles for the sake of flexibility. 1. ````: Susy grid layouts are defined by columns. In a symmetrical grid all the columns are the same relative width, so they can be defined by the number of columns. We can have an "8-column" grid, or a "12-column" grid. .. code-block:: scss // input $count: susy-count(12); // output $count: 12; 2. ````: Asymmetrical grids are more complex. Since each column can have a different width relative to the other columns, we need to provide more detail about the columns. We can do that with a list of relative (unitless sizes). Each number in the list represents a number of grid units relative to the other numbers. .. code-block:: scss // input $count: susy-count(1 2 4 3 1); // output $count: 5; For asymmetrical grids, the number of columns is egual to the list length. This isn't complex math. ------------------------------------------------------------------------- .. _core-susy-sum: Column Sum ---------- Find the total sum of column-units in a layout. - ``$columns``: ```` | ```` - ``$gutters``: ```` - ``$spread``: ``false``/``narrow`` | ``wide`` | ``wider`` Rather than counting how many columns there are, the ``susy-sum`` function calculates the total number of grid units covered. It's a simple matter of adding together all the columns as well as the gutters between them. .. code-block:: scss // input $susy-sum: susy-sum(7, .5); // output: 7 + (6 * .5) = 10 $susy-sum: 10; Most grids have one less gutter than column, but that's not always true. The ``spread`` argument allows you to also include the gutters on either side. While the default ``narrow`` spread subtracts a gutter, the ``wide`` spread (common when using split gutters) has an equal number of columns and gutters. .. code-block:: scss // input $wide-sum: susy-sum(7, .5, wide); // output: 7 + (7 * .5) = 10.5 $wide-sum: 10.5; On rare occasions you may actually want gutters on both sides, which we call a ``wider`` spread. .. code-block:: scss // input $wider-sum: susy-sum(7, .5, wider); // output: 7 + (8 * .5) = 11 $wider-sum: 11; This is all possible with asymmetrical grids as well. .. code-block:: scss // input $susy-sum: susy-sum(1 2 4 2, 1/3); // output: (1 + 2 + 4 + 2) + (3 * 1/3) = 10 $susy-sum: 10; ------------------------------------------------------------------------- .. _core-susy-span: Column Span ----------- Return a subset of columns at a given location. - ``$span``: ```` - ``$location``: ```` - ``$columns``: ```` | ```` This is only necessary for asymmetrical grids, since a symmetrical subset is always equal to the span, but the function handles both styles for the sake of flexibility. The ``location`` is given as a column index, starting with 1, so that ``1`` is the first column, ``2`` is the second, and so on. .. code-block:: scss // input $sym-span: susy-span(3, 2, 7); $asym-span: susy-span(3, 2, (1 2 3 5 4)); // output: 3 columns, starting with the second $sym-span: 3; $asym-span: (2 3 5); ------------------------------------------------------------------------- .. _core-susy: Susy ---- Find the sum of given slice. - ``$span``: ```` - ``$location``: ```` - ``$columns``: ```` | ```` - ``$gutters``: ```` - ``$spread``: ``false``/``narrow`` | ``wide`` | ``wider`` This is where it all comes together. ``susy`` is the basic building-block for any grid system. It combines ``susy-span`` with ``susy-sum`` to return the unitless width of a given slice. .. code-block:: scss // input $sym-span: susy(3, 2, 7, .5); $asym-span: susy(3, 2, (1 2 3 5 4), .5); // output $sym-span: 4; $asym-span: 11; All you need to do is add units... ------------------------------------------------------------------------- .. _core-diy: Build Something New ------------------- That's really all it takes to build a grid system. The rest is just syntax. Start with ``susy()``. .. code-block:: scss $sum: susy(3, 2, 7); If you want static grids, you can multiply the results by the width of one column. .. code-block:: scss // static $column-width: 4em; $static: $sum * $column-width; For a fluid grid, divide the results by the context span sum, to get a percentage. .. code-block:: scss // fluid $context: susy(7); $fluid: percentage($sum / $context); That's all it takes. Now go build yourself a grid system! susy-2.2.12/docs/index.rst000066400000000000000000000030741265145761700154140ustar00rootroot00000000000000Susy |release| ============== In a world of agile development and super-tablet-multi-magic-laptop-phones, the best layouts can’t be contained in a single framework or technique. CSS Libraries are a bloated mess of opinions about how to do your job. Why let the table-saw tell you where to put the kitchen? Your markup, your design, your opinions | *our math*. .. note:: These docs are focused on Susy |release|. See the :doc:`susyone` documentation for help with earlier versions of Susy. Contents -------- .. toctree:: :maxdepth: 1 install settings shorthand toolkit susyone upgrade diy changelog ToDo ---- These are the features we're working on next: - Add IE support to new syntax. - Move SusyOne syntax onto new math/output modules. - Add padding/margin options to the ``span`` mixin, for simpler output. We're always happy to hear your ideas as well. Leave us a note on `GitHub Issues`_, or fork our code, and submit a pull request! .. _GitHub Issues: https://github.com/oddbird/susy/issues .. note:: This isn't neverland, and Susy isn't magic. We're still talking about web design in a world where browsers disagree on implementation, standards are not always the standard, and your Sass code compiles into Boring Old CSS. Don't rely on Susy to solve all your problems — the table-saw can't build your house for you. If you don't understand what Susy is doing, take a look at the output CSS files, dig around, and find your own path. Nothing here is sacred, just a set of tools to help make your life easier. susy-2.2.12/docs/install.rst000066400000000000000000000136751265145761700157630ustar00rootroot00000000000000Getting Started =============== The only requirement is `Sass`_, but Susy was built to be part of the `Compass`_ ecosystem, and we recommend pairing with tools like `Breakpoint`_ and `Vertical Rhythms`_. Compass is still required for the :doc:`susyone` syntax. .. _Sass: http://sass-lang.com/ .. _Compass: http://compass-style.org/ .. _Breakpoint: http://breakpoint-sass.com/ .. _Vertical Rhythms: http://compass-style.org/reference/compass/typography/vertical_rhythm/ Simple Install -------------- .. code-block:: bash # command line gem install susy Bundler or Rails ---------------- .. warning:: In order to use Susy 2 with Rails you must update your Gemfile to use sass-rails ~> 5.0.0. This is because Susy 2 requires Sass >= 3.3 whilst Rails 4.1 and below include a version of sass-rails which does not support Sass 3.3. .. code-block:: ruby # Gemfile # gem 'sass-rails', '~> 4.0.3' gem 'sass-rails', '~> 5.0.0' gem 'susy' # If you want Compass: gem 'compass-rails', '~> 2.0.0' .. code-block:: ruby # config/application.rb require 'susy' .. code-block:: bash # command line bundle install .. _Bundler: http://bundler.io/ .. _Rails: http://rubyonrails.org/ If you add Susy to an existing Rails app, follow the steps above, but use bundle update instead of bundle install. .. code-block:: bash # command line bundle update Compass ------- If you want to use Susy with `Compass`_, start by `installing Compass`_. Create a new Compass project: .. code-block:: bash # command line compass create --using susy Alternatively, add Susy to a current project .. code-block:: bash # command line compass install susy .. _Compass: http://compass-style.org/ .. _installing Compass: http://compass-style.org/install/ Bower ----- .. code-block:: bash # command line bower install susy --save This will add the Susy repository to your ``bower_components`` directory or create a ``bower_components`` directory for you. .. code-block:: scss // Import Susy @import "bower_components/susy/sass/susy"; You can also import Susyone. .. code-block:: scss // Import Susy @import "bower_components/susy/sass/susyone"; Grunt (and Yeoman) ------------------ You can enable Susy in Grunt by adding a line to your ``Gruntfile.js``. You will need to add a line to either your Sass task or, if you're using Compass, your Compass task. To add Susy to the Sass task, edit your Gruntfile.js at the root level of your project and look for the Sass-related rules. Add ``require: 'susy'`` inside the ``options`` object: .. code-block:: js // Gruntfile.js sass: { dist: { options: { style: 'expanded', require: 'susy' }, files: { 'css/style.css': 'scss/style.scss' } } } Assuming you've already installed Susy, it will now be added to the project and will not clash with Yeomans grunt rules. To add Susy to the Compass task, edit your Gruntfile.js at the root level of your project and look for the Compass-related rules. Add ``require: 'susy'`` inside the ``options`` object: .. code-block:: js // Gruntfile.js compass: { options: { require: 'susy', ... } } } Again, assuming you've already installed Susy, it will now be added to the project. Webpack and npm --------------- Install using npm: .. code-block:: bash npm install susy sass-loader --save-dev Make sure you have `sass-loader `_ enabled in your `webpack` configuration: .. code-block:: js // webpack.config.js loaders: [ { test: /\.scss$/, loader: 'style!css!sass' } ] Start using Susy: .. code-block:: sass /* app.scss */ @import "~susy/sass/susy"; Manual Start ------------ If you want to copy in the Sass files directly, and skip any package management, you can do that too. - Download the zip file from GitHub. - Copy the contents of the "sass" folder (feel free to remove everything else). - Paste the files in your project "sass" folder (whatever you call it). Version Management ------------------ When you work with bundled gems across a number of different projects, managing gem versions can become an issue. If you are in a Ruby environment, check out `RVM`_. In a Python environment, we recommend `virtualenv`_ with these `scripts`_ added to your "postactivate" and "predeactivate" files. Once you have that in place, `Bundler`_ can be used in either environment to manage the actual installation and updating of the gems. .. _RVM: https://rvm.io/ .. _virtualenv: http://www.virtualenv.org/en/latest/index.html .. _scripts: https://gist.github.com/1078601 Quick Start ----------- Once you have everything installed, you can import Susy into your Sass files. .. code-block:: scss @import "susy"; The basic Susy layout is composed using two simple mixins: .. code-block:: scss @include container; // establish a layout context @include span(); // lay out your elements For example: .. code-block:: scss body { @include container(80em); } nav { @include span(25%); } If you want to lay your elements out on a grid, you can use the ``span`` mixin to calculate column widths: .. code-block:: scss nav { @include span(3 of 12); } But you don't have to do things the Susy way. We give you direct access to the math, so you can use it any way you like: .. code-block:: scss main { float: left; width: span(4); margin-left: span(2) + gutter(); margin-right: gutter(); } You can also establish :doc:`global settings `, to configure Susy for your specific needs. Create a ``$susy`` variable, and add your settings as a map. .. code-block:: scss $susy: ( columns: 12, // The number of columns in your grid gutters: 1/4, // The size of a gutter in relation to a single column ); There are many more settings available for customizing every aspect of your layout, but this is just a quick-start guide. Keep going to get the details. susy-2.2.12/docs/requirements.txt000066400000000000000000000001401265145761700170260ustar00rootroot00000000000000Jinja2==2.7.1 MarkupSafe==0.18 Pygments==1.6 Sphinx==1.2 docutils==0.11 sphinx-rtd-theme==0.1.5 susy-2.2.12/docs/settings.rst000066400000000000000000000611231265145761700161440ustar00rootroot00000000000000Settings ======== The new syntax for Susy is based around a number of settings that can be written either as a Sass Map or using a :doc:`shorthand syntax `. These two definitions are interchangeable: .. code-block:: scss $susy: ( columns: 12, gutters: 1/4, math: fluid, output: float, gutter-position: inside, ); $shorthand: 12 1/4 fluid float inside; Either format can be passed as a single argument to the functions and mixins that make up the Susy language. Maps can even be used as part of the shorthand: .. code-block:: scss $susy: ( columns: 12, gutters: .25, math: fluid, ); @include layout($susy float inside); Unless otherwise noted, most settings can be controlled both globally (by setting the site-wide default) or locally (passed to individual functions and mixins). ------------------------------------------------------------------------- .. _settings-global: Global Defaults --------------- Here are all the global Susy settings with their default values: .. code-block:: scss $susy: ( flow: ltr, math: fluid, output: float, gutter-position: after, container: auto, container-position: center, columns: 4, gutters: .25, column-width: false, global-box-sizing: content-box, last-flow: to, debug: ( image: hide, color: rgba(#66f, .25), output: background, toggle: top right, ), use-custom: ( background-image: true, background-options: false, box-sizing: true, clearfix: false, rem: true, ) ); You can set your own global defaults, or create individual layout maps to access as needed. For global settings, create a ``$susy`` variable with any values that you need. .. code-block:: scss $susy: ( columns: 12, gutters: .25, gutter-position: inside, ) ------------------------------------------------------------------------- .. _settings-layout: Layout ------ A "layout" in Susy is made up of any combination of settings. Layouts are stored as maps, but can also be written as :doc:`shorthand `. ------------------------------------------------------------------------- .. _settings-layout-function: Layout [function] ~~~~~~~~~~~~~~~~~ Convert :doc:`shorthand ` into a map of settings. .. describe:: function :format: :samp:`layout({$layout})` :$layout: :ref:`\ ` .. code-block:: scss // function input $map: layout(auto 12 .25 inside fluid isolate); //output $map: ( container: auto, columns: 12, gutters: .25, gutter-position: inside, math: fluid, output: isolate, ); This is useful any time you need to combine settings stored in different variables. It's not possible to combine two shorthand variables: .. code-block:: scss // THIS WON'T WORK $short: 12 .25 inside; @include layout($short fluid no-gutters); but it is possible to add a map into the shorthand: .. code-block:: scss // THIS WILL WORK $map: layout(12 .25 inside); @include layout($map fluid no-gutters); or combine two maps: .. code-block:: scss $map1: 13 static; $map2: (6em 1em) inside; @include layout($map1 $map2); ------------------------------------------------------------------------- .. _settings-layout-mixin: Layout [mixin] ~~~~~~~~~~~~~~ Set a new layout as the global default. .. describe:: mixin :format: :samp:`layout($layout, $clean)` :$layout: :ref:`\ ` :$clean: .. code-block:: scss // mixin: set a global layout @include layout(12 1/4 inside-static); By default, these new settings are added to your existing global settings. Use the `$clean` argument to establish new settings from scratch. ------------------------------------------------------------------------- .. _settings-with-layout: With Layout ~~~~~~~~~~~ Temporarily set defaults for a section of your code. .. describe:: mixin :format: ``with-layout($layout, $clean) { @content }`` :$layout: :ref:`\ ` :$clean: :@content: Sass content block .. code-block:: scss @include with-layout(8 static) { // Temporary 8-column static grid... } // Global settings are restored... By default, these new settings are added to your existing global settings. Use the `$clean` argument to establish new settings from scratch. ------------------------------------------------------------------------- .. _settings-susy-get: Susy-Get -------- .. describe:: function :format: ``susy-get($key, $layout)`` :$key: Setting name :$layout: :ref:`\ ` You can access your layout settings at any time, using the ``susy-get`` function. .. code-block:: scss $large: layout(80em 24 1/4 inside); $large-container: susy-get(container, $large); To access a nested setting like ``debug/image``, send the full path as a list for the ``$key`` argument. .. code-block:: scss $debug-image: susy-get(debug image); If no setting is available (or no ``$layout`` is provided) ``susy-get`` falls back to the global user settings, and finally to the Susy default settings. ------------------------------------------------------------------------- .. _settings-flow: Flow ---- The reading direction of your document. Layout elements will stack out in the direction of flow, unless otherwise directed. .. describe:: setting :key: ``flow`` :scope: global, local :options: ``rtl`` | ``ltr`` :default: ``ltr`` .. glossary:: ``ltr`` Layout elements will flow from left to right. ``rtl`` Layout elements will flow from right to left. ------------------------------------------------------------------------- .. _settings-math: Math ---- Susy can produce either relative widths (fluid percentages) or static widths (using given units). .. describe:: setting :key: ``math`` :scope: global, local :options: ``fluid`` | ``static`` :default: ``fluid`` .. glossary:: ``fluid`` All internal grid spans will be calculated relative to the container, and output as ``%`` values. ``static`` All internal grid values will be calculated as multiples of the ``column-width`` setting. If you set column-width to ``4em``, your grid widths will be output as ``em`` values. ------------------------------------------------------------------------- .. _settings-output: Output ------ Susy can generate output using different layout techniques. Currently we have a float module, with an extension to handle isolation as well. In the future there could be flexbox, grid, and other output styles. .. describe:: setting :key: ``output`` :scope: global, local :options: ``float`` | ``isolate`` :default: ``float`` .. glossary:: ``float`` Floats are the most common form of layout used on the web. ``isolate`` Isolation is a `trick`_ developed by `John Albin Wilkins`_ to help fix `sub-pixel rounding`_ bugs in fluid, floated layouts. You can think of it like absolute positioning of floats. We find it to be very useful for spot-checking the worst rounding bugs, but we think it's overkill as a layout technique all to itself. .. _trick: http://www.palantir.net/blog/responsive-design-s-dirty-little-secret .. _sub-pixel rounding: http://tylertate.com/blog/2012/01/05/subpixel-rounding.html .. _John Albin Wilkins: http://john.albin.net/ ------------------------------------------------------------------------- .. _settings-container: Container --------- Set the max-width of the containing element. .. describe:: setting :key: container :scope: global, local [container only] :options: ```` | ``auto`` :default: ``auto`` ```` Set any explicit length (e.g. ``60em`` or ``80%``), and it will be applied directly to the container. .. glossary:: ``auto`` Susy will calculate the width of your container based on the other grid settings, or fall back to ``100%``. .. warning:: For ``static`` layouts, leave ``container: auto`` and set the ``column-width`` instead. Susy will calculate the outer container width for you. Dividing columns out of a set container width would leave you open to sub-pixel errors, and no one likes sub-pixel errors. ------------------------------------------------------------------------- .. _settings-container-position: Container Position ------------------ Align the container relative to it's parent element (often the viewport). .. describe:: setting :key: container-position :scope: global, local [container only] :options: ``left`` | ``center`` | ``right`` | `` [*2]`` :default: ``center`` .. glossary:: ``left`` Holds container elements flush left, with ``margin-left: 0;`` and ``margin-right: auto;``. ``center`` Centers the container, by setting both left and right margins to ``auto``. ``right`` Pushes the container flush right, with ``margin-right: 0;`` and ``margin-left: auto;``. `` [*2]`` If one length is given, it will be applied to both side margins, to offset the container from the edges of the viewport. If two values are given, they will be used as ``left`` and ``right`` margins respectively. ------------------------------------------------------------------------- .. _settings-columns: Columns ------- Establish the column-count and arrangement for a grid. .. describe:: setting :key: ``columns`` :scope: global, local :options: ```` | ```` :default: ``4`` ```` The number of columns in your layout. ```` For asymmetrical grids, list the size of each column relative to the other columns, where ``1`` is a single column-unit. ``(1 2)`` would create a 2-column grid, with the second column being twice the width of the first. For a `Fibonacci`_-inspired grid, use ``(1 1 2 3 5 8 13)``. .. _Fibonacci: http://en.wikipedia.org/wiki/Fibonacci_number ------------------------------------------------------------------------- .. _settings-gutters: Gutters ------- Set the width of a gutter relative to columns on your grid. .. describe:: setting :key: ``gutters`` :scope: global, local :options: ```` :default: ``1/4`` ```` Gutters are established as a ratio to the size of a column. The default ``1/4`` setting will create gutters one quarter the size of a column. In asymmetrical grids, this is ``1/4`` the size of a single column-unit. If you want to set explicit column and gutter widths, write your ``gutters`` setting as ``/``. You can even leave the units attached. .. code-block:: scss // 70px columns, 20px gutters $susy: ( gutters: 20px/70px, ); ------------------------------------------------------------------------- .. _settings-column-width: Column Width ------------ Optionaly set the explicit width of a column. .. describe:: setting :key: ``column-width`` :scope: global, local :options: ```` | ``false``/``null`` :default: ``false`` ```` The width of one column, using any valid unit. This will be used in ``static`` layouts to calculate all grid widths, but can also be used by ``fluid`` layouts to calculate an outer maximum width for the container. ``false``/``null`` There is no need for column-width in ``fluid`` layouts unless you specifically want the container-width calculated for you. ------------------------------------------------------------------------- .. _settings-gutter-position: Gutter Position --------------- Set how and where gutters are added to the layout, either as padding or margins on layout elements. .. describe:: setting :key: gutter-position :scope: global, local :options: ``before`` | ``after`` | ``split`` | ``inside`` | ``inside-static`` :default: ``after`` .. glossary:: ``before`` Gutters are added as ``margin`` before a layout element, relative to the flow direction (left-margin for ltr, right-margin for rtl). The first gutter on each row will need to be removed. ``after`` Gutters are added as ``margin`` after a layout element, relative to the flow direction. The last gutter on each row will need to be removed. ``split`` Gutters are added as ``margin`` on both sides of a layout element, and are not removed at the edges of the grid. ``inside`` Gutters are added as ``padding`` on both sides of a layout element, and are not removed at the edges of the grid. ``inside-static`` Gutters are added as static ``padding`` on both sides of a layout element, even in a fluid layout context, and are not removed at the edges of the grid. ------------------------------------------------------------------------- .. _settings-global-box-sizing: Global Box Sizing ----------------- Tell Susy what box model is being applied globally. .. describe:: setting :key: ``global-box-sizing`` :scope: global :options: ``border-box`` | ``content-box`` :default: ``content-box`` .. glossary:: ``content-box`` Browsers use the ``content-box`` model unless you specify otherwise. ``border-box`` If you are using the `Paul Irish universal border-box`_ technique (or something similar), you should change this setting to ``border-box``. You can also use our ``border-box-sizing`` mixin, and we'll take care of it all for you. For more, see the `MDN box-sizing documentation`_. .. _Paul Irish universal border-box: http://www.paulirish.com/2012/box-sizing-border-box-ftw/ .. _MDN box-sizing documentation: https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing ------------------------------------------------------------------------- .. _settings-last-flow: Last Flow --------- The float-direction for the last element in a row when using the :term:`float` output. .. describe:: setting :key: ``last-flow`` :scope: global :options: ``from`` | ``to`` :default: ``to`` .. glossary:: ``from`` This is the default for all other elements in a layout. In an ``ltr`` (left-to-right) flow, the from-direction is ``left``, and this setting would float "last" elements to the left, along with the other elements. ``to`` In many cases (especially with ``fluid`` grids), it can be helpful to float the last element in a row in the opposite direction. ------------------------------------------------------------------------- .. _settings-debug: Debug ----- Susy has a few tools to help in debugging your layout as you work. These settings help you control the debugging environment. .. describe:: setting block :key: ``debug`` :scope: global, local [container only] :options: .. code-block:: scss $susy: ( debug: ( image: show, color: blue, output: overlay, toggle: top right, ), ); .. warning:: Grid images are not exact. Browsers have extra trouble with sub-pixel rounding on background images. These are meant for rough debugging, not for pixel-perfect measurements. Expect the ``to`` side of your grid image (``right`` if your flow is ``ltr``) to be off by several pixels. ------------------------------------------------------------------------- .. _settings-debug-image: Debug Image ~~~~~~~~~~~ Toggle the available grid images on and off. .. describe:: setting :key: ``debug image`` :scope: global, local [container only] :options: ``show`` | ``hide`` | ``show-columns`` | ``show-baseline`` :default: ``hide`` .. glossary:: ``show`` Show grid images, usually on the background of container elements, for the purpose of debugging. If you are using `Compass vertical rhythms`_ (or have set your own ``$base-line-height`` variable) Susy will show baseline grids as well. ``hide`` Hide all grid debugging images. ``show-columns`` Show only horizontal grid-columns, even if a baseline grid is available. ``show-baseline`` Show only the baseline grid, if the ``$base-line-height`` variable is available. .. _Compass vertical rhythms: http://compass-style.org/reference/compass/typography/vertical_rhythm/ ------------------------------------------------------------------------- .. _settings-debug-output: Debug Output ~~~~~~~~~~~~ The debug image can be output either as a background on the container, or as a generated overlay. .. describe:: setting :key: ``debug output`` :scope: global, local [container only] :options: ``background`` | ``overlay`` :default: ``background`` .. glossary:: ``background`` Debugging images will be generated on on the background of the container element. ``overlay`` Debugging images will be generated as an overlay using the container's ``::before`` element. By default, the overlay is hidden, but we also generate a :ref:`toggle ` in a corner of the viewport. Hover over the toggle to make the overlay appear. ------------------------------------------------------------------------- .. _settings-debug-toggle: Debug Toggle ~~~~~~~~~~~~ If you are using the grid overlay option, Susy will generate a toggle to show/hide the overlay. Hovering over the toggle will show the overlay. You can place the toggle in any corner of the viewport using a combination of ``top``, ``right``, ``bottom``, and ``left``. .. describe:: setting :key: ``debug toggle`` :scope: global :options: ``right`` | ``left`` and ``top`` | ``bottom`` :default: ``top right`` ------------------------------------------------------------------------- .. _settings-debug-color: Debug Color ~~~~~~~~~~~ Change the color of columns in the generated grid image. .. describe:: setting :key: ``debug color`` :scope: global :options: :default: ``rgba(#66f, .25)`` ------------------------------------------------------------------------- .. _settings-custom: Custom Support -------------- There are several common helpers that you can tell Susy to use, if you provide them yourself or through a third-party library like Compass or Bourbon. ------------------------------------------------------------------------- .. _settings-custom-clearfix: Custom Clearfix ~~~~~~~~~~~~~~~ Tell Susy to use a global ``clearfix`` mixin. .. describe:: setting :key: ``use-custom clearfix`` :scope: global :options: :default: ``false`` ``false`` Susy will use an internal micro-clearfix. ``true`` Susy will look for an existing ``clearfix`` mixin, and fallback to the internal micro-clearfix if none is found. ------------------------------------------------------------------------- .. _settings-custom-background-image: Custom Background Image ~~~~~~~~~~~~~~~~~~~~~~~ Tell Susy to use a global ``background-image`` mixin. This is only used for debugging. .. describe:: setting :key: ``use-custom background-image`` :scope: global :options: :default: ``true`` ``false`` Susy will output background-images directly to CSS. ``true`` Susy will look for an existing ``background-image`` mixin (like the ones provided by Compass and Bourbon), and fallback to plain CSS output if none is found. ------------------------------------------------------------------------- .. _settings-custom-background-options: Custom Background Options ~~~~~~~~~~~~~~~~~~~~~~~~~ Tell Susy to use global ``background-size``, ``-origin``, and ``-clip`` mixins. This is only used for debugging. .. describe:: setting :key: ``use-custom background-options`` :scope: global :options: :default: ``false`` ``false`` Susy will output background-options directly to CSS. ``true`` Susy will look for existing ``background-size``, ``-origin``, and ``-clip`` mixins (like the ones provided by Compass and Bourbon), and fallback to plain CSS output if none is found. ------------------------------------------------------------------------- .. _settings-custom-breakpoint: Custom Breakpoint Options ~~~~~~~~~~~~~~~~~~~~~~~~~ Tell Susy to use a custom ``breakpoint`` mixin, like the one provided by the `Breakpoint`_ plugin. .. _Breakpoint: http://breakpoint-sass.com/ .. describe:: setting :key: ``use-custom breakpoint`` :scope: global :options: :default: ``true`` ``false`` Susy will use an internal fallback for media-queries. ``true`` Susy will look for existing an ``breakpoint`` mixin like the one provided by the [Breakpoint](http://breakpoint-sass.com) plugin, and fallback to internal media-query support if none is found. ------------------------------------------------------------------------- .. _settings-custom-box-sizing: Custom Box Sizing ~~~~~~~~~~~~~~~~~ Tell Susy to use a global ``box-sizing`` mixin. .. describe:: setting :key: ``use-custom box-sizing`` :scope: global :options: :default: ``true`` ``false`` Susy will output ``box-sizing`` official syntax, as well as ``-moz`` and ``-webkit`` prefixed versions. ``true`` Susy will look for an existing ``box-sizing`` mixin (like the ones provided by Compass and Bourbon), and fallback to mozilla, webkit, and official syntax if none is found. ------------------------------------------------------------------------- .. _settings-custom-rem: Custom Rem ~~~~~~~~~~ Tell Susy to use the Compass ``rem`` support module. .. describe:: setting :key: ``use-custom rem`` :scope: global :options: :default: ``true`` ``false`` Susy will output length values directly to CSS. ``true`` Susy will look for an existing ``rem`` mixin, and check the ``$rhythm-unit`` and ``$rem-with-px-fallback`` settings provided by Compass, or fallback to plain CSS output if they aren't found. ------------------------------------------------------------------------------ .. _settings-location: Location -------- Reference a specific column on the grid for :ref:`row edges `, :ref:`isolation `, or :ref:`asymmetrical layouts `. Locations keywords don't require the ``at`` flag. .. describe:: setting :key: ``location`` :scope: local :options: ``first``/``alpha`` | ``last``/``omega`` | ```` :default: ``null`` .. glossary:: ``first`` ``alpha`` Set location to ``1``. ``last`` ``omega`` Set the location to the final column, and any previous columns included by the relevant ``span``. ```` Set the location to any column-index between ``1`` and the total number of available columns. ------------------------------------------------------------------------- .. _settings-box-sizing: Box Sizing ---------- Set a new box model on any given element. .. describe:: setting :key: ``box-sizing`` :scope: local :options: ``border-box`` | ``content-box`` :default: ``null`` ``border-box`` Output ``box-sizing`` CSS to set the ``border-box`` model. ``content-box`` Output ``box-sizing`` CSS to set the ``content-box`` model. ------------------------------------------------------------------------- .. _settings-spread: Spread ------ Adjust how many gutters are included in a column span. .. describe:: setting :key: ``spread`` :scope: local :options: ``narrow`` | ``wide`` | ``wider`` :default: various... .. glossary:: ``narrow`` In most cases, column-spans include the gutters *between* columns. A span of ``3 narrow`` covers the width of 3 columns, as well as 2 internal gutters. This is the default in most cases. ``wide`` Sometimes you need to include one side gutter in a span width. A span of ``3 wide`` covers the width of 3 columns, and 3 gutters (2 internal, and 1 side). This is the default for several margin/padding mixins. ``wider`` Sometimes you need to include both side gutters in a span width. A span of ``3 wider`` covers the width of 3 columns, and 4 gutters (2 internal, and 2 sides). ------------------------------------------------------------------------- .. _settings-gutter-override: Gutter Override --------------- Set an explicit one-off gutter-width on an element, or remove its gutters entirely. .. describe:: setting :key: ``gutter-override`` :scope: local :options: ``no-gutters``/``no-gutter`` | ```` :default: ``null`` .. glossary:: ``no-gutters`` ``no-gutter`` Remove all gutter output. ```` Override the calculated gutter output with an explicit width. ------------------------------------------------------------------------- .. _settings-role: Role ---- Mark a grid element as a nesting context for child elements. .. describe:: setting :key: ``role`` :scope: local :options: ``nest`` :default: ``null`` .. glossary:: ``nest`` Mark an internal grid element as a context for nested grids. .. note:: This can be used with any grid type, but it is required for nesting with ``split``, ``inside``, or ``inside-static`` gutters. susy-2.2.12/docs/shorthand.rst000066400000000000000000000114131265145761700162730ustar00rootroot00000000000000Shorthand ========= Susy provides a shorthand syntax to easily pass arbitrary settings into functions and mixins. This allows the syntax to stay simple and readable for the majority of use cases, and only add complexity if/when you really need it. .. code-block:: scss // Establish an 80em container @include container(80em); // Span 3 of 12 columns @include span(3 of 12); // Setup the 960 Grid System @include layout(12 (60px 20px) split static); // Span 3 isolated columns in a complex, asymmetrical grid, without gutters @include span(isolate 3 at 2 of (1 2 3 4 3 2 1) no-gutters); ------------------------------------------------------------------------- Overview -------- In most cases, the syntax order is not important, but there are a few rules to get you started. The syntax generally breaks down into three parts. .. describe:: syntax :shorthand: ``$span`` ``$grid`` ``$keywords``; .. glossary:: span A ``span`` can be any length, or (in some cases) a unitless number representing columns to be spanned. The specifics change depending on the function or mixin where it is being passed. Some mixins even allow multiple spans, using the standard CSS :abbr:`TRBL ` syntax. grid The ``grid`` is composed of a :ref:`settings-columns` setting, and optional settings for :ref:`settings-gutters` and :ref:`settings-column-width`. It looks something like this: .. code-block:: scss // 12-column grid $grid: 12; // 12-column grid with 1/3 gutter ratio $grid: 12 1/3; // 12-column grid with 60px columns and 10px gutters $grid: 12 (60px 10px); // asymmetrical grid with .25 gutter ratio $grid: (1 2 3 2 1) .25; keywords The ``keywords`` are the easiest. Most :doc:`settings ` have simple keyword values that can be included in any order — before, after, or between the :term:`span` and :term:`grid` options. .. code-block:: scss // All the keywords in Susy: $global-keywords: ( container : auto, math : static fluid, output : isolate float, container-position : left center right, flow : ltr rtl, gutter-position : before after split inside inside-static, debug: ( image : show hide show-columns show-baseline, output : background overlay, ), ); $local-keywords: ( box-sizing : border-box content-box, edge : first alpha last omega, spread : narrow wide wider, gutter-override : no-gutters no-gutter, clear : break nobreak, role : nest, ); The global keywords can be used anywhere, and apply to global default :doc:`settings `. The local keywords are specific to each individual use. ------------------------------------------------------------------------- .. _shorthand-layout: Layout ------ The simplest shorthand variation is used for defining your layout in broad terms. .. describe:: shorthand :pattern: `` `` Nothing here is required — all the settings are optional and have global defaults. :term:`grid` and :term:`keyword ` settings work exactly as advertised. .. code-block:: scss // grid: (columns: 4, gutters: 1/4, column-width: 4em); // keywords: (math: fluid, gutter-position: inside-static, flow: rtl); $small: 4 (4em 1em) fluid inside-static rtl; You can easily convert layouts from shorthand to map syntax using the :ref:`settings-layout` function. ------------------------------------------------------------------------- .. _shorthand-span: Span ---- Most of Susy's functions & mixins are used to calculate or set a width, or ``span``. .. describe:: shorthand :pattern: `` at of `` Most spans in Susy are either a unitless number (representing columns) or an explicit width. Some of them also require a location (particularly for asymmetrical grids and isolation). The standard span syntax looks like this: .. code-block:: scss // Pattern: $span: $span at $location of $layout; // span: 3; // location: 4; // layout: (columns: 12, gutters: .25, math: fluid) $span: 3 at 4 of 12 .25 fluid; // Only $span is required in most cases $span: 30%; The "at" flag comes immediately before the location (unless the location itself is a keyword), and everything after the "of" flag is treated as part of the layout. Some mixins accept multiple spans, using the common CSS "top right bottom left" (TRBL) pattern, or have other specific options. Those are all documented as part of the function/mixin details. susy-2.2.12/docs/susyone.rst000066400000000000000000000605021265145761700160110ustar00rootroot00000000000000Susy One ======== This is documentation for the old syntax, used in Susy 1. If you are using Susy 2 and want use the old syntax, change your import from ``susy`` to ``susyone``. .. code-block:: scss // With Susy 2 installed... @import "susyone"; ---------------------------------------------------------------------- .. _susyone-basic-settings: Basic Settings -------------- - **Container**: The root element of a *Grid*. - **Layout**: The total number of *Columns* in a grid. - **Grid Padding**: Padding on the sides of the *Grid*. - **Context**: The number of *Columns* spanned by the parent element. - **Omega**: Any *Grid Element* spanning the last *Column* in its *Context*. .. _susyone-total-columns: Total Columns ~~~~~~~~~~~~~ The number of Columns in your default Grid Layout. .. code-block:: scss // $total-columns: ; $total-columns: 12; - ````: Unitless number. .. _susyone-column-width: Column Width ~~~~~~~~~~~~ The width of a single Column in your Grid. .. code-block:: scss // $column-width: ; $column-width: 4em; - ````: Length in any unit of measurement (em, px, %, etc). .. _susyone-gutter-width: Gutter Width ~~~~~~~~~~~~ The space between Columns. .. code-block:: scss // $gutter-width: ; $gutter-width: 1em; - ````: Units must match ``$column-width``. .. _susyone-grid-padding: Grid Padding ~~~~~~~~~~~~ Padding on the left and right of a Grid Container. .. code-block:: scss // $grid-padding: ; $grid-padding: $gutter-width; // 1em - ````: Units should match the container width (``$column-width`` unless ``$container-width`` is set directly). ---------------------------------------------------------------------- .. _susyone-functions: Functions --------- Where a mixin returns property/value pairs, functions return simple values that you can put where you want, and use for advanced math. .. _susyone-columns: Columns ~~~~~~~ Similar to ``span-columns`` mixin, but returns the math-ready ``%`` multiplier. .. code-block:: scss // columns(<$columns> [, <$context>, <$style>]) .item { width: columns(3,6); } - ``<$columns>``: The number of *Columns* to span, - ``<$context>``: The *Context*. Default: ``$total-columns``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. .. _susyone-gutter: Gutter ~~~~~~ The ``%`` width of one gutter in any given context. .. code-block:: scss // gutter([<$context>, <$style>]) .item { margin-right: gutter(6) + columns(3,6); } - ``<$context>``: The *Context*. Default: ``$total-columns``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. .. _susyone-space: Space ~~~~~ Total ``%`` space taken by Columns, including internal AND external gutters. .. code-block:: scss // space(<$columns> [, <$context>, <$style>]) .item { margin-right: space(3,6); } - ``<$columns>``: The number of *Columns* to span, - ``<$context>``: The *Context*. Default: ``$total-columns``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. ---------------------------------------------------------------------- .. _susyone-basic-mixins: Basic Mixins ------------ .. _susyone-container: Container ~~~~~~~~~ Establish the outer grid-containing element. .. code-block:: scss // container([$]*) .page { @include container; } - ``<$media-layout>``: Optional media-layout shortcuts (see *Responsive Grids* below). Default: ``$total-columns``. .. _susyone-span-columns: Span Columns ~~~~~~~~~~~~ Align an element to the Susy Grid. .. code-block:: scss // span-columns(<$columns> [ , <$context>, <$padding>, <$from>, <$style>]) nav { @include span-columns(3,12); } article { @include span-columns(9 omega,12); } - ``<$columns>``: The number of *Columns* to span. - ````: Optional flag to signal the last element in a row. - ``<$context>``: Current nesting *Context*. Default: ``$total-columns``. - ``<$padding>``: Optional padding applied inside an individual grid element. Given as a length (same units as the grid) or a list of lengths (from-direction to-direction). Default: ``false``. - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. .. _susyone-omega: Omega ~~~~~ Apply to any omega element as an override. .. code-block:: scss // omega([<$from>]) .gallery-image { @include span-columns(3,9); // each gallery-image is 3 of 9 cols. &:nth-child(3n) { @include omega; } // every third image completes a row. } - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. .. _susyone-nth-omega: Nth-Omega ~~~~~~~~~ Apply to any element as an nth-child omega shortcut. Defaults to ``:last-child``. .. code-block:: scss // nth-omega([<$n>, <$selector>, <$from>]) .gallery-image { @include span-columns(3,9); // each gallery-image is 3 of 9 cols. @include nth-omega(3n); // same as omega example above. } - ``<$n>``: The keyword or equation to select: ``[first | only | last | ]``. An equation could be e.g. ``3`` or ``3n`` or ``'3n+1'``. Note that quotes are needed to keep complex equations from being simplified by Compass. Default: ``last``. - ``<$selector>``: The type of element, and direction to count from: ``[child | last-child | of-type | last-of-type ]``. Default: ``child``. - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. ---------------------------------------------------------------------- .. _susyone-responsive-mixins: Responsive Mixins ----------------- - **Breakpoint**: A min- or max- viewport width at which to change *Layouts*. - **Media-Layout**: Shortcut for declaring *Breakpoints* and *Layouts* in Susy. .. code-block:: scss // $media-layout: ; // - You must supply either or . $media-layout: 12; // Use 12-col layout at matching min-width. $media-layout: 30em; // At min 30em, use closest fitting layout. $media-layout: 30em 12; // At min 30em, use 12-col layout. $media-layout: 12 60em; // Use 12 cols up to max 60em. $media-layout: 30em 60em; // Between min 30em & max 60em, use closest layout. $media-layout: 30em 12 60em;// Use 12 cols between min 30em & max 60em. $media-layout: 60em 12 30em;// Same. Larger length will always be max-width. $media-layout : 12 lt-ie9; // Output is included under ``.lt-ie9`` class, // for use with IE conditional comments // on the tag. - ``<$min/max-width>``: Any length with units, used to set media breakpoints. - ``<$layout>``: Any (unitless) number of columns to use for the grid at a given breakpoint. - ``<$ie-fallback>``: Any string to use as a fallback class when mediaqueries are not available. Do not include a leading "``.``" class-signifier, only the class name ("``lt-ie9``", not "``.lt-ie9``"). This can be anything you want: "``no-mediaqueries``", "``ie8``", "``popcorn``", etc. .. _susyone-at-breakpoint: At-Breakpoint ~~~~~~~~~~~~~ At a given min- or max-width Breakpoint, use a given Layout. .. code-block:: scss // at-breakpoint(<$media-layout> [, <$font-size>]) { <@content> } @include at-breakpoint(30em 12) { .page { @include container; } } - ``<$media-layout>``: The *Breakpoint/Layout* combo to use (see above). - ``<$font-size>``: Browsers interpret em-based media-queries using the browser default font size (``16px`` in most cases). If you have a different base font size for your site, we have to adjust for the difference. Tell us your base font size, and we'll do the conversion. Default: ``$base-font-size``. - ``<@content>``: Nested ``@content`` block will use the given *Layout*. .. _susyone-layout: Layout ~~~~~~ Set an arbitrary Layout to use with any block of content. .. code-block:: scss // layout(<$layout-cols>) { <@content> } @include layout(6) { .narrow-page { @include container; } } - ``<$layout-cols>``: The number of *Columns* to use in the *Layout*. - ``<@content>``: Nested ``@content`` block will use the given *Layout*. .. _susyone-set-container-width: Set Container Width ~~~~~~~~~~~~~~~~~~~ Reset the width of a Container for a new Layout context. Can be used when ``container()`` has already been applied to an element, for DRYer output than using ``container`` again. .. code-block:: scss // set-container-width([<$columns>, <$style>]) @include container; @include at-breakpoint(8) { @include set-container-width; } - ``<$columns>``: The number of *Columns* to be contained. Default: Current value of ``$total-columns`` depending on *Layout*. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. .. _susyone-with-settings: With Grid Settings ~~~~~~~~~~~~~~~~~~ Use different grid settings for a block of code - whether the same grid at a different breakpoint, or a different grid altogether. .. code-block:: scss // with-grid-settings([$, $, <$gutter>, <$padding>]) { <@content> } @include with-grid-settings(12,4em,1.5em,1em) { .new-grid { @include container; } }; - ``<$columns>``: Overrides the ``$total-columns`` setting for all contained elements. - ``<$width>``: Overrides the ``$column-width`` setting for all contained elements. - ``<$gutter>``: Overrides the ``$gutter-width`` setting for all contained elements. - ``<$padding>``: Overrides the ``$grid-padding`` setting for all contained elements. - ``<@content>``: Nested ``@content`` block will use the given grid settings. ---------------------------------------------------------------------- .. _susyone-box-sizing: Box Sizing ---------- .. _susyone-border-box-mixin: Border-Box Sizing ~~~~~~~~~~~~~~~~~ Set the default box-model to ``border-box``, and adjust the grid math accordingly. .. code-block:: scss // border-box-sizing() @include border-box-sizing; This will apply border-box model to all elements (using the star selector) and set ``$border-box-sizing`` to ``true``. You can use the variable on it's own to adjust the grid math, in cases where you want to apply the box-model separately. ---------------------------------------------------------------------- .. _susyone-isolation: Isolation --------- .. _susyone-isolate: Isolate ~~~~~~~ Isolate the position of a grid element relative to the container. This should be used in addition to ``span-columns`` as a way of minimizing sub-pixel rounding errors in specific trouble locations. .. code-block:: scss // isolate(<$location> [, <$context>, <$from>, <$style>]) @include span-columns(4); // 4-columns wide @include isolate(2); // positioned in the second column - ``<$location>``: The container-relative column number to position on. - ``<$context>``: Current nesting *Context*. Default: ``$total-columns``. - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. .. _susyone-isolate-grid: Isolate Grid ~~~~~~~~~~~~ Isolate a group of elements in a grid (such as an image gallery) using nth-child or nth-of-type for positioning. Provide the column-width of each element, and Susy will determine the positioning for you. .. code-block:: scss // isolate-grid(<$columns> [, <$context>, <$selector>, <$from>, <$style>]) .gallery-item { @include isolate-grid(3); } - ``<$columns>``: The number of *Columns* for each item to span. - ``<$context>``: Current nesting *Context*. Default: ``$total-columns``. - ``<$selector>``: either 'child' or 'of-type'. Default: ``child``. - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. ---------------------------------------------------------------------- .. _susyone-padding: Padding Mixins -------------- .. _susyone-prefix: Prefix ~~~~~~ Add Columns of empty space as ``padding`` before an element. .. code-block:: scss // prefix(<$columns> [, <$context>, <$from>, <$style>]) .box { @include prefix(3); } - ``<$columns>``: The number of *Columns* to be added as ``padding`` before. - ``<$context>``: The *Context*. Default: ``$total-columns``. - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. .. _susyone-suffix: Suffix ~~~~~~ Add columns of empty space as padding after an element. .. code-block:: scss // suffix(<$columns> [, <$context>, <$from>, <$style>]) .box { @include suffix(2); } - ``<$columns>``: The number of *Columns* to be added as ``padding`` after. - ``<$context>``: The *Context*. Default: ``$total-columns``. - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. .. _susyone-pad: Pad ~~~ Shortcut for adding both Prefix and Suffix ``padding``. .. code-block:: scss // pad([<$prefix>, <$suffix>, <$context>, <$from>, <$style>]) .box { @include pad(3,2); } - ``<$prefix>``: The number of *Columns* to be added as ``padding`` before. - ``<$suffix>``: The number of *Columns* to be added as ``padding`` after. - ``<$context>``: The *Context*. Default: ``$total-columns``. - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. .. _susyone-bleed: Bleed ~~~~~ Add negative margins and matching positive padding to an element, so that its background "bleeds" outside its natural position. .. code-block:: scss // bleed(<$width> [<$sides>, <$style>]) @include bleed(2); - ``<$width>``: The number of *Columns* or arbitrary length to bleed. Use ``2 of 12`` syntax for context in nested situations. - ``<$sides>``: The sides of the element that should bleed. Default: ``left right``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. ---------------------------------------------------------------------- .. _susyone-margin: Margin Mixins ------------- .. _susyone-pre: Pre ~~~ Add columns of empty space as margin before an element. .. code-block:: scss // pre(<$columns> [, <$context>, <$from>, <$style>]) .box { @include pre(2); } - ``<$columns>``: The number of *Columns* to be added as ``margin`` before. - ``<$context>``: The *Context*. Default: ``$total-columns``. - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. .. _susyone-post: Post ~~~~ Add columns of empty space as margin after an element. .. code-block:: scss // post(<$columns> [, <$context>, <$from>, <$style>]) .box { @include post(3); } - ``<$columns>``: The number of *Columns* to be added as ``margin`` after. - ``<$context>``: The *Context*. Default: ``$total-columns``. - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. .. _susyone-squish: Squish ~~~~~~ Shortcut to add empty space as margin before and after an element. .. code-block:: scss // squish([<$pre>, <$post>, <$context>, <$from>, <$style>]) .box { @include squish(2,3); } - ``<$pre>``: The number of *Columns* to be added as ``margin`` before. - ``<$post>``: The number of *Columns* to be added as ``margin`` after. - ``<$context>``: The *Context*. Default: ``$total-columns``. - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. .. _susyone-push: Push ~~~~ Identical to ``pre``. .. code-block:: scss // push(<$columns> [, <$context>, <$from>, <$style>]) .box { @include push(3); } .. _susyone-pull: Pull ~~~~ Add negative margins before an element, to pull it against the flow. .. code-block:: scss // pull(<$columns> [, <$context>, <$from>, <$style>]) .box { @include pull(2); } - ``<$columns>``: The number of *Columns* to be subtracted as ``margin`` before. - ``<$context>``: The *Context*. Default: ``$total-columns``. - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. ---------------------------------------------------------------------- .. _susyone-reset: Reset Mixins ------------ .. _susyone-reset-column: Reset Columns ~~~~~~~~~~~~~ Resets an element to default block behaviour. .. code-block:: scss // reset-columns([<$from>]) article { @include span-columns(6); } // articles are 6 cols wide #news article { @include reset-columns; } // but news span the full width // of their container - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. .. _susyone-remove-omega: Remove-Omega ~~~~~~~~~~~~ Apply to any previously-omega element to reset it's float direction and margins to match non-omega grid elements. Note that unlike omega, this requires a context when nested. .. code-block:: scss // remove-omega([<$context>, <$from>, <$style>]) .gallery-image { &:nth-child(3n) { @include remove-omega; } // 3rd images no longer complete rows. } - ``<$context>``: Current nesting *Context*. Default: ``$total-columns``. - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. .. _susyone-remove-nth-omega: Remove Nth-Omega ~~~~~~~~~~~~~~~~ Apply to any previously nth-omega element to reset it's float direction and margins to match non-omega grid elements. Note that unlike omega, this requires a context when nested. .. code-block:: scss // remove-nth-omega([<$n>, <$selector>, <$context>, <$from>, <$style>]) .gallery-image { @include remove-nth-omega(3n); // same as remove-omega example above. } - ``<$n>``: The keyword or equation to select: ``[first | only | last | ]``. An equation could be e.g. ``3`` or ``3n`` or ``'3n+1'``. Note that quotes are needed to keep a complex equation from being simplified by Compass. Default: ``last``. - ``<$selector>``: The type of element, and direction to count from: ``[child | last-child | of-type | last-of-type ]``. Default: ``child``. - ``<$context>``: Current nesting *Context*. Default: ``$total-columns``. - ``<$from>``: The origin direction of your document flow. Default: ``$from-direction``. - ``<$style>``: Optionally return ``static`` lengths for grid calculations. Default: ``$container-style``. ---------------------------------------------------------------------- .. _susyone-debug: Debugging --------- .. _susyone-grid-background: Susy Grid Background ~~~~~~~~~~~~~~~~~~~~ Show the Susy Grid as a background-image on any container. .. code-block:: scss // susy-grid-background(); .page { @include susy-grid-background; } - If you are using the ```` element as your *Container*, you need to apply a background to the ```` element in order for this grid-background to size properly. - Some browsers have trouble with sub-pixel rounding on background images. Use this for checking general spacing, not pixel-exact alignment. Susy columns tend to be more accurate than gradient grid-backgrounds. ---------------------------------------------------------------------- .. _susyone-container-override: Container Override Settings --------------------------- .. _susyone-container-width: Container Width ~~~~~~~~~~~~~~~ Override the total width of your grid with an arbitrary length. .. code-block:: scss // $container-width: | ; $container-width: false; - ````: Length in em, px, %, etc. - ````: True or false. .. _susyone-container-style: Container Style ~~~~~~~~~~~~~~~ Override the type of shell containing your grid. .. code-block:: scss // $container-style: