|
| 1 | +django-libsass |
| 2 | +============== |
| 3 | + |
| 4 | +A django-compressor filter to compile Sass files using libsass. |
| 5 | + |
| 6 | +Installation |
| 7 | +~~~~~~~~~~~~ |
| 8 | + |
| 9 | +Starting from a Django project with `django-compressor <https://github.com/django-compressor/django-compressor/>`_ set up:: |
| 10 | + |
| 11 | + pip install django-libsass |
| 12 | + |
| 13 | +and add django_libsass.SassCompiler to your COMPRESS_PRECOMPILERS setting:: |
| 14 | + |
| 15 | + COMPRESS_PRECOMPILERS = ( |
| 16 | + ('text/x-scss', 'django_libsass.SassCompiler'), |
| 17 | + ) |
| 18 | + |
| 19 | +You can now use the content type text/x-scss on your stylesheets, and have them |
| 20 | +compiled seamlessly into CSS:: |
| 21 | + |
| 22 | + {% compress css %} |
| 23 | + <link rel="stylesheet" type="text/x-scss" href="{% static "myapp/css/main.scss" %}" /> |
| 24 | + {% endcompress %} |
| 25 | + |
| 26 | + |
| 27 | +Imports |
| 28 | +~~~~~~~ |
| 29 | + |
| 30 | +Relative paths in @import lines are followed as you would expect:: |
| 31 | + |
| 32 | + @import "../variables.scss"; |
| 33 | + |
| 34 | +Additionally, Django's STATICFILES_FINDERS setting is consulted, and all possible locations |
| 35 | +for static files *on the local filesystem* are included on the search path. This makes it |
| 36 | +possible to import files across different apps:: |
| 37 | + |
| 38 | + @import "myotherapp/css/widget.scss" |
| 39 | + |
| 40 | + |
| 41 | +Why django-libsass? |
| 42 | +~~~~~~~~~~~~~~~~~~~ |
| 43 | + |
| 44 | +We wanted to use Sass in a Django project without introducing any external (non pip-installable) |
| 45 | +dependencies. (Actually, we wanted to use Less, but the same arguments apply...) There are a few |
| 46 | +pure Python implementations of Sass and Less, but we found that they invariably didn't match the |
| 47 | +behaviour of the reference compilers, either in their handling of @imports or lesser-used CSS |
| 48 | +features such as media queries. |
| 49 | + |
| 50 | +`libsass <http://libsass.org/>`_ is a mature C/C++ port of the Sass engine, co-developed by the |
| 51 | +original creator of Sass, and we can reasonably rely on it to stay in sync with the reference |
| 52 | +Sass compiler - and, being C/C++, it's fast. Thanks to Hong Minhee's |
| 53 | +`libsass-python <https://github.com/dahlia/libsass-python>`_ project, it has Python bindings and |
| 54 | +installs straight from pip. |
| 55 | + |
| 56 | +django-libsass builds on libsass-python to make @import paths aware of Django's staticfiles |
| 57 | +mechanism, and provides a filter module for django-compressor which uses the libsass-python API |
| 58 | +directly, avoiding the overheads of calling an external executable to do the compilation. |
| 59 | + |
| 60 | +Author |
| 61 | +~~~~~~ |
| 62 | + |
| 63 | + |
0 commit comments