Pattern documentation for favicons

Signed-off-by: Armin Ronacher <armin.ronacher@active-4.com>

docs/patterns/favicon.rst

@@ -0,0 +1,55 @@
+.. _favicon:
+
+Adding a favicon
+================
+
+A "favicon" is an icon used by browsers for tabs and bookmarks. This helps
+to distinguish your website and to give it a unique brand.
+
+A common question is how to add a favicon to a flask application. First, of
+course, you need an icon. It should be 16 × 16 pixels and in the ICO file
+format. This is not a requirement but a de-facto standard supported by all
+relevant browsers. Put the icon in your static directory as
+:file:`favicon.ico`.
+
+Now, to get browsers to find your icon, the correct way is to add a link
+tag in your HTML. So, for example:
+
+.. sourcecode:: html+jinja
+
+    <link rel="shortcut icon" href="{{ url_for('static', filename='favicon.ico') }}">
+
+That's all you need for most browsers, however some really old ones do not
+support this standard. The old de-facto standard is to serve this file,
+with this name, at the website root. If your application is not mounted at
+the root path of the domain you either need to configure the webserver to
+serve the icon at the root or if you can't do that you're out of luck. If
+however your application is the root you can simply route a redirect::
+
+    app.add_url_rule('/favicon.ico',
+                     redirect_to=url_for('static', filename='favicon.ico'))
+
+If you want to save the extra redirect request you can also write a view
+using :func:`~flask.send_from_directory`::
+
+    import os
+    from flask import send_from_directory
+
+    @app.route('/favicon.ico')
+    def favicon():
+        return send_from_directory(os.path.join(app.root_path, 'static'),
+                                   'favicon.ico', mimetype='image/vnd.microsoft.icon')
+
+We can leave out the explicit mimetype and it will be guessed, but we may
+as well specify it to avoid the extra guessing, as it will always be the
+same.
+
+The above will serve the icon via your application and if possible it's
+better to configure your dedicated web server to serve it; refer to the
+webserver's documentation.
+
+See also
+--------
+
+* The `Favicon <http://en.wikipedia.org/wiki/Favicon>`_ article on
+  Wikipedia

docs/patterns/index.rst

@@ -32,3 +32,4 @@ Snippet Archives <http://flask.pocoo.org/snippets/>`_.
    errorpages
    lazyloading
    mongokit
+   favicon