Style Guide: Blocks & paragraphs - Hederis/docs GitHub Wiki

A block is a standalone chunk of text, like a paragraph. These are the main pieces of text in your book. Most novels don't contain much more than Chapter titles and Plain text paragraphs, but sometimes a book contains extra types of content, like poems, sub sections, letters, and so on, and those paragraphs should be tagged accordingly.

When it comes to your book design, blocks can be designed differently depending both on the name of the block and the wrapper or section it appears within. For example, you can use the "Plain text paragraph" style both as your main chapter text and within your extract wrappers, and apply different designs to each based purely on the container it appears within. This means that you do not need special styles for every type of text paragraph--you can rely on this type of positional design, and use a simpler set of style names.


Plain text paragraph

A simple paragraph of text. This can appear in many locations (for example, as the main text within a chapter, as well as inside an extract wrapper).


Plain text paragraph (cont'd)

Occasionally, a paragraph is split by another block, like a figure, code block, or example. In those cases, the continuation of the paragraph that follows the dividing block should be tagged with this style.


Chapter/Section title

The main title of a book section (i.e., one of the sections listed in the Section breaks part of this documentation, above).


Wrapper title

The title of a wrapper block, for example a sidebar title, note title, etc.


Chapter/Section/Wrapper number

Sometimes sections or wrappers are both numbered and titled. This style should be used for the number of the section.


Chapter/Section/Wrapper subtitle

If a section or wrapper has a subtitle, tag it with this style.


Verse paragraph

A single line of verse, often within a larger poem. Should always be nested inside of a Poetry wrapper (however a single Poetry wrapper can contain many Verse paragraphs). E.g.:

An epigraph with an attribution

Required wrapper: Poetry


Author name

The name of an author of a section of text; for example, if different chapters of the book have different authors who are credited within each chapter; the author of a foreword or afterword; etc.


Dateline

Any generic dateline (for example, a dateline at the beginning of a chapter, or at any point within a chapter). For letter extracts, use the "Letter date" style instead.


Salutation

Occasionally a section will include a salutation, for example, "Dear Reader", which is a perfect place for this style to be used. For letter extracts, use the "Letter salutation" style instead.


Location

A location. For example, if the beginning of a chapter is marked by a date and location, e.g.:

A location line at the start of a chapter

This style might also be used on a titlepage, to tag the location of the publisher.


Signature

It's common for a foreword or afterword to be "signed" by the author (e.g., to end with the author's name). This style should be used in that situation. For letter extracts, use the "Letter signature" style instead.


Code paragraph

A single line of code.

Required wrapper: Code block


Endnote paragraph

A single paragraph within an endnote.

Required wrapper: Endnote


Footnote paragraph

A single paragraph within a footnote.

Required wrapper: Footnote


List item

An item within a list (bulleted, numbered, or simple).

Required wrapper: Bulleted list, Numbered list, or Simple list


List item (cont'd)

Sometimes a list item consists of multiple paragraphs. In those cases, use this style for all paragraphs after the first paragraph of the list item.

Required wrapper: Bulleted list, Numbered list, or Simple list


Image holder

An image. The contents of this block should only be an actual image file, or a path to an image file.

Required wrapper: Figure


Caption

A caption, for example for an image or table


Dialogue paragraph


Speaker name


Quote paragraph

When quoting another work, use the Quote paragraph style for each paragraph in the extract.

Required wrapper: Extract or Epigraph, depending on the context


Attribution

The source (speaker, book title, etc.) of a quote or extract. For example:

An epigraph with an attribution


Attribution (cont'd)

If an attribution requires multiple lines, use this style for all lines after the first. See immediately above for an example.


Line space

An intentional blank line, often used to give the illusion of the passage of time within a narrative, or to separate a thought.


Ornamental space

An intentional break used to give the illusion of the passage of time within a narrative, or to separate a thought, marked by a decorative ornament.


Titlepage contributor

Required section: Title page, Halftitle page


Titlepage imprint

Required section: Title page, Halftitle page


Titlepage publisher name

Required section: Title page, Halftitle page


Titlepage dateline

Required section: Title page, Halftitle page


Letter heading, Letter address, Letter date, Letter salutation, Letter body, Letter closing, Letter signature, Letter postscript

The parts of a letter should always appear inside of a Letter wrapper, like the following:

A letter

Required wrapper: Letter


Generic subheading

Occasionally, a section or wrapper might require a heading interspersed within the text, without requiring the text to be split into sub-sections. In those rare cases, this style should be used for the subheading. A common use of this would be within a sidebar that uses subheadings, e.g.:

A sidebar with a generic subheading a few paragraphs in


Definition term

A term to be defined. This should always occur inside a Definition list wrapper (but a single Definition list wrapper may contain many Definition terms and definitions).


Definition definition

The definition of a term. This should always follow a Definition term paragraph and should always occur inside a Definition list wrapper (but a single Definition list wrapper may contain many Definition terms and definitions).


Definition definition (cont'd)

If a definition consists of more than one paragraph, use this style for all paragraphs after the first paragraph. This should always occur inside a Definition list wrapper (but a single Definition list wrapper may contain many Definition terms and definitions).


Box type

It's common in nonfiction and reference texts to include a number of different, recurring types of sidebars. In addition to a title, these sidebars are often labeled with the type of sidebar that they are, and this style should be used for that purpose.


Mark for Deletion

A paragraph that should be deleted.