# HTMLBook: an XHTML5 standard for writing books in HTML
> HTMLBook is an open standard for authoring and producing both print and digital books from one source document. It is a subset of XHTML5 with no extra elements or attributes, tailored to the structure of a book, defined by an XML schema, with XSLT transforms, stylesheets, and a command line validation workflow.
**oreillymedia/HTMLBook** — Let's write books in HTML!
- Repository: https://github.com/oreillymedia/HTMLBook
- Website: http://oreillymedia.github.io/HTMLBook
- Stars: 660 · Forks: 101
- Language: XSLT
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/oreillymedia-htmlbook
## One document, several books
The pitch is in the tagline: write books in HTML. More precisely, HTMLBook is an open, XHTML5 based standard for the authoring and production of both print and digital books.
The single source idea is the whole point, and it is worth being clear about what it replaces. The traditional technical publishing pipeline has a manuscript that is typeset for one medium, and a production step that produces the others, often through conversions that lose the things the other medium could not express. A single source document with separate transformations in each direction does not have that problem, and it is the reason the project exists rather than being one more XML dialect.
The three premises in the readme are what the design rests on.
The first is that books are timeless. The basic book structure has persisted for hundreds of years and will continue to persist for the lifetime of the reader, in digital or printed form. That is a claim about the durability of a document model, and it is the reason the standard is built around a structure rather than around a workflow.
The second is that HTML is the markup language of the world for the foreseeable future. The third is that single source document processing will remain valuable for the foreseeable future.
Put together, the three say that the format should be the one everybody already uses, the structure should be the one that does not change, and the workflow should be the one that lets the same file feed several outputs. A standard that is not a new language is easier to adopt, and that is the strategy here.
## A subset, deliberately
Five properties describe the standard, and the first two are the ones that define its scope.
HTMLBook is a subset of XHTML5. All HTMLBook is XHTML5, but not all XHTML5 is HTMLBook. And the standard contains no additional elements or attributes outside of the XHTML5 specification.
That second point is the strong one. A standard that invented its own vocabulary would be a new dialect to learn, and the argument for HTMLBook is precisely that there is nothing new to learn. What a publisher gets is the existing HTML vocabulary, organised for books.
The third property is that the standard is semantically tailored to the structure of a book, including the more complex content used in technical and reference documents. So the subset is not a simplified HTML. It is HTML with the emphasis moved towards long form: sections that nest properly, figures and examples that carry captions, notes, and the apparatus that a reference work needs.
The fourth property is that the standard is defined with and can be validated against an XML schema, and the fifth is that the stylesheets are written in CSS.
Those two together are what make the project usable in a real production environment. A schema means a document can be checked mechanically rather than by reading, and CSS means the visual layer is the modern one, with a print stylesheet as a media type rather than as a separate technology.
The result is a standard with no novel syntax, which is why the tooling around it is a schema, a set of transformations, and a set of stylesheets rather than a parser and a runtime.
## The schema, and the two ways to validate against it
The main schema file is the one named htmlbook.xsd, and it imports the W3C schemas for MathML and SVG so that those can be validated as part of the same document.
That import is the detail that shows the standard is aimed at technical books rather than at novels. A technical book with mathematics and with figures needs both vocabularies to be checked, and a schema that pulls in the MathML and SVG schemas means an author gets an error for a bad equation or a malformed drawing, not just for a bad heading.
Validation on the command line is a single xmllint invocation with the schema flag and no output flag, which means the file is checked and nothing is printed unless something is wrong.
```bash
$ xmllint --noout --schema htmlbook.xsd .html
```
The alternative is to do it in a graphical XML editor, and that path is configured by adding a schema location declaration to the root element of the document.
```xml
```
Two things are happening there. The instance schema location attribute points an editor at the schema file so that it can validate as you type, and the default namespace declaration puts the document in the XHTML namespace, which is what makes the file an XHTML5 document rather than a generic XML one.
So a publisher has two workflows for the same check, one for a continuous integration job and one for an author at a desk, and both read the same schema.
## The repository, and what the samples tell you
The top level of the repository maps onto the four parts of the project.
There is a schema directory, which is where the validation story lives, a specification document at the root with the working draft, and a stylesheets directory for the CSS. The stylesheets are the print and screen presentation layer, and their presence is the reason the standard says the stylesheets are written in CSS rather than in a page description language.
Then there is the directory that explains the recorded primary language of the repository, the XSLT one. Transformations are how a single source becomes several outputs, and XSLT is the classic way to do that with XML input, which is what an XHTML5 document is. The presence of a transformation layer is what turns the single source premise into something that produces a printed page and not only a web page.
The samples directory holds the evidence for the claims. There is a sample of the standard applied to a full text, the story of Alice in Wonderland, which is the obvious choice for a public domain work with a rich structure of chapters, dialogue, and illustration, and it is a hard test for any book standard because it has front matter, a contents list, and a large number of short sections. There is a second sample that is a small document showing the skeleton of a book, and there are directories for the images and for the markdown sources that the samples are authored in.
That last directory is worth noticing. The samples are written in markdown, which is how most technical books are actually written today, and the presence of a markdown source alongside the HTML samples suggests the authoring path is markdown in, HTMLBook out, with the conversion as part of the pipeline rather than as something an author does by hand.
## Working draft status, and the tooling still to come
The notes section is short and sets expectations honestly.
The specification is currently in working draft status and will continue to be developed and revised for the foreseeable future. Bugs and feature requests go through the issue tracker of the repository.
That matters for an adopter, and it is worth being clear about it. A working draft means the schema may change, which means a validation rule you rely on today may be different in a year. For a publisher with a long production cycle that is a real consideration, and the mitigation is the obvious one: pin the schema you build against.
The second note is about what is coming. In the coming months the project intends to add tools for authoring and producing books with HTMLBook, and the two named are CSS stylesheets, which are already partly there, and scripts for generating EPUB and Mobi, which are the two ebook formats a technical publisher still has to produce.
Those two formats explain the rest of the design. A digital book in the reading software most people use is an EPUB, and an older format for the older devices is a Mobi, and neither is a page layout. They are both produced from a document, and producing them is a transformation problem, which is exactly what the XSLT directory in the repository is for.
The final note is an invitation to contribute by pull request, and the repository has a code owners file and a style guide, so it is a project with a process rather than a proposal.
The overall picture is a standard that is deliberately unambitious in what it adds, careful about what it reuses, and honest about its maturity. For a technical publisher with a large catalogue and a pipeline to rebuild, that combination is more useful than a new markup language would have been.
## Conclusion
HTMLBook fits a technical publisher or an author who wants one document to produce a printed page, an ebook, and a web version without maintaining three sources. It does not fit a team that has already committed to a different authoring chain, and it does not fit a project that needs the richer markup of the web, because the standard is a subset on purpose. Verify first that the content you intend to write fits the subset, since the standard adds no elements of its own, that the transformations in the repository cover the output formats you need, and that you are comfortable with a specification that is still a working draft and will keep changing.
## FAQ
### What is HTMLBook?
It is an open, XHTML5 based standard for the authoring and production of both print and digital books, with the aim of producing both from one source document. It is a subset of XHTML5 with no elements or attributes of its own, semantically tailored to the structure of a book.
### What are the premises behind HTMLBook?
Three. Books are timeless, in that the basic book structure has persisted for hundreds of years and is not going away. HTML is the markup language of the world for the foreseeable future. And single source document processing will remain valuable for the foreseeable future.
### How do I validate an HTMLBook document?
With xmllint on the command line, passing the schema file with the schema flag and the no output flag, so nothing is printed unless something is wrong. Alternatively, in a graphical XML editor, by adding a schema location declaration to the root element of the document pointing at the schema file.
### What does the HTMLBook schema cover?
The main schema file is htmlbook.xsd, and it imports the W3C schemas for MathML and SVG, so that the mathematics and the drawings in a technical book are validated as part of the same document rather than being left unchecked.
### Is the HTMLBook specification finished?
No. It is in working draft status and will continue to be developed and revised for the foreseeable future, and the project asks for bugs and feature requests through the issue tracker. Additional authoring and production tools, including stylesheets and scripts for generating EPUB and Mobi, are planned.
## Sources
- [Issues](https://github.com/oreillymedia/HTMLBook/issues)
- [License: MIT](https://github.com/oreillymedia/HTMLBook/blob/master/LICENSE)
- [oreillymedia/HTMLBook on GitHub](https://github.com/oreillymedia/HTMLBook)
- [Project website](http://oreillymedia.github.io/HTMLBook)
- [README](https://github.com/oreillymedia/HTMLBook/blob/master/README.md)
---
Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/oreillymedia-htmlbook