docs/howto/html-stylesheets.txt

   1 ==============================================
   2  Writing HTML (CSS) Stylesheets for Docutils_
   3 ==============================================
   4
   5 :Author: Lea Wiemann
   6 :Contact: docutils-develop@lists.sourceforge.net
   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 CSS
  15 stylesheets.  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 Another good reference site is http://selfhtml.org (German and French).
  45
  46 __ http://www.htmlhelp.com/reference/css/
  47 __ http://www.htmlhelp.com/reference/css/all-properties.html
  48
  49 It is important that you do not edit a copy of ``html4css1.css``
  50 directly because ``html4css1.css`` is frequently updated with each new
  51 release of Docutils.
  52
  53 Also make sure that you import ``html4css1.css`` (using "``@import
  54 url(html4css1.css);``") because the definitions contained in the
  55 default stylesheet are required for correct rendering (margins,
  56 alignment, etc.).
  57
  58 Alternatively, specify both, the default stylesheet and your stylesheet
  59 to the ``--stylesheet`` or ``--stylesheet-path`` command line option (or the
  60 corresponding settings in a configuration_ file), e.g. ::
  61
  62   rst2html.py --stylesheet=html4css1.css,transition-stars.css
  63
  64 This is the preferable approach if you want to embed the stylesheet(s), as
  65 this ensures that an up-to-date version of ``html4css1.css`` is embedded.
  66
  67 If you think your stylesheet is fancy and you would like to let others
  68 benefit from your efforts, you are encouraged to post the stylesheet to the
  69 Docutils-users_ mailing list. It might find its place in the `stylesheet
  70 collection`_ in the Docutils Sandbox_.
  71
  72 If you decide to share your stylesheet with other users of Docutils,
  73 please keep website-specific customizations not applicable to
  74 Docutils' HTML code in a separate stylesheet.
  75
  76 .. base for relative links is /docutils/docs/howto/
  77
  78 .. _Docutils-users: ../user/mailing-lists.html#docutils-users
  79 .. _configuration: ../user/config.txt
  80 .. _sandbox: ../../../sandbox
  81 .. _stylesheet collection: ../../../sandbox/stylesheets/
  82
  83
  84
  85 \f
  86 ..
  87    Local Variables:
  88    mode: indented-text
  89    indent-tabs-mode: nil
  90    sentence-end-double-space: t
  91    fill-column: 70
  92    End: