Quire Website & Documentation Style Guide

Language & Grammar

File types in text are capitalized (“Markdown”) or all caps when they are an acronym (“PDF”, “YAML”, “EPUB”).
YAML has “attributes” and “values.”
Headings should be short and active. Use “Structure Your Publication” rather than “Publication Structure” or "Structuring Your Publication"
When writing about Quire, refer to it as a "tool" and not software, platform, or framework.
Use "multiformat" and not multi-format. Multiformat specifically refers to online, print, and E-book.
When used as an adjective before a noun, use "open-source" (with a hyphen). For example, in the sentence "I enjoy using open-source software" the word "open-source" is describing a type of software. When used as a noun, use "open source" (with no hyphen). Avoid using “open-source” as a verb.
While the term "directory" is most widely used throughout the documentation, it can be used interchangeably with "folder" when appropriate.
When referencing commands on a Mac use hyphens. For example "Command-F" will bring up the search function.

Keep in mind that both Level 2 and 3 headings (## and ### in Markdown) are used to create navigation links at the top of every page.
When referring to other sections of the documentation use italics and hyperlink that section.

When describing images in the publication showcase, use the publication titles as the alt-text.

When editing an existing heading, always do a global content search for any links that reference it. Many links are based on heading wording, so when the wording changes, the links break.

The homepage slider publications should appear in alphabetical order. Once a month replace homepage slider images with either the most recent or most impressive catalogues. Don’t include minor catalogues or catalogues that stray from the scholarly. Also try to keep homepage catalogue selection as diverse as possible (i.e., only one exhibition catalogue, only one online exhibition, only one journal, etc.)
Publication cover images should be taken as screenshots in full-screen mode with the toolbar removed. Resize the image in photoshop to 900 x 563 pixels.
Save images as JPGs.
Save illustrations with transparency as PNG.

Code styling can be added with the Markdown standard of wrapping it with a single tick ` for inline formatting, or three ticks ``` for a standalone block of code. Within running text, the following types should always be formatted as code:
- Specific file and directory names
- CLI commands
- YAML attributes and values

Callout boxes can be created to highlight small portions of text by wrapping it with the {{< q-class "box tip" >}} shortcode. Adding "box warning" or "box tip" and using a markdown-formatted list will add a large warning or tip icon to the box.

{{< q-class "box tip" >}}

- Here’s a great tip ...

{{ /q-class }}

<div class="box tip">

- Here's a great tip with an image.

![*Descriptive Text*](/img/screenshots/*image file name*)

</div>