New Python Markdown extension full_html
Contents
Adds a <head>
section to the output, wraps the body in <body>
and </body>
tags,
and wraps the entire output in <html>
and </html>
tags.
<title>
tag in the HTML <head>
The <head>
gets a <title>
from one of the following (first one found is used):
- A
title
configuration option - The value in an
MDX_FULL_HTML_TITLE
environment variable - A
title:
metadata tag, if the meta extension is enabled - The value of the first header found in the text, even if it’s not level 1
The above order means the default title is taken from the first header found in
the document. That can be overidden by a title:
in the metadata, which in turn
can be overriden by specifying export MDX_FULL_HTML_TITLE="
title
"
on
the command line (bash on *nix) or set MDX_FULL_HTML_TITLE=
title
(Windows
cmd.exe) before running the markdown processor. All these values can be
overridden within the Python interactive environment by setting the title
configuration value when invoking markdown.markdown.
Character set declaration
The <head>
section can add the following line:
<meta http-equiv='Content-Type' content='text/html; charset=CHARSET'/>
if one of the following is found (first one found is used):
- A
charset
configuration entry - The value in an
MDX_FULL_HTML_CHARSET
environment variable - A
charset
metadata tag, if the meta extension is enabled
Similar to the hierarchy in the title
setting, the charset
is set in the
following increasing order of importance: a charset:
metadata entry, an
environment variable named MDX_FULL_HTML_CHARSET
, and finally a charset
configuration entry.
Including CSS
CSS can be added to the <head>
, either as a URL to the CSS or the contents of
a CSS file. The following are checked in order, and each one found is added to
the CSS:
- A
css_url:
metadata tag, if the meta extension is enabled - The value in an
MDX_FULL_HTML_CSS_URL
environment variable - A
css_url
config entry - The contents of the file named in:
- A
css_file:
metadata tag, if the meta extension is enabled - The value in an
MDX_FULL_HTML_CSS_FILE
environment variable - A
css_file
config entry
- A
The above order implies that CSS rules in the css_url:
metadata tag are the
“base” rules; they can be overridden or supplemented with additional rules
found at a URL named in the MDX_FULL_HTML_CSS_URL
environment variable, and
further refined via CSS found a css_url
configuration entry. The ruleset can
be extended further by using a css_file:
metdata tag, an environment variable
named MDX_FULL_HTML_CSS_FILE,
and finally a css_file
configuration entry.
If you want to include only one set of CSS, you can specify it any way you want: a metadata tag, an environment varliable, or a configuration entry.
A missing CSS file is not considered fatal. A warning is printed to stderr if
verbose
mode is enabled, either as a configuration option or by specifying
the -v/--verbose
option to the command line program.