Documents Live, a web authoring and publishing system
If you see this, something is wrong
Table of contents
First published on Saturday, Jan 25, 2025 and last modified on Tuesday, Sep 22, 2026 by François Chaplais.
1 Introduction
You can access a document in edit mode in two ways:
- in the document dashboard, select the
Inline edititem in the Action menu for your document - from the View page of your document, select the
Inline edititem in the View menu
Apart from some initial code, most of this documentation was written interactively using the Inline Editor.
Note: before reading what follows, make sure you have understood the help text about the Documents Live workflow and the internal model.
2 Opening the Inline Editor
To edit an element, hover over it. In most of the cases, clicking on the elemnt will open the editor for that content.
In some cases, there may be several elements stacked on top of each other. To select the right element, hover on the content and watch the tooltips that appear. They indicate which kind of element you will edit. When you are satisfied with the element type, just click to open the editor.
Here is a screenshot.
Note: if you click on a section title, this will collapse/expand the corresponding section. This functionality is active to let you to organize your work space. To open a section in the Inline Editor, press the alt/option key while clicking on the section title. This will edit the section.
3 Edit
3.1 The editor panes
The editor consists in two stacked panes:
- On top is a preview corresponding to the code. It has a gray background, unless you are editing a section, which has a slightly different user interface.
- Below is the code editor for the object.
3.2 The code editor
Th code editor has two parts: on top is the toolbar, and below is the code editor itself. The editor is powered by Ace .
3.2.1 The toolbar
The left part is devoted to the search and replace operations. At its right is a collection of LaTeX-related editing buttons. Finally, at the right, you have the Inline Editor dropdown menu that lets you perform top-level operations related to the Inline Editor.
3.2.1.1 Search and replace
The input field on the left is where you enter the string you are looking for. The search is case-sensitive. To launch the search, click on the magnifier icon next to it. Pressing the enter/return key will not initiate the search. Actually, the keyboard action is first intercepted by the browser which, in this case, will reload the page. Doing so would lose your unsaved changes.
You can initiate four types of searches:
- standard search
- case insensitive search
- use a regular expression
- search for a whole word
When you have found your first match, hit Ctrl-K (Windows/Linux) or Command-G (Mac) to search for the next occurrence.
At the right of the replace field are two search and replace buttons. The first one will do a single search and replace operation. Hitting it repeatedly will repeat the process for the next occurrences. The second button performs a global search and replace.
3.2.1.2 LaTeX tools
Here is a quick description of the LaTeX related dropdown menus, as seen in figure 3.
- This dropdown menu lets you insert a sectioning command. If some text was selected before performing the action, it will be used as the parameter of the sectioning command, i.e., the section title. This is a general behavior (when applicable) of the LaTeX editor actions.
- This lets you style the selected text.
- gives you access to some common LaTeX commands.
- gives you access to some common LaTeX environments.
- gives access to Documents Live specific commands. The
environmentaction creates an environment whose name is the selected text. For instance, to create averbatimenvironment, type verbatim in the editor, select the word, and use theenvironmentaction on it. - is dedicated to Documents Live styling commands fo the web (borders, margins, etc...)
- use the selection to ask a question to AI
3.2.1.3 The Edit dropdown menu
Here is a quick description of the LaTeX related dropdown menus, as seen in figure 4
Edit dropdown menu in action.
Here are the actions available
- Render This renders the current code in the top render pane. This lets you preview if the output of your code will be correct.
- Revert to saved This reset the editor state to the HTML and LaTeX code corresponding to the last save.
- Close This closes the Inline Editor. You cannot have to editors open at the same time. This will not reload the page. To recover the saved HTML version of the document, just reload the page.
- Save to model This saves the currently edited object to the model. The next
Revert to savedaction wil revert to this. - Save to model and update HTML This saves the currently edited object to the model and to HTML. This only modifies the part of the document that correspond to the edited objects. The next
Revert to savedaction wil revert to this. - Export model to HTML This exports the saved model to HTML and reloads the page. This is a global export to HTML, you should avoid it on large documents.
- Spelling This opens an interactive session where you can spell check the selection
- Syntax This checks the most common errors, like unmatched
\beginand\end, or lis-matched dollar signs. - Markdown to LaTeX This converts the selection frm Markdown code to LaTeX.
- LaTeX to Markdown The other way round.
3.2.1.4 Complex search and replace
3.2.1.4.1 Find & replace a LaTeX command
The editor’s search/replace box doesn’t just look for plain text — it understands LaTeX commands and their arguments. Type a command name in the search box (e.g. textbf) and, optionally, what to put instead in the replace box (e.g. emph): every matching command in your selection (or the whole document, if nothing is selected) gets swapped in one pass.
Leaving the replace box empty is a special, very common case: it removes the command but keeps the text that was inside it.
The two boxes, in plain terms
- Search box — the command you’re looking for, e.g.
textbfor\textbf(the backslash is optional, it’s added for you if you forget it). - Replace box — exactly what should appear instead, written out infull, e.g.
emphor\emph. Same rule: the backslash is optional.
The one thing to keep in mind, and the source of most surprises: the replace box is not a template that reuses the text you’re replacing. Whatever you type in the replace box is what ends up in the document, verbatim — the original command’s own arguments are discarded unless you retype them yourself. See the pitfall in the examples below.
Narrowing the search to a specific value
If you only write a command name (no {...} or [...] after it), the search matches every occurrence of that command, no matter what’s inside its arguments.
If you add {...} or [...] after the command name in the search box, you’re asking for an exact match: only commands whose argument is exactly that text will be touched. This also means an empty {} in the search box is not a wildcard — it only matches a command whose argument is truly empty, not "any argument."
Matching is also case-sensitive: searching for textbf will not touch \TextBf.
Examples
3.1.3.1 Remove a command, keep its text
| Search |
textbf
|
| Replace | (empty) |
| Before |
Hello \textbf{World} and \textbf{Foo}
|
| After |
Hello World and Foo
|
Leaving replace empty strips the command and its braces away and keeps the text that was inside — this is the standard way to "undo" a formatting command everywhere in a document.
3.1.3.2 Swap one command for another
| Search |
textbf
|
| Replace |
emph
|
| Before |
Hello \textbf{World} and \textbf{Foo}
|
| After |
Hello \emph and \emph
|
⚠️ Pitfall: "World" and "Foo" have vanished. Since the replace box didn’t include a {...} of its own, the tool has nothing to put the original text into, and drops it. If you want to keep the wrapped text, you need to write
it out yourself — see example 6.
3.1.3.3 A "replace" that includes its own text
| Search |
emph
|
| Replace |
textbf{fixed text}
|
| Before |
\emph{hi}
|
| After |
\textbf{fixed text}
|
Whatever text you put inside the replace box’s own {...} is what shows up — here, "hi" is discarded and "fixed text" appears instead, because that’s what was typed in the replace box, not because it was somehow derived from "hi".
3.1.3.4 Only replace one specific occurrence, by its exact content
| Search |
textbf{Warning}
|
| Replace |
emph
|
| Before |
\textbf{Warning}: careful. \textbf{Note}: ok.
|
| After |
\emph: careful. \textbf{Note}: ok.
|
Because the search box specified {Warning}, only the \textbf{Warning} occurrence was touched. \textbf{Note} was left alone because "Note" isn’t an exact match for "Warning".
3.1.3.5 Empty braces {} mean "empty", not "anything"
| Search |
textbf{}
|
| Replace |
emph
|
| Before |
\textbf{} and \textbf{World}
|
| After |
\emph and \textbf{World}
|
\textbf{} (a genuinely empty argument) matched, but \textbf{World} didn’t — {} in the search box asks for an empty value, not "match anything here". To match regardless of content, don’t write any braces at all in the search box (compare with example 2).
3.1.3.6 Renaming a command while keeping its text — do it value by value
| Search |
ref{Intro}
|
| Replace |
autoref{Intro}
|
| Before |
\ref{Intro} text \ref{Methods} text
|
| After |
\autoref{Intro} text \ref{Methods} text
|
To rename a command and keep a specific piece of text, put that exact text in both boxes. Only the occurrence that matches the search box’s exact value is changed — \ref{Methods} is untouched. Run the tool again with ref{Methods} / autoref{Methods} to handle that one too. There’s no way to say "keep whatever was inside" for varying text — each distinct value needs its own search/replace pass.
3.1.3.7 Every matching occurrence is replaced in one pass
| Search |
ref
|
| Replace |
autoref
|
| Before |
\ref{Intro} text \ref{Methods} text
|
| After |
\autoref {text} \autoref {text}
|
Both occurrences were replaced in a single click — but, as in example 2, their labels were dropped because the replace box didn’t repeat them.
3.1.3.8 Optional arguments ([...]) follow the same rule
| Search |
includegraphics
|
| Replace |
includegraphics[width=10cm]
|
| Before |
\includegraphics[width=5cm]{img.png}
|
| After |
\includegraphics[width=10cm]
|
The filename, {img.png}, is gone — the replace box only defined the [width=...] part, not a {...} part, so the mandatory argument had nowhere to go. To keep the filename, write out the full replacement including it: includegraphics[width=10cm]{img.png}.
3.1.3.9 An empty search box does nothing
| Search | (empty) |
| Replace |
anything
|
| Before |
\emph{hi}
|
| After |
\emph{hi} (unchanged)
|
With nothing to search for, no command is ever matched, so the document comes back exactly as it went in — the replace box is simply never used.
3.1.3.10 Selection vs. whole document
If you select some text before running the search/replace, only that selection is scanned and only that part of the document is changed — useful for restricting a rename to one paragraph or section. If nothing is selected, the whole document is scanned and updated.
Quick recap
- Search box empty → nothing happens.
- Search box has a command name only → matches every occurrence of that command, whatever its arguments contain.
- Search box has a command name with
{...}/[...]→ matches only occurrences whose argument is exactly that text (case-sensitive; empty braces mean "empty", not "any value"). - Replace box empty → the command is removed, its mandatory argument’s text is kept.
- Replace box has content → the matched command is fully replaced by what you typed, verbatim. Any text you want to preserve from the original must be retyped into the replace box yourself.
3.2.2 The editor
The editor is Ace .
It has a full undo/redo system.
It has an excellent syntax coloring for LaTeX code. We use the Cobalt theme.
You can navigate using the arrow keys.
It is quite helpful with delimiters. For the parentheses, curly braces and bracket delimiters, it will create an open/close pair when typing the opening character. It will enclose the selection (if present) with the chosen delimiter pair. Clicking near an opening delimiter will reveal the scope of it.
It also has a auto-complete feature.
A full list of Ace’s default shorcuts in available in the Documents Live online help .
4 Render
Chosing the Render menu item of the Edit dropdown menu will render the Web version of the current code that is in the editor. This gives you an instant preview of what your code will produce.
Render does not alter your data in any way. It just generates HTML code from the code in the editor and renders it in the top pane of the Inline Editor. Most of the Documents Live functionalities are available in the preview, including reference inclusion, etc....
5 Save and restore
When you are in edit mode, there are two ways to save your work. The first one consists in saving from the Inline Editor itself.
The second one is accessed by selecting the Backup... item from the Edit menu.
5.1 Saving from the Inline Editor
When you are in the Inline Editor, you can save you work from the Edit dropdown menu of the editor. You have two options
-
Save to modelsave the object that you are editing to the document model. -
Save to model and update HTMLsaves your modifications to the model and exports the result to the HTML code of the document.
Both options perform a local update. This means that only the current object is modified in the model, and the updated HTML code replaces only the previous code for the current object.
This also means that use can use the Inline Editor on very large or complex documents without impacting the editor’s performance.
5.2 The flexibility of the Inline Editor
In theory, if you edit a paragraph, you should only edit paragraph content. The Inline editor is, however, quite flexible. In most cases, if you create more complex code, the render and save functionalities will adapt. In particular, section levels and numbering will be adapted to the containg object.
5.3 Use the backup system
5.3.1 Saving
When using the Backup... menu item, you will be prompted for a description of the work that was done between the previous backup and now.
After hitting the Save button, a number of tasks will be executed:
- the model will be exported to LaTeX code
- the body of the code will be save as a backup file on the server
- create a backup in the database of the model in its current state, together with the description and backup timestamp
- insert the computed body into the LaTeX source code and save it to the database
As a summary, three kinds of backups are performed: the model is saved, the LaTeX code is saved to a file, and the LaTeX code is saved to the database.
Subsequently, if you compile the document into a web page, the latest backup code will be used. Note that an initial backup is performed when the document is created.
5.3.2 Restoring
You can access your backups by using the Manage backups menu item in the Edit menu. After that, you are presented with list of your backups. For each backup, you can
- view the backup LaTeX code (which cannot be modified)
- revert the LaTeX code to the previous version
- revert both the code and the model to the previous version
- delete the backup
Both revert operations restore the LaTeX code. The second one also restores the model, which spare you the work of re-creating the model. This can be useful for large documents for which the import process may be complicated.
Important: the restore operations work globally, by contrast to the restore operation in the Inline Editor, which is limited to the scope of the object being edited.
5.3.3 Versioning
From the right sidebar, drag and drop the "Versioning" block to the element you wish yo inspect. here is a screenshot.
You card read the original version in the editor in the left pane, and edit the current version in the right editor pane.
Or, instead of checking the version, you can directly select a version that you wish to restore.
Not that, by contrast to common versioning tools such as git, the Documents Live versioning system lets you act at the object level, which is totally different from classical versioning sytems when you must review the full length of the code, which can be quite tedious.
6 Create, delete objects
6.1 Create objects
You can create objects simply by drag and drop. In the "Builder" section of the sidebar, drag a object type block to its destination in the document view. When the drag action begins, available targets in the document will have a blue dashed border. Here is a screenshot.
6.2 Delete objects
To delete an object, drag from the right sidebar the "Delete" block to the document object you wish to delete. Here is a screenshot.
6.3 About HTML update
After creating or deleting an object, in general the HTML code is updated accordingly.
There are actually two situations:
- The element was not just below the document in the hierarchy. Then it was the list of elements of the parent object which was updated. Then the HTML code for the parent is generated and it replaces the older code. This is generally safe.
- The element is just below the document in the hierarchy. This happens for paragraphs that appear before the first section. This also happens for top-level sections. In this case, the whole document HTML code should be re-generated. This is avoided because it could result in a large processing time that would impede the Inline Editor experience.
7 Document search and edit inside the model
In edit mode, just above the document title, there is a search bar that works a bit differently from usual search. Instead of looking for text in the web page, it looks for content in the document model.
What is returned is a list of matches, each consisting of two lines
- a breadcrumb that represents the object hierarchy above the match
- an extract of the text where the match was found, with the match highlighted
The model search is useful when looking for data that is not visible in the web page render. Here are some examples of usages
- search for a label: the search result will return where the label was found (and it is probably attached to the object itself)
- search for math content
- If the text is a parameter of a LaTeX command, the search will find it
Clicking on any segment of the breadcrumb will open an inline editor to the corresponding object.
