The Importance of “Good Markup”

Ebooks are essentially self-contained websites. As such, they are created from text wrapped in HTML and CSS styling.

To have good-looking book outputs from Pressbooks (and indeed, for any kind of ebook, whether or not you use Pressbooks), it’s critical to have good “markup.” This chapter will answer the following questions:

  • What is “markup”?
  • Why is it important to have “good markup”?
  • OK, so what is “good” markup?
  • What is “bad” markup?
  • How do I get “good” markup?

What Is “Markup”?

Pressbooks uses HTML (content and structure) and CSS (styling) to create ebooks, PDFs and web versions. You don’t need to know HTML or CSS to use Pressbooks, but understanding a little bit about how they work will help make sure your books look good when you export from Pressbooks.

NOTE: the VISUAL editor in Pressbooks allows you to style things without ever knowing about markup, or seeing code or tags. But if you’ve got formatting problems with your output, 90% of the time it will be caused by “bad” underlying markup.

Why is Good Markup Important?

The thing about ebooks is that you never quite know what kind of setup your book is going to be read on. Different ebook reading software might display things differently, and the people reading often have control over things like spacing, margins etc. What this means is: you cannot control exactly how your book is going to look. But! If you have good markup, chances are that the output will look like it’s supposed to. This is especially important in Pressbooks, where our outputs include: PDF (for print), EPUB, MOBI and web … so ALL of these formats have to look good.

Basic Markup

Markup is the HTML part … it’s the text of your book, plus tags in the background.

For instance, here is a brief passage of text with some formatting:

A long, long time ago, in a galaxy far, far away, there lived a fine young man unaware of various things about his past, including: the Force, what his father was up to, how to use a lightsaber. All that, however, was about to change. Three things were about to happen: he would discover the Force, he would learn how to use a lightsaber, and he would meet his father.

This is what you might write into the VISUAL editor of Pressbooks. But if you look at the TEXT editor, you’ll see that the way that italic and bold is achieved is through “markup”, or HTML. So the markup of that text looks like:

A long, <em>long</em> time ago, in a galaxy far, far away, there lived a fine young man <strong>unaware</strong> of various things about his past, including: the Force, what his father was up to, how to use a lightsaber. All that, however, was about to change. Three things were about to happen: he would discover the Force, he would learn how to use a lightsaber, and he would meet his father.

The <em>tag</em> specifies that a text should be italicized. The <strong>tag</strong> specifies that it should be bold.

A reader reading an ebook, or a print book, or a web page won’t see those tags. They are instead used to tell the ebook software, or browser, how those words should look.

So, what is good markup?

OK, So What Is “Good” Mark-up?

Doesn’t Pressbooks give me “good” markup without me worrying about it? Yes, although sometimes bad markup can be introduced by applying formatting incorrectly or importing documents with hidden markup from word processing software. How do I get “good” mark-up? What is the basic markup used in Pressbooks (and indeed all books)?

The example above is pretty simple, but there are other kinds of content that you might want to style in certain ways in a book. In addition to italics and bolds, there are a handful tags you should know about:

tag name used for  tags
strong used to make text bold <strong>  or <b>
emphasis used to make text italic <em> or <i>
blockquote used to quote a long text, can be used for instance for a letter, a poem etc <blockquote>
unordered list used to create a list with bullets <ul><li>item 1</li><li>item 2</li></ul>
ordered list used to create a numbered list  <ol>
<li>item 1</li>
<li>item 2</li>
</ol>
headings used to make headings in your document <h1>, <h2>, <h3> ... </h6>

This set of tags is all we’ll cover in this chapter, but you can do a lot more with tags in ebooks and Pressbooks.

Here is that same text from above with more tags used, resulting more formatting:

The Background

A long, long time ago, in a galaxy far, far away, there lived a fine young man unaware of various things about his past, including:

  • the Force
  • what his father was up to
  • how to use a lightsaber.

All that, however, was about to change. Three things were about to happen:

  1. he would discover the Force
  2. he would learn how to use a lightsaber, and
  3. he would meet his father.

The Update

Long after this fellow lived, a famous movie was made about his life. The movie was shot in Tunisia.

Here is that text with markup:

<h3>The Background</h3>
A long, <em>long</em> time ago, in a galaxy far, far away, there lived a fine young man <strong>unaware</strong> of various things about his past, including:
<ul>
<li>the Force</li>
<li>what his father was up to</li>
<li>how to use a lightsaber.</li>
</ul>
All that, however, was about to change. 

Three things were about to happen:

<ol>
<li>he would discover the Force</li>
<li>he would learn how to use a lightsaber, and</li>
<li>he would meet his father.</li>
</ol>


<h3>The Update</h3>
Long after this fellow lived, a famous movie was made about his life. The movie was shot in Tunisia.

If your markup is “bad,” chances are your book isn’t going to look good.

So what is bad markup ? We’ve got a chapter on just that: Bad Markup = Bad Formatting