1 ==============================================
2 Writing HTML (CSS) Stylesheets for Docutils_
3 ==============================================
6 :Contact: docutils-develop@lists.sourceforge.net
9 :Copyright: This document has been placed in the public domain.
11 .. _Docutils: http://docutils.sourceforge.net/
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.
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
28 :Contact: Your Email Address
29 :Copyright: This stylesheet has been placed in the public domain.
31 Stylesheet for use with Docutils. [Optionally place a more
32 detailed description here.]
35 @import url(html4css1.css);
37 /* Your customizations go here. For example: */
39 h1, h2, h3, h4, h5, h6, p.topic-title {
40 font-family: sans-serif }
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).
46 __ http://www.htmlhelp.com/reference/css/
47 __ http://www.htmlhelp.com/reference/css/all-properties.html
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
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,
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. ::
62 rst2html.py --stylesheet=html4css1.css,transition-stars.css
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.
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_.
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.
76 .. base for relative links is /docutils/docs/howto/
78 .. _Docutils-users: ../user/mailing-lists.html#docutils-users
79 .. _configuration: ../user/config.txt
80 .. _sandbox: ../../../sandbox
81 .. _stylesheet collection: ../../../sandbox/stylesheets/
90 sentence-end-double-space: t