Skip to content

Convert XML to HTML

This tutorial shows how to turn an XML document into a web page you can open in any browser. It takes about ten minutes. You do not need to know XSLT or any programming language: the rules for how each element should look are written in a document of their own, called an ODD.

The examples use TEI. opm works the same way for DocBook and JATS, and ships ready-made rules for all three; for any other XML format, you write the rules yourself. Where the steps differ, this tutorial says so.

By the end you will have:

  1. a small project folder with your XML file in it
  2. an HTML version of that file
  3. your first change to the way the output looks

Before you start

You need opm installed on your computer. If you have not done this yet, follow the installation instructions. To check that it worked, open a terminal and type:

opm --help

You should see a list of commands.

1. Create a project

A project is simply a folder that holds your XML files, the ODD with your rendering rules, and a configuration file. Create a new one with:

opm init my-edition --vocabulary tei
cd my-edition

--vocabulary names the XML format of your documents. For DocBook or JATS, write --vocabulary docbook or --vocabulary jats instead.

opm creates the folder my-edition and fills it with everything you need to get started. The most important parts are:

Path What it is for
data/ your XML documents. There is already a small sample.xml in it.
odd/custom.odd your rendering rules. It starts out empty and inherits sensible defaults for all common elements of the format you chose.
templates/ the page layout and stylesheet wrapped around your text
opm.toml the project settings

2. Convert the sample document

Let us first try the sample document that came with the project:

opm transform data/sample.xml --preview

--preview opens the result in your web browser. The first run takes a few seconds longer, because opm first reads the ODD and prepares it. Later runs reuse that work and are much faster.

To save the result as a file instead, name the output with -o:

opm transform data/sample.xml -o sample.html

3. Convert your own document

Now copy one of your own XML files into the data folder and run the same command on it:

opm transform data/letter.xml --preview

Most documents will display reasonably well right away, since the default rules cover many of the common elements: divisions, headings, paragraphs, notes, lists, tables, figures and, for TEI, also verse, drama, and many more.

4. Change how something looks

Suppose you want person names to appear in italics and in dark red. Open odd/custom.odd in a text editor. Inside the schemaSpec element, add an elementSpec for persName:

<schemaSpec ident="custom" start="TEI teiCorpus" source="teipublisher.odd">
    <elementSpec ident="persName" mode="change">
        <model behaviour="inline">
            <outputRendition>font-style: italic; color: #8b0000;</outputRendition>
        </model>
    </elementSpec>
</schemaSpec>

Graphical Editor

If you don't feel comfortable with editing the XML, there's also a graphical editor as a plugin for Visual Studio Code and derived editors like Cursor or Antigravity, called ODDity.

Let us look at what this says:

  • elementSpec ident="persName" selects the element we want to change. In a DocBook or JATS project, you would pick one of their elements instead, for example emphasis or italic. mode="change" means we only replace its rendering rules and keep everything else from the default ODD.
  • model behaviour="inline" says that a person name should run along with the surrounding text, rather than start a new block like a paragraph would.
  • outputRendition holds the styling, written in CSS.

Save the file and run the transform command again. The names are now shown in italic red. opm notices that the ODD has changed and prepares it anew.

This is the general pattern for all changes: find the element, decide on a behaviour (paragraph, heading, inline, note, link, …), and add styling where needed. The TEI Publisher documentation explains the available behaviours and includes a short tutorial on writing processing models.

One set of rules for all formats

The same ODD is also used when you create a PDF, an EPUB or Word file, or a website. Your change to persName applies to all of them.

Why not XSLT?

XSLT stylesheets, such as the TEI Stylesheets, are a well-established way of transforming XML. The approach taken by opm differs in where the rules live. Instead of a program, you write a document that describes the desired output, following the TEI Processing Model. It is part of the TEI Guidelines, but works for any XML format. This has some practical advantages:

  • the rules are easier to read and change for people who know their XML format but are not programmers
  • one set of rules produces HTML, PDF, EPUB, Word and Markdown
  • ODD expands to One Document Does it all for a reason: it can host schema definitions, encoding guidelines, documentation and the processing document — all in the same TEI file
  • the same ODD also works in TEI Publisher, so you can move between a static setup and a full web application without starting over

Next steps