Formatting your Pub

Kyle Denlinger

Structuring your Pub with Headings

A table of contents formed by the use of headings — Contents of a pub in *Fermentology*

When you write for an external audience, it’s helpful to give your pub some structure that permits readers to “skim” your work. This is especially true for longer works. The best way to do this in PubPub is by using headings.

Headings do more than just make text larger and bolder: they add code to your pub that make it easier for computers to understand the structure of your document. Notice the “contents” section of any pub that uses headings and you’ll see what I mean.

Heading levels in the text editor — Heading levels

Headings also make it so folks with who use specialized screen reader software can engage with your pubs more efficiently.

To create a heading, just highlight some text and select “H1” or “H2” in the formatting bar that appears, or select a heading level from the text formatting bar at the top of the pub. Keep in mind that you should “nest” your headings appropriately: the first heading in any pub should be H1, and any sub-headings under that H1 should be H2, then H3, etc. In most cases, you’ll need only H1 and H2.

Here’s a good example of appropriately nested headings. Note that it’s possible to have multiple sub-headings within any other heading, as long as you don’t skip a heading level:

A list of formatted text headings nested in appropriate order. — Appropriately nested headings

Here’s what not to do. Notice that the following list of headings skips Heading 2 and goes straight to Heading 3.

A list of formatted text headings not nested in appropriate order. — Inappropriately nested headings. Note that this list skips from H1 to H3, leaving out H2.

Other Special Formatting

Lists

Lists, either numbered or unnumbered (bulleted) are helpful in some situations. PubPub offers both kinds, which you can find in the formatting toolbar of the pub editor. Examples:

Thing A
Thing B
Thing C

This thing
That thing
The other thing

Blockquotes

Sometimes it’s useful to call attention to a line of text that stands alone, such as a quote or a prominent claim or statistic. You can use the blockquote tool in the formatting toolbar to apply blockquote styling to any text you select.

Why are those quick, brown foxes always jumping over lazy dogs?

See how it’s set apart? Kinda cool.

Tables

Tables are useful for organizing data in your pub. Try not to use them for laying out elements or trying to hack image and text alignment. Check it out:

Fruit	Vegetable
Apple	Carrot
Orange	Broccoli
Banana	Cauliflower
Mango	Onion
Pineapple	Potato

Sweet table, eh?