Documents Live, a web authoring and publishing system
Documents Live, a web authoring and publishing system
If you see this, something is wrong
First published on Wednesday, Apr 10, 2024 and last modified on Sunday, Feb 22, 2026
LaTeX is designed for print.
Documents Live must produce Web pages, and, among other things, create HTML code.
LaTeX and HTML share many concepts, but are syntactically different, even though both of them are (mostly) markup languages.
Documents Live takes the following path when producing HTML code from LaTeX code:
it converts the LaTeX source code into an object-oriented model. Each type of object corresponds to a concept that LaTeX and HTML share
from that object-oriented model, it produces HTML code, as well as other web related resources
Documents Live tries its best to transpose the LaTeX concepts to HTML ones, but this requires a compromise between what each language allows.
Most notably, TeX, and hence LaTeX, are unseparable from fixed, pre-determined dimensions. Documents Live, on the other hand, must live in a world where the size and proportions of the target display is unknown at compile time. This is why it is impossible to implement TeX with the goal of achieveing responsive design.
Documents Live has to deal with three different languages: LaTeX, HTML and Markdown. Each language has its own set of reserved characters, and Documents Live does its best to manage them all.
HTML has five reserved characters:
<
>
' (single quote)
" (double quote)
&
When parsing your source code, Documents Live escapes these characters into special code. When producing the HTML code, Documents Live restores these characters as HTML entities. This is necessary to avoid cross site scripting attacks and keep the web site safe.
For instance, the < character is actually encoded as < in the HTML code.
If these characters are used in your document only for text (or math) content, this is not a problem.
However, if you use these characters for LaTeX (or TeX) variables, such as labels, file names, etc…, chances are great that this will result in mess in Documents Live code. So, replace these characters (especially the quotes) in your LaTeX variables.
Sometimes, it feels safer to put content inside curly braces ( { and }). As a general rule, Documents Live will not try to guess why you use these scoping delimiters, and if they are useful or not. One very good reason is that, in LaTeX, text and math are processed together, while, in Documents Live, they are processed by different engines. Of similar importance is the fact that Documents Live does not parse the source code on a character-by-character basis, but rather on an object-by-object basis, an object being a table, a paragraph, etc…
In most cases, the curly braces are used for command parsing. If they still appear in the HTML output, try to remove them; most probably, things will be fine, for the reason that TeX do things that are much more complicated than what Documents Live does.
By contrast, it is a good practice to always use the standard syntax \command{parameter} when using a command, and not a loose alternative.
These advices are for the preparation of LaTeX documents before upload.
As a general rule, LaTeX documents and Internet pages differ in the following point:
in LaTeX there is no seperation between form and matter
in a web page, the matter resides in the HTML code, while the form is handled by style sheets (CSS files generally)
In practice, if by necessity (like following a publisher's guidelines), or for esthetics, you have tampered with the default form of a LaTeX document, please consider removing the extra styling.
If you have a default style pre-print version of your document, use it instead of the version destined for publication in a journal.
Here is a guide for checking if your document is as ready as possible for publication in Documents Live.
Set your document class to one of the three LaTeX defaults: article, report or book. Do not use extra parameters, like a two column option. In this very case, two columns does not make sense in an internet document, because there is no "bottom" defined. Generally, any command that refers to some kind of page layout should be discarded, because there is no paging concept in a web document.
Use as few packages as possible. The following packages are supported by the MathJax engine:
amsmath
amssymb
MathJax is the Javascript engine that renders equations in your browser.
Documents Live has decent support (with occasional enhancements) for the following packages
the \includegraphics command from the graphics package, with support for remote files
hyperref
amsthm
acronym
algorithm
xcolor
Documents Live does not process tikz figures of any kind. Some support is offered to process them on your computer and then upload the result to your project. For more details, see the help page.
On the brighter side, Documents Live does a decent work at importing beamer presentations.
Typeset your document with the previous minimum setup and see what happens. When the typesetting process stumbles on something it does not understand, check if the command is really necessary and if there is not a simpler alternative.
If the document does not compile in this minimum setup and that you do need some extra commands, this does not prevents you from uploading your project to Documents Live. There are many ways to fix potential problems within Documents Live itself.
Attempting to typeset the document in this minimum setup is just here to evaluate how necessary some of your packages are to make your content understandable. We do do our best to emulate commonly used packages, beyond the previous list.
If the import/export/compile process has gone well on the server, this will be aknowleged by a success notification. In case of an error, you will see a red notification. In general, the best thing to do is to have a look at the log for your document. The log is accessible from the documents dashboard, and also from the HTML render.
There are two ways to debug your project.
To edit the source code for your document, select "Edit source" from the action menu of your document. In the editor, you can search replace, undo, redo and many other things that can be expected from an editor. It also has syntax coloring. When using the code editor, it is advisable to have another browser tab/window to see the result of your edit.
If the was an error in the import process, you can only fix it in the source code editor. If some macro has not been parsed correctly, the source code editor is the place to be.
When you are done with the heavy work and that the HTML exports works without too many errors, it may be easier to fix the errors in the inline editor. To use the inline editor, select "Inline edit" from the action menu in the dashboard, or, from the HTML render, select "Inline edit" from the view menu.
The essential difference between the source code editor and the inline editor, is that the inline editor edits visually the content of the document model, and does not modify the source code itself.
To edit buggy content, just click on it. You will be presented with a selection of Documents Live objects that contain the clicked element. Choose one of these, and there will appear an editor with two panels:
the top panel is the preview of your edit
the bottom panel is where you edit the source code for the corresponding object.
You can edit the code, select render from the editor menu, and a preview of the HTML render for the current object is displayed on the top panel. This can be done on any kind of Documents Live object, including equations.
Once you are happy with your edit, select the "Save to model" item from the editor menu. This translates your code into a local Documents Live object, which is then inserted inside the global document model.
When you are done with your editing, export your new model to HTML.
As I said before, the inline editor modifies the document model, and not the source code. If you compile or import the source code afterwards, the changes in the model will be lost. To avoid this, you can do a backup of you current document model to your source code.
To do so, select the "Save to LaTeX ..." item from the top "Edit" menu. After entering a description of your backup, Documents Live will export the current model to the "body" of a LaTeX code, i.e. what lies between the \begin{document} and the \end{document} statements.
This LaTeX code is then saved in two places:
inside the source code of your document in the database
into a text file
You can manage your backups by selecting the "Manage backups" item of the edit menu. After that, you can review your versions, revert to them, or erase them (one by one). An initial backup is performed at upload, so you can start over at the beginning.
Macros work as described in the Leslie Lamport book, but there are some caveat. Take for instance the following macro:
\newcommand{\norm}[1]{\left\lVert#1\right\rVert}The following code
\int_{0}^{t)\norm{x(s)}dswill work in latex. However, in Documents Live, the resulting code will be
\int_{0}^{t)\\ left\lVertx(s)\right\rVertdswhich is LaTeX gibberish. Don't hesitate to use spaces in your macro definitions like this
\newcommand{\norm}[1]{\left\lVert #1\right\rVert }This will give exactly the desired result in either environment, and the coding is less sloppy.
Except for equations and the like, \label commands are expected to stand after the command they refer to, possibly after some spaces or new line characters. If you put it elsewhere, Documents Live will not try to determine if the \label commands refers to some inner environment or not. So keep it simple, place your label declarations just after the corresponding LaTeX declaration.
Documents Live is very strict regarding commands; in particular, there should be no space or line breaks between the arguments of a command. For instance
\acro{IMT} {International Mobile Telecommunications}may work in LaTeX, but it does not work in Documents Live because of the blank space between the first parameter and the second parameter.
The following code does work in Documents Live:
\acro{IMT}{International Mobile Telecommunications}This zero tolerance in Documents Live is necessary to implement macros properly in the system.
There may be several reasons with some of your theorem-like environments produce errors or do not render correctly
Theorems are complex environments. Documents Live expects your theorem label to follow immediately (or after some spaces or new lines) the \begin statement that opens your theorem code.
If the label is somewhere inside the theorem code, it is difficult for Documents Live to find it. So, make it simple and declare your label just after the \begin statement.
Due to their complexity, proofs are assimilated to theorems. Since a theorem cannot include another one in Documents Live, proofs should not be inside a theorem code. Put your proof environment after the end of the theorem.
For the definition of a theorem, the syntax is
\newtheorem{name}{caption}[within]
without spaces between the command and is parameters. Since Documents Live does its own numbering, the within parameter is ignored.
We have read the documentations for a lot of packages or document classes that define their own implementation of theorem definitions. Their benefit is essentially cosmetic and do not change the meaning of the \newtheorem command. If you use these variants, know that LaTeX2web does not support them because the extra complexity they add to the source code parsing is not worth the effort.
If you use these variants and have errors in your log, or HTML output, due to some non-standard theorem definition, please correct your source code to use the standard form.
If you see some red text where there should be an equation, this means that the MathJax engine, which is responsible for the rendering of math content, could no process this part of the equation.
To see what eventually went wrong, right-click on the incriminated portion, and MathJax will give the possibility to see the underlying LaTeX code. Using this information, you should try to fix your LaTeX code by editing the source code of your document.
Another option is to use the Inline Editor to edit the portion of the document that produces an error. Not that this will update the Document Model, and not the source code itself.
Also, the error may be due to a faulty macro. In this case, since Documents Live executes the macros before creating the model, you will not fix the problem by using the Inline Editor. Use the Source Code Editor instead.
being sloppy when using math accents. The proper syntax for a math accent is \hat{a} and not \hat a
trying to draw things with LaTeX. MathJax cannot do this. \mathbin, for instance, is not supported.
using special TeX fonts. Mathjax supports vanilla LaTeX symbols and amsmath symbols and commands.
This probably because the \label command was placed somewhere where Documents Live does not expect it. Put your label declarations just after the command or environment delaration that you want them to refer to.
There are five reserved characters in HTML:
&
"
'
<
>
Documents Live escapes them to avoid inserting malicious code in the web page.
However, the way it does this corrupts the label names, so please rename your \label and \ref to avoid using these characters.
The \def command is supported (only for simple usage).
Other commands are not implemented, because they may (and often do) include commands that we cannot implement in Documents Live. The bottom line is: Documents Live is NOT a TeX emulator. This also why the endif package is not supported.
Log entries are generated when importing and exporting documents. The log can be viewed from the "Action" menu attached to the document in the Documents page.
You can also access the log from the Document View page in the "View" menu, and on the Inline Edit page in the "Edit" menu. It is currently not accessible from the publication view, which is not designed for document authoring. From the publication page, you can switch to the document view page from the"View" menu.
Whatever the language, you document will be uploaded as a zip archive. ALL your files must be included in your archive. This includes
Your main document file
All source files that will be included in the main document
Your bibliography, if any
Your media files
Whatever the hierarchy within your archive, all files will be stored at root level during the upload process. So please avoid duplicate file names.
If you wonder what UTF-8 encoding is, the Wikipedia page is rather clear. If your document only contains ASCII characters, it is entirely compatible with UTF-8.
If your document contains characters that are not ASCII, you should check that it is UTF-8 encoded, as UTF-8 is the de facto standard for web page encoding.
Here is a step by step guide to convert a text file to a version with UTF-8 encoding:
If you do not have it, download Visual Studio Code. This is a code editor that works well with source code files. It is free and multi platform (Windows, Mac, Linux).
Open your text file with VS code. At the bottom of the editor window, in the status bar, you will see the encoding of your file:
In the example above, the encoding is one of the encodings that Windows uses. This encoding is different from UTF-8. Click on the encoding type; the following pop up menu will appear at the top of the editor window:
Choose "Save with Encoding", and a select menu appears you that lets you choose the desired encoding:
Select "UTF-8" at the top, save, and you're done.
The PDF file format is NOT supported natively in web pages, and this is not about to change. Supported file formats are currently
png
jpeg, jpg
svg
gif
mp4
CSV files, although not media in the strict sense, can be uploaded for usage in Documents Live.
Note that Matlab can export its figures to svg.
Technically, you can upload pdf and eps images. You will be given the opportunity to convert them to png files, using imagick on top of ghostscript. The process, however, can be quite slow. Pdf/eps files with a size greater than 200 KB will be displayed in red, indicating that their conversion may bring your Documents Live session to a halt. Try to convert this files on your computer and upload the result to your document (this can be done from the documents dashboard).