Dive in to creating your first Quire publication
Before getting started, make sure you have installed Quire and downloaded a Definition: text editor: A text editor is an application used to edit text files containing either plain text or markup for rich text. All computers have basic text editors preinstalled, though we recommend using a free, more fully featured option like Atom or Visual Studio Code.. We recommend reviewing the Quire Basics Tutorial. This beginner’s guide is a step-by-step introduction to the fundamentals of Quire. We also encourage you to check out our Sample Quire Workflow to get a sense of how to approach your publication and the breakdown of responsibilities.
Start a New Project
To create a new project run the
quire new command. You can learn more about various commands in the Quire Commands section of our guide. Open your Definition: command-line shell: The command-line shell is a text-based window into the contents of your computer, and a space where you can run program commands. On Mac computers you’ll most often use a shell called Terminal, on PCs it’s PowerShell or Git BASH. and copy and paste the text below, replacing
project-name with what you would like your project folder to be called. (Don’t use spaces or special characters in your project name, and lowercase is recommended.)
quire new project-name
Quire will download a new starter project into a folder named “my-project” that can be found in your Definition: home directory: A home directory is a file system directory on a multi-user operating system that serves as the repository for a user’s personal files, applications, music, movies, downloads, etc. The directory name usually defaults to the system user’s name. You can find the directory by opening your Finder or File Explorer window and typing Command-Shift-H.. The process may take a minute as Quire installs a new starter project (a sample publication including content, images, and relevant metadata that you can build off of) in the
The project is ready when you see the message: “Theme and dependencies successfully installed.”
- If you are a Mac user and receive an error message when previewing a new project or an existing project, check to see what operating system you are on. If you are on Monterey, follow this link to install Python 2: https://www.python.org/downloads/release/python-2718/. Click the “macOS 64-bit installer” and follow the prompts. Then navigate to
themes/defaultfolder in your new project, delete the
node_modulesfolder, then run
quire installfollowed by
Copy an Existing Project
In addition to starting a Quire project from scratch as described in the previous section, you can also copy and work on a pre-existing Quire project. You would do this if you were collaborating with others on a publication via GitHub or another service.
Copy the Quire project directory into your Definition: home directory: A home directory is a file system directory on a multi-user operating system that serves as the repository for a user’s personal files, applications, music, movies, downloads, etc. The directory name usually defaults to the system user’s name. You can find the directory by opening your Finder or File Explorer window and typing Command-Shift-H. (typically from a thumb drive, Dropbox/Google Drive, or GitHub).
Open your command-line shell and navigate to the project directory using the
cd(change directory) command. For example, if your project directory was called
my-projectand it was in your home directory, you would enter
Still in the command-line shell, type
quire installand press enter to install the theme dependencies for your project. (This is done automatically when running
quire new, but needs to be done manually when working on pre-existing projects.)
- Learn how to take an existing Quire project in GitHub and use it as the basis for a new one in our Use an Existing Quire Project as a Template section. This is especially useful for serial publications such as journals.
Files for Content Creators and Editors
Inside each Quire project, you will find the following directories and files. Content creators and editors will primarily use the
📁 bin 📁 config 📄 config.yml 📁 content <-- Markdown files with publication text. 📁 data <-- YAML files with publication data. 📄 README.md 📁 site 📁 static <-- Images / Style overrides / PDF, EPUB & MOBI 📁 themes files that are output with `quire pdf` etc.
- Projects started with
quire newwill include demo content, images, and data in the
datafolders. This information can be written over, re-used, or deleted altogether as you’d like.
The central part of Quire is the
content directory where almost all of a publication’s textual content will live as individual Definition: Markdown: Markdown is a text formatting standard that defines the use of very simple text character combinations in order to indicate structure and formatting that can easily be transferred to more complicated HTML (web markup). For example, something surrounded in asterisks in Markdown turns into italics in the final publication:
*emphasis* = emphasis. (
.md) files. Every Markdown file is a page of the publication. You can read more about how to structure the publication content in Page Types & Structure section of this guide.
The publication information that doesn’t live in the
content directory as a Markdown file, will live in the
data directory as a Definition: YAML: YAML is a plain-text, human-readable format for writing and storing data. YAML can be used in a standalone file with the file suffix
yml, or inside a Markdown (
.md) file. Read more in the Fundamentals: YAML & Markdown chapter of this guide. (
.yml) file. This information is considered data because it can usually be found in multiple places throughout the publication. Rather than re-entering that information each time it appears, Quire has been designed to simplify this process by storing information that appears in multiple paces as YAML which is then pulled into the Markdown files through the use of identifiers.
Publication metadata including title, subtitle, contributors, copyright information, etc. can be found in the
publication.yml file, which is required in all Quire projects. Read more in Metadata & Configuration). YAML is also stored at the top of each Markdown file. Learn more in the Page Types & Structure section of this guide. A Quire project may additionally include
- Learn how the
contentfiles work together through the use of Definition: shortcodes: A shortcode is a simple snippet of code inserted in a Markdown file that pulls in information from other files in your project. In Quire, shortcodes are used for styling, figure images, citations, bibliographies, and collaborators. Quire suports a range of shortcodes, and custom shortcodes can also be added. in the Page Content section of this guide.
This file includes information on catalogue objects including artist name, artwork year, dimensions, medium, location, link to work, etc. Read more in Collection Catalogues.
This file includes information for figure images and figure groups including captions, credits, and alt text. Read more in Figure Images.
This file includes reference information used to create in-text citations and bibliographies that are designed to meet scholarly needs. Read more in Citations & Bibliographies.
static directory includes anything that will be included in your final publication, but that doesn’t have to first be processed through Quire’s Definition: static site generator: A static site generator is a framework that generates a static website from source files.. By default, this includes a
css directory for directly overriding theme styles (read more in Style Customization); a
downloads directory for the multiple Quire formats (Output Your Project); and an
img directory for all image and other media assets (Figure Images).
README.md file is a code convention, and is a free space for information about the publication. It is not used in the output Quire publication at all. However, if you host your Quire project on Definition: GitHub: GitHub is a code hosting platform for version control and collaboration. For an introductory guide to it, visit: https://guides.github.com/activities/hello-world/#what or other similar
git project management sites, the
README.md file is used for the repository’s front page description. Often it will include notes on development, on what usage is allowed, on how issues will be handled, and if contributions should be considered.
Files for Developers
Inside each Quire project, you will find the following directories and files. Developers will primarily use the
config.yml file and the
📁 bin <-- Scripts 📁 config <-- Secondary/environmental configuration 📄 config.yml <-- Main configuration 📁 content 📁 data 📄 README.md 📁 site <-- The built site output with `quire site` 📁 static 📁 themes <-- Layouts, shortcodes, styles, js
Currently, it only contains a
deploy.sh script file for deploying a Quire project to GitHub pages, which you can learn more about in the Deploy Your Project.
This is a standard, required file for Definition: Hugo: The static site generator that powers Quire: https://gohugo.io/ and also for Quire. In Quire, it is used expressly for configuring how Hugo operates, and for defining a number of key values used in Quire Definition: templates: Themes may include one or more templates. Templates are the variety of layouts a theme has.. Users who have worked on other non-Quire/Hugo projects will note that they typically use the
config.yml file to also store publication metadata. Given the potentially large scope of this metadata in formal digital publications, Quire uses the
publication.yml file inside the
data directory instead. Read more in Metadata & Configuration.
This is an additional configuration directory. While most Quire configuration happens in the [
config.yml] file as explained above, the
config directory gives more specific controls for different output formats and development environments. In most cases, changes won’t need to be made to these files until you are deploying your site. Read more in Output Your Project.
This is where the built pages of the Quire website will live. This folder and its contents are automatically generated with the
quire site command, and should not be edited directly. Read more in Output Your Project.
themes directory contains one or more Definition: themes: Themes define the overall style of your website. It determines the use of colors, layout elements, and text positioning. that define the structure and style of the Quire publication. When using the
quire new command, the theme is
default. Read more in Style Customization.
Create a Publication Outline
It is a good idea to start any project by creating a basic outline of your publication. To get started with your outline, if you haven’t already, you will need to download a Definition: text editor: A text editor is an application used to edit text files containing either plain text or markup for rich text. All computers have basic text editors preinstalled, though we recommend using a free, more fully featured option like Atom or Visual Studio Code.. We recommend Atom or Visual Studio Code, two free and fully featured options. Once the text editor has been installed, open your Quire project in it. You will see the directory contents listed on the left sidebar. The way you organize the Markdown files in the
content directory of your project will define the structure of your publication and how the Table of Contents is organized. (Learn more in the Table of Contents & Sidebar Menu section of this guide.)
Here’s an outline showing the order, organization, and file names for a sample publication:
📄 cover.md 📄 contents.md 📁 part-one 📄 section-overview.md 📄 chapter-01.md 📄 chapter-02.md 📁 part-two 📄 section-overview.md 📄 chapter-03.md
The names of the files will effect the final URLs of your publication. By default, URLs will be the filename, minus the
.md suffix. Files nested in a sub-directory within
content will include that sub-directory in the URL as well.
- To have URLs for your homepage or section landing pages that don’t include the Markdown file name, add
slug: .to the page YAML of that file. Read more in the Page Types & Structure section of this guide.
For the ordering of the pages, in the example above we’ve listed the files and directories as they would appear in the publication’s table of contents. When looking in the actual
content directory on your computer or in your text editor, however, they will almost certainly not appear in the proper publication order. More likely, they’ll appear alphabetically or by date modified, which is also how Quire will order them when building and previewing your publication. You can adjust this by assigning a
weight to each page in its page YAML.
There are some other important rules and tips to keep in mind:
To create a new file, select “New File” in the text editor menu. You can also right click or press control click on a folder and select “New File”.
File names should be lowercase, with no spaces. Always include the .md suffix. If file names contain more than one word, use a hyphen to separate them. Make sure that the file name includes either a
_index.mdfiles. Though common for users with previous static site or web development experience, you should not use
_index.mdfiles in your Quire project. Because of the way Definition: Hugo: The static site generator that powers Quire: https://gohugo.io/ is modeled, these work against the linear ordering of the publication and break the Next and Previous page navigation in Quire.
Prepare Images and Text
Preview and Edit a Project
Quire lets you preview the current version of your site in a web browser, and will update the preview as you edit the files.
To run the preview:
Open your command-line shell and navigate to your Quire project directory using the
cd(change directory) command. For example, if your project directory was called
my-projectand it was in your home directory, you’d enter
Still in the command-line shell, type
quire previewand press enter to start the preview server.
Open a web browser and visit http://localhost:1313 to see the publication. To stop the preview you can either press Control–C or type
quire stopand press enter.
Some tips for previewing your publication outline:
Include YAML on page for it to be viewable in your web browser In order for pages to become active, you must have basic YAML included at the top of the page. Learn more about YAML in Page Types & Structure
Hide pages from the table of contents view. If you want to hide a page from the table of contents include
menu:falsein the YAML.
- In some cases, changes to
.cssfiles may not show up in your preview immediately. You may need to refresh the browser, clear the browser cache, or stop and re-start the
quire previewcommand in these cases.