==============================================
 Writing HTML (CSS) Stylesheets for Docutils_
==============================================

:Author: Lea Wiemann
:Contact: docutils-develop@lists.sourceforge.net
:Date: $Date: 2012-01-03 20:23:53 +0100 (Tue, 03 Jan 2012) $
:Revision: $Revision: 7302 $
:Copyright: This document has been placed in the public domain.

.. _Docutils: http://docutils.sourceforge.net/


The look of Docutils' HTML output is customizable via CSS
stylesheets.  The default stylesheet is called ``html4css1.css`` and
can be found in the ``writers/html4css1/`` directory of the Docutils
installation.  Use the command ``rst2html.py --help`` and look at the
description of the ``--stylesheet-path`` command-line option for the
exact machine-specific location.

To customize the stylesheet, first copy ``html4css1.css`` to the same
place as your output HTML files will go.  Next, place a new file
(e.g. called ``my-docutils.css``) in the same directory and use the
following template::

    /*
    :Author: Your Name
    :Contact: Your Email Address
    :Copyright: This stylesheet has been placed in the public domain.

    Stylesheet for use with Docutils.  [Optionally place a more
    detailed description here.]
    */

    @import url(html4css1.css);

    /* Your customizations go here.  For example: */

    h1, h2, h3, h4, h5, h6, p.topic-title {
      font-family: sans-serif }    

For help on the CSS syntax, please see `the WDG's guide to Cascading
Style Sheets`__ and, in particular, their `list of CSS1 properties`__.
Another good reference site is http://selfhtml.org (German and French).

__ http://www.htmlhelp.com/reference/css/
__ http://www.htmlhelp.com/reference/css/all-properties.html

It is important that you do not edit a copy of ``html4css1.css``
directly because ``html4css1.css`` is frequently updated with each new
release of Docutils.

Also make sure that you import ``html4css1.css`` (using "``@import
url(html4css1.css);``") because the definitions contained in the
default stylesheet are required for correct rendering (margins,
alignment, etc.).

Alternatively, specify both, the default stylesheet and your stylesheet
to the ``--stylesheet`` or ``--stylesheet-path`` command line option (or the
corresponding settings in a configuration_ file), e.g. ::

  rst2html.py --stylesheet=html4css1.css,transition-stars.css

This is the preferable approach if you want to embed the stylesheet(s), as
this ensures that an up-to-date version of ``html4css1.css`` is embedded.

If you think your stylesheet is fancy and you would like to let others
benefit from your efforts, you are encouraged to post the stylesheet to the
Docutils-users_ mailing list. It might find its place in the `stylesheet
collection`_ in the Docutils Sandbox_.

If you decide to share your stylesheet with other users of Docutils,
please keep website-specific customizations not applicable to
Docutils' HTML code in a separate stylesheet.

.. base for relative links is /docutils/docs/howto/

.. _Docutils-users: ../user/mailing-lists.html#docutils-users
.. _configuration: ../user/config.txt
.. _sandbox: ../../../sandbox
.. _stylesheet collection: ../../../sandbox/stylesheets/




..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End: