# Writing HTML (CSS) Stylesheets for Docutils

Author: | Lea Wiemann
Contact: | docutils-develop@lists.sourceforge.net
Date: | 2016-11-29
Revision: | 7977
Copyright: | This document has been placed in the public domain.

The look of Docutils' HTML output is customizable via CSS stylesheets. The default stylesheets can be found in the `docutils/writers/html*/` directories of the `html4css1` and `html-base` writers in the Docutils installation. Use the front-end command (`rst2html.py` or `rst2html5.py`) with the `--help` option and look at the description of the `--stylesheet-path` command-line option for the exact machine-specific location.

To customize the look of HTML documents, you can override the settings of the default stylesheet in your own stylesheet. 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.

Alternatively, copy the default style sheet to the same place as your output HTML files will go and 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 CSS 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.).

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.