|
|
|
|
|
==============================================
|
|
|
|
|
|
Writing HTML (CSS) Stylesheets for Docutils_
|
|
|
|
|
|
==============================================
|
|
|
|
|
|
|
|
|
|
|
|
:Author: Lea Wiemann
|
|
|
|
|
|
:Contact: docutils-develop@lists.sourceforge.net
|
|
|
|
|
|
:Date: $Date: 2016-11-29 13:00:39 +0100 (Di, 29 Nov 2016) $
|
|
|
|
|
|
:Revision: $Revision: 7977 $
|
|
|
|
|
|
: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 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).
|
|
|
|
|
|
|
|
|
|
|
|
__ 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.).
|
|
|
|
|
|
|
|
|
|
|
|
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:
|
