Writing HTML (CSS) Stylesheets for Docutils¶
Author: | Lea Wiemann |
---|---|
Contact: | docutils-develop@lists.sourceforge.net |
Date: | $Date: 2012-01-03 20:23:53 +0100 (Die, 03. Jän 2012) $ |
Revision: | $Revision: 7302 $ |
Copyright: | This document has been placed in the public domain. |
orphan: | 本文档不能通过导航到达 |
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).
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.