docutils/docs/howto/html-stylesheets.txt

   1 ==============================================
   2  Writing HTML (CSS) Stylesheets for Docutils_
   3 ==============================================
   4
   5 :Author: Felix Wiemann
   6 :Contact: Felix.Wiemann@ososo.de
   7 :Date: $Date$
   8 :Revision: $Revision$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 .. _Docutils: http://docutils.sourceforge.net/
  12
  13
  14 The look of Docutils' HTML output is customizable via a CSS
  15 stylesheet.  The default stylesheet is called ``html4css1.css`` and
  16 can be found in the ``writers/html4css1/`` directory of the Docutils
  17 installation.  Use the command ``rst2html.py --help`` and look at the
  18 description of the ``--stylesheet-path`` command-line option for the
  19 exact machine-specific location.
  20
  21 To customize the stylesheet, first copy ``html4css1.css`` to the same
  22 place as your output HTML files will go.  Next, place a new file
  23 (e.g. called ``my-docutils.css``) in the same directory and use the
  24 following template::
  25
  26     /*
  27     :Author: Your Name
  28     :Contact: Your Email Address
  29     :Copyright: This stylesheet has been placed in the public domain.
  30
  31     Stylesheet for use with Docutils.  [Optionally place a more
  32     detailed description here.]
  33     */
  34
  35     @import url(html4css1.css);
  36
  37     /* Your customizations go here.  For example: */
  38
  39     h1, h2, h3, h4, h5, h6, p.topic-title {
  40       font-family: sans-serif }
  41
  42 For help on the CSS syntax, please see `the WDG's guide to Cascading
  43 Style Sheets`__ and, in particular, their `list of CSS1 properties`__.
  44
  45 __ http://www.htmlhelp.com/reference/css/
  46 __ http://www.htmlhelp.com/reference/css/all-properties.html
  47
  48 It is important that you do not edit a copy of ``html4css1.css``
  49 directly because ``html4css1.css`` is frequently updated with each new
  50 release of Docutils.
  51
  52 Also make sure that you import ``html4css1.css`` (using "``@import
  53 url(html4css1.css);``") because the definitions contained in the
  54 default stylesheet are required for correct rendering (margins,
  55 alignment, etc.).
  56
  57 If you think your stylesheet is fancy and you would like to let others
  58 benefit from your efforts, you are encouraged to post the stylesheet
  59 to the Docutils-users_ mailing list.  We can upload it to the
  60 `Docutils repository`__ if you would like us to do so.
  61
  62 If you decide to share your stylesheet with other users of Docutils,
  63 please keep website-specific customizations not applicable to
  64 Docutils' HTML code in a separate stylesheet.
  65
  66 .. _Docutils-users: ../user/mailing-lists.html#docutils-users
  67 __ http://docutils.sourceforge.net/sandbox/stylesheets/
  68
  69 \f
  70 ..
  71    Local Variables:
  72    mode: indented-text
  73    indent-tabs-mode: nil
  74    sentence-end-double-space: t
  75    fill-column: 70
  76    End: