docutils/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 stylesheets.
  15 The default stylesheets can be found in the
  16 ``docutils/writers/html*/`` directories of the ``html4css1`` and
  17 ``html-base`` writers in the Docutils installation.  Use the front-end
  18 command (``rst2html.py`` or ``rst2html5.py``) with the
  19 ``--help`` option and look at the description of the ``--stylesheet-path``
  20 command-line option for the exact machine-specific location.
  21
  22 To customize the look of HTML documents, you can override the settings
  23 of the default stylesheet in your own stylesheet. Specify both, the
  24 default stylesheet and your stylesheet to the ``--stylesheet`` or
  25 ``--stylesheet-path`` command line option (or the corresponding
  26 settings in a configuration_ file), e.g. ::
  27
  28   rst2html.py --stylesheet=html4css1.css,transition-stars.css
  29
  30 This is the preferable approach if you want to embed the stylesheet(s), as
  31 this ensures that an up-to-date version of ``html4css1.css`` is embedded.
  32
  33 Alternatively, copy the default style sheet to the same place as your
  34 output HTML files will go and place a new file (e.g. called
  35 ``my-docutils.css``) in the same directory and use the following
  36 template::
  37
  38     /*
  39     :Author: Your Name
  40     :Contact: Your Email Address
  41     :Copyright: This stylesheet has been placed in the public domain.
  42
  43     Stylesheet for use with Docutils.  [Optionally place a more
  44     detailed description here.]
  45     */
  46
  47     @import url(html4css1.css);
  48
  49     /* Your customizations go here.  For example: */
  50
  51     h1, h2, h3, h4, h5, h6, p.topic-title {
  52       font-family: sans-serif }
  53
  54 For help on the CSS syntax, please see `the WDG's guide to Cascading
  55 Style Sheets`__ and, in particular, their `list of CSS properties`__.
  56 Another good reference site is http://selfhtml.org (German and French).
  57
  58 __ http://www.htmlhelp.com/reference/css/
  59 __ http://www.htmlhelp.com/reference/css/all-properties.html
  60
  61 It is important that you do not edit a copy of ``html4css1.css``
  62 directly because ``html4css1.css`` is frequently updated with each new
  63 release of Docutils.
  64
  65 Also make sure that you import ``html4css1.css`` (using "``@import
  66 url(html4css1.css);``") because the definitions contained in the
  67 default stylesheet are required for correct rendering (margins,
  68 alignment, etc.).
  69
  70 If you think your stylesheet is fancy and you would like to let others
  71 benefit from your efforts, you are encouraged to post the stylesheet to the
  72 Docutils-users_ mailing list. It might find its place in the `stylesheet
  73 collection`_ in the Docutils Sandbox_.
  74
  75 If you decide to share your stylesheet with other users of Docutils,
  76 please keep website-specific customizations not applicable to
  77 Docutils' HTML code in a separate stylesheet.
  78
  79 .. base for relative links is /docutils/docs/howto/
  80
  81 .. _Docutils-users: ../user/mailing-lists.html#docutils-users
  82 .. _configuration: ../user/config.txt
  83 .. _sandbox: ../../../sandbox
  84 .. _stylesheet collection: ../../../sandbox/stylesheets/
  85
  86
  87
  88 \f
  89 ..
  90    Local Variables:
  91    mode: indented-text
  92    indent-tabs-mode: nil
  93    sentence-end-double-space: t
  94    fill-column: 70
  95    End: