diff --git a/docs/patterns/favicon.rst b/docs/patterns/favicon.rst new file mode 100644 index 00000000..6cf64ea0 --- /dev/null +++ b/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 + + + +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 `_ article on + Wikipedia diff --git a/docs/patterns/index.rst b/docs/patterns/index.rst index 21f3a562..68cff143 100644 --- a/docs/patterns/index.rst +++ b/docs/patterns/index.rst @@ -32,3 +32,4 @@ Snippet Archives `_. errorpages lazyloading mongokit + favicon