README.rst
1++++++++++++++
2django-htmlmin
3++++++++++++++
4
5.. image:: https://secure.travis-ci.org/cobrateam/django-htmlmin.png
6 :target: http://travis-ci.org/cobrateam/django-htmlmin
7
8django-html is an HTML minifier for Python, with full support for HTML 5. It
9supports Django, Flask and many other Python web frameworks. It also provides a
10command line tool, that can be used for static websites or deployment scripts.
11
12Why minify HTML code?
13=====================
14
15One of the important points on client side optimization is to minify HTML. With
16minified HTML code, you reduce the size of the data transferred from the server
17to the client, which results in faster load times.
18
19Installing
20==========
21
22To install django-htmlmin, run this on the terminal: ::
23
24 $ [sudo] pip install django-htmlmin
25
26Using the middleware
27====================
28
29All you need to do is add two middlewares to your ``MIDDLEWARE_CLASSES`` and
30enable the ``HTML_MINIFY`` setting: ::
31
32 MIDDLEWARE_CLASSES = (
33 # other middleware classes
34 'htmlmin.middleware.HtmlMinifyMiddleware',
35 'htmlmin.middleware.MarkRequestMiddleware',
36 )
37
38Note that if you're using Django's caching middleware, ``MarkRequestMiddleware``
39should go after ``FetchFromCacheMiddleware``, and ``HtmlMinifyMiddleware``
40should go after ``UpdateCacheMiddleware``: ::
41
42 MIDDLEWARE_CLASSES = (
43 'django.middleware.cache.UpdateCacheMiddleware',
44 'htmlmin.middleware.HtmlMinifyMiddleware',
45 # other middleware classes
46 'django.middleware.cache.FetchFromCacheMiddleware',
47 'htmlmin.middleware.MarkRequestMiddleware',
48 )
49
50You can optionally specify the ``HTML_MINIFY`` setting::
51
52 HTML_MINIFY = True
53
54The default value for the ``HTML_MINIFY`` setting is ``not DEBUG``. You only
55need to set it to ``True`` if you want to minify your HTML code when ``DEBUG``
56is enabled.
57
58Excluding some URLs
59-------------------
60
61If you don't want to minify all views in your app and it's under a ``/my_app``
62URL, you can tell the middleware to not minify the response of your views by
63adding a ``EXCLUDE_FROM_MINIFYING`` setting on your settings.py: ::
64
65 EXCLUDE_FROM_MINIFYING = ('^my_app/', '^admin/')
66
67Regex patterns are used for URL exclusion. If you want to exclude all URLs of
68your app, except a specific view, you can use the decorator ``minified_response``
69(check the next section above).
70
71Keeping comments
72----------------
73
74The default behaviour of the middleware is to remove all HTML comments. If you
75want to keep the comments, set the setting ``KEEP_COMMENTS_ON_MINIFYING``
76to ``True``: ::
77
78 KEEP_COMMENTS_ON_MINIFYING = True
79
80Using the decorator
81===================
82
83django-htmlmin also provides a decorator, that you can use only on views you
84want to minify the response: ::
85
86 from htmlmin.decorators import minified_response
87
88 @minified_response
89 def home(request):
90 return render_to_response('home.html')
91
92Decorator to avoid response to be minified
93------------------------------------------
94
95You can use the ``not_minified_response`` decorator on views if you want to avoid
96the minification of any specific response, without using the ``EXCLUDE_FROM_MINIFYING``
97setting: ::
98
99 from htmlmin.decorators import not_minified_response
100
101 @not_minified_response
102 def home(request):
103 return render_to_response('home.html')
104
105Using the html_minify function
106==============================
107
108If you are not working with Django, you can invoke the ``html_minify`` function
109manually: ::
110
111 from htmlmin.minify import html_minify
112 html = '<html> <body>Hello world</body> </html>'
113 minified_html = html_minify(html)
114
115Here is an example with a `Flask <http://flask.pocoo.org>`_ view: ::
116
117 from flask import Flask
118 from htmlmin.minify import html_minify
119
120 app = Flask(__name__)
121
122 @app.route('/')
123 def home():
124 rendered_html = render_template('home.html')
125 return html_minify(rendered_html)
126
127Keeping comments
128----------------
129
130By default, ``html_minify`` function removes all comments. If you want to keep
131them, you can pass ``False`` as value to ``ignore_comments`` parameter on that
132function: ::
133
134 from htmlmin.minify import html_minify
135 html = '<html> <body>Hello world<!-- comment to keep --></body> </html>'
136 minified_html = html_minify(html, ignore_comments=False)
137
138
139Using command line tool
140=======================
141
142If you are not even using Python, you can use the ``pyminify`` command line
143tool to minify HTML files: ::
144
145 $ pyminify index.html > index_minified.html
146
147You can also keep the comments, if you want: ::
148
149 $ pyminify --keep-comments index.html > index_minified_with_comments.html
150
151development
152===========
153
154* Source hosted at `GitHub <http://github.com/cobrateam/django-htmlmin>`_
155* Report issues on `GitHub Issues
156 <http://github.com/cobrateam/django-htmlmin/issues>`_
157
158Pull requests are very welcome! Make sure your patches are well tested.
159
160Running tests
161-------------
162
163If you are using a virtualenv, all you need to do is:
164
165::
166
167 $ make test
168
169community
170=========
171
172irc channel
173-----------
174
175#cobrateam channel on irc.freenode.net
176
177Changelog
178=========
179
180You can see the complete changelog in `releases page <https://github.com/cobrateam/django-htmlmin/releases>`_.
181
182LICENSE
183=======
184
185Unless otherwise noted, the django-htmlmin source files are distributed under the BSD-style license found in the LICENSE file.
186
