Dive in to creating your first Quire publication
Before getting started, if you have not done so already, we recommend taking some time to review our beginner’s guide Tutorial: Quire Basics which is step-by-step introduction to the fundamentals of Quire.
Start a New Project
Now that you have taken the tutorial and installed Quire its time to get started on your first publication. To create a new project you will be running the
quire new command. You can learn more about various commands in the Quire Commands chapter 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” in your home directory. 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) into a folder named
my-project in your home directory.
The project is ready when you see the message: “Theme and dependencies successfully installed.”
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 on a team working on a publication together and are sharing the files via GitHub or another service, or if you wanted to use a previous Quire project as a template for a new one.
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 or 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.)
- You can also type
cdand a space in your shell and then drag and drop the Quire directory icon into it. This will copy the full file path.
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.
The central part of Quire is the
content directory where almost all of a publication’s text 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. files. Every Markdown file is a page of the publication. You can read more about how to structure the publication content in Pages.
- New Quire projects started with the
quire newcommand come with some demo content, images, and data as samples to start. These materials can be written over, re-used, or deleted altogether as you’d like.
What content doesn’t live in
content directory as a Markdown file, will live here 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. file. A
publication.yml file is required (read more in Publication Metadata & Configuration), but a Quire project may also include
references.yml (Citations & Bibliographies);
figures.yml (Figures); and
objects.yml (Catalogue Objects).
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 Customizing Styles); 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 Publication 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 Customizing Styles.
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, you will want 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.
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 Pages 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”.
Filenames 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 .md.
Sub-directories can’t have other sub-directories within them. Quire currently supports only one level of nesting.
_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 Markdown & YAML
Use menu:false to hide a page 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.