HTMLSave

How to save your Notebook as HTML

Using the front end, issue the menu command:

  File
    Save As Special...
      HTML

to save the currently selected notebook.  A dialog box will prompt you for destination file or directory.

As a kernel command:

HTMLSave["output.html",  "input.nb"]

Important:  Even when you execute this as a kernel command, the kernel must be connected to a front end.  HTMLSave needs certain services from the front end such as conversion to GIF, and it needs to query the front end for settings.

The second argument is interpreted as a notebook.  It can be a variety of things, including

"filename.nb"
"window name"
Notebook[] expression
NotebookObject[...]
{Cell, Cell, ...}
Cell[...]
BoxData[...]

If it isn't a complete notebook, e.g. a list of Cells or a BoxData, it will be wrapped in a Notebook to make it a whole document.

Note:  Although HTMLSave assumes that the conversion is of entire documents, a current item of development is conversion of individual box expressions or other pieces of notebooks to snippets of HTML.  This is analogous to the built-in TeXForm function, so we may add an HTMLForm function, or more likely, include it in the much more general Export mechanism in the upcoming version.

How to map Mathematica styles to HTML elements

The style sheet for any of your Mathematica notebooks is a set of cells defining named styles that can be applied to whole cells, or to smaller pieces of text.  The style of a cell or a piece of text identifies that piece's meaning, and has a distinct appearance, and perhaps non-visual properties.  Hence, Mathematica styles are used for markup, just as tags are in HTML, or in other SGML or XML applications.  They bind presentation and other properties to that named element type.

As a sample, from the ordinary Default.nb style sheet, here is the Cell defining the "InlineFormula" style:

Once you have a style sheet for your notebook, you can add a cell option called ConversionRules to some or all of these cells, in order to specify what HTML tag, or nested tags, this cell style should come out as in the HTML document.

The above specifies that any StyleBox of style "MyStyle" should have its contents wrapped in bold and code tags in HTML, and any whole cell of style "MyStyle" should additionally be wrapped in <P>, since it is block-level.

The HTML tags that specify appearance, e.g. <FONT>, are controversial, because they are often misused:  they are used instead of tags that convey meaning or structure, so they specify one notion of how a document should look, not what its parts mean or how they are structured.  The purists believe that appearance information should not be part of the document content at all.  Personally, I tend to stay away from them, but the less radical advice I give people is:  if you insist on embedding appearance directives, at least use them in addition to markup that indicates role (structure, meaning).  This way, information isn't lost, in case the document needs to be converted to something else later, or a filter strips out presentation tags.  During the development of Version 3, I used Mathematica programs to convert between Mathematica notebooks and other document languages, and I can tell you first hand that it is very time-consuming and frustrating to develop heuristics to figure out the different roles of pieces of text that were marked up as "FontSize -> 14, FontFamily -> Courier".  In one instance, the document author switched to Courier to represent a Mathematica function name, in another to represent code in another language such as C, in another to do something else.

The major browsers are growing more mature in this respect.  With the recent promotion of XML and Cascading Style Sheets Level 2 to full Recommendations at the World Wide Web Corsortium, and HTML 4.0 which official supports style sheet import, the future is in separation of appearance and structure.

With XML and style sheets, you can make up all your own element types to suit the meanings and structures you need, and associate appearance characteristics with them.

Philosophical point

It's important to use StyleBox in Mathematica documents to convey the intended meaning and appearance, so HTMLSave doesn't have to guess or use vanilla markup rules.  This affords much more control to the author.

A few things added or fixed since 3.0

1.  More appearance characteristics are respected, e.g. font color, size, underlining, and so on.

2.  The "tiny GIF" problem for typeset expressions has been fixed.

3.  A lone GridBox is converted to a table, instead of to a monolithic GIF image.

But also, since so many people do manual formatting of tables in their text cells, using tabs, I added a heuristic to determine when a series of lines probably is meant as a table, and I convert that.

row  :=  [possible \t]   a   [at least one \t]

row possibly separated by one or more \n

Still, I recommend using in-line GridBox if you can, because it's better to have the meaning clearly conveyed in the source document.

4.  MathML output

5.  Brand new:  Mathematica's native linear syntax for typeset expressions, for which there is an applet that calls on the FE to produce graphic for it and render it in the HTML.

Future Directions:  Style sheets, SGML/XML

There is a fair amount of support for level 1 of Cascading Style Sheets in the version 4 browsers, but since the support is still erratic, and many people haven't upgraded to version 4 browsers, style sheets haven't been the highest development priority for HTMLSave yet.

In a future version, HTMLSave will include a CSS style sheet that makes HTML elements mimic Mathematica styles as much as possible.  Since the translation of Mathematica styles to HTML elements is not one-to-one (the domain, Mathematica styles, has no limit on the number of elements, some very rich style sheets might exist), perhaps the CLASS attribute available for all elements in HTML 4.0 will be used to distinguish the source document's markup elements, and to bind different appearance to them.

Exactly mimicking a Mathematica notebook might not be the author's intention, so of course this style sheet need not be used.

In a future version, there will be a program to take a Mathematica style sheet, and convert it to another style sheet language, including CSS1, CSS2, and XSL.  With this, any custom style sheet could be approximated in the destination language.

Probably this will also produce an XML DTD corresponding to the style sheet and notebook elements.