Style Guide: Wrappers - Hederis/docs GitHub Wiki
NOTE: We are currently in an invite-only alpha testing phase. If you'd like to participate, please contact [email protected].
Sometimes a group of paragraphs is meant to stand out from the main narrative text, for example as a note, sidebar, or a letter. These groups of paragraphs need to be inside of a wrapper, which conveys extra information about the type of information contained by this group of paragraphs, and denotes that these paragraphs belong together.
Extract
An extract is a generic container for any content extracted from another source, either real or imaginary. For example, a passage from another (real) book, an article snippet from an imaginary newspaper, a selection of text messages between book characters, a selection from a play, etc.
Typically contains: Plain text paragraph, Verse paragraph, Quote paragraph, Dialogue paragraph, Speaker name, Generic subheading (e.g., for a newspaper headline)
Figure
Often images are accompanied by extra information that belongs with the image, like a caption or photo credit. These things should be grouped with the image inside a figure wrapper.
Typically contains: Image holder, Caption, Attribution
Bulleted List
An unordered list of items (regardless of the marker type that you want to appear in the design).
Typically contains: List item, List item (cont'd)
Numbered List
An ordered list of items (regardless of the numbering style that you want to appear in the design).
Typically contains: List item, List item (cont'd)
Simple List
A short list of items similar to an unordered list, but usually represented in design without any marker at all.
Typically contains: List item
Definition List
A list of key terms and their definitions.
Typically contains: Definition term, Definition definition, Definition definition (cont'd)
Epigraph
An introductory quotation, typically appearing at the beginning of a section.
Typically contains: Quote paragraph, Verse paragraph, Attribution, Attribution (cont'd)
Letter
A letter.
Typically contains: Letter address, Letter salutation, Letter date, Letter signature, Letter heading, Letter body, Letter closing, Letter postscript
Sub-section
Any nested section within a main book section. Nonfiction books are often divided into many levels sub-sections, and this wrapper can be used in that fashion. For example:
Typically contains: Any block or wrapper type EXCEPT Chapter title. CAN NOT contain Section breaks.
Sidebar
Information that is supplemental to the topic being discussed, but not part of the main narrative.
Typically contains: Wrapper title, Plain text paragraph, most block types
Poetry
Any poem that is not an extract. For example, in a book of poetry, each poem would be nested inside a Poetry wrapper.
Typically contains: Verse paragraph
Note
An alert to the reader (for example, the note at the beginning of this page). Can be informational or cautionary.
Typically contains: Wrapper title, Plain text paragraph
Footnote
A group of blocks or wrappers that make up a single footnote. For example, if your footnote contains multiple paragraphs, or a poem, or an extract, etc. you should wrap it in a Footnote wrapper.
Typically contains: Footnote paragraph, Poetry wrapper, Verse paragraph, Extract wrapper, etc.
Endnote
A group of blocks or wrappers that make up a single endnote. For example, if your endnote contains multiple paragraphs, or a poem, or an extract, etc. you should wrap it in a Footnote wrapper.
Typically contains: Endnote paragraph, Poetry wrapper, Verse paragraph, Extract wrapper, etc.
Code Block
A block of computer code.
Typically contains: Code paragraph
Example
An instructional example, often used in nonfiction or education texts to illustrate how a certain exercise should look. Examples can contain a variety of content, like code samples, essays, legal briefs, etc.
Typically contains: Wrapper title, Caption, Code paragraph, Plain text paragraph, most block types.
Table
Tables sometimes need to be grouped with a caption or other supplemental information. Like a figure wrapper, all of these pieces of information should be nested inside the table wrapper.
Typically contains: Caption, table