docs.howto.html-stylesheets.txt Maven / Gradle / Ivy
==============================================
Writing HTML (CSS) Stylesheets for Docutils_
==============================================
:Author: Lea Wiemann
:Contact: [email protected]
: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.
.. _Docutils: http://docutils.sourceforge.net/
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).
__ http://www.htmlhelp.com/reference/css/
__ http://www.htmlhelp.com/reference/css/all-properties.html
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.
.. base for relative links is /docutils/docs/howto/
.. _Docutils-users: ../user/mailing-lists.html#docutils-users
.. _configuration: ../user/config.txt
.. _sandbox: ../../../sandbox
.. _stylesheet collection: ../../../sandbox/stylesheets/
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End: