Use this guide to learn more, and use the sample download to explore and play with the structure.
Note: this guide refers to the current version: (2.0.2)
This guide should get you up and running. You can optionally consider getting a one-time advanced guide for more advanced tips, usage ideas, and hidden features not mentioned here.
Every book is a single Markdown file (e.g., the.lion.queen.md) with frontmatter which describes attributes (like title or series) and chapters which have their own attributes (e.g., name or pov) and actual content.
a global.md file that provides overarching directions to the script (which files to pick, how to process and so on). Some instructions in the global.md can be overridden in the individual manuscript frontmatter.
The script picks the global.md, applies the global rules and local (file-level) rules as it processes each manuscript, and then produces the output using naming conventions provided in the manuscript frontmatter or global.
Variable names in the settings files are case sensitive!
That’s it.
The download folder will look something like this:
bin/ (required: binaries and processing files - don't touch the contents!)
output/ (optional: where generated outputs can go, but you can change destination)
templates/ (optional: some sample templates to get started)
resources/ (optional:some files for the sample)
global.md (required: overarching settings)
pq.cjs (required: the script - don't try to make modifications to this!)Make sure to follow the installation guide to get started.
We will now walk through the setting options through (1) the global settings file and (2) the structure of an individual manuscript.
Before we get into the settings and structuring the manuscript, here’s what I recommend.
1b. Run node pq.cjs --h to see the the options.
Now open the sample.md and just go through it to get a sense of the structure. Maybe even change a few values and add things and reproduce (make sure to keep a copy of the file just in case)
Open the global.md file and take a look. Maybe modify a few values and see what happens.
Now make a copy of sample.md - call it sample2.md
Under the groups: sample group, add a new row, - sample2.md
Make some changes to sample2.md - perhaps the title, modify some text etc. Make sure to modify the outputName to sample2.
Run the command lines node pq.cjs -g sample -t batch and you will see sample.docx and sample2.docx. Now run node pq.cjs -g sample -t boxset and you’ll see only sample2.docx but the file will have both sample and sample2.
Now that you have the basics, read the rest of the guide.
Playing with the file/values is the best way to learn. And in parallel, scroll down and read the rest of the guide to understand some of the nuances and how to use the system.
The script reads the global.md when invoked, so let’s understand what’s in it:
---
nowFormat: DD-MMM-YYYY
groups:
sample:
- ./myMasterPiece.md
darkCorners:
- ../Books/dark.corners.1.md
- ../Books/dark.corners.2.md
- ../Books/dark.corners.3.md
buildControls:
resourcePath: ./resources
wordsPerPage: 250
outputFolder: ./output
metricsFile: ./output/metrics.txt
replacers:
myWeb : https://jaypenner.com
sig: "[-John Doe](https://nasa.gov)"
facebook: https://facebook.com/jaypennerbooks
---
global settings file.
nowFormat: dictate a format for how date/time is represented when {{now}} special replacer is used (for formatting options, see here)
groups: this is an essential setting. Each group has a label: and below that, paths to one or more manuscripts, with their paths relative or absolute to the pq.cjs script. The beauty of this arrangement is that you can create groups that represent any combination of manuscripts you want. A boxset, individual, other combinations etc. When you run the script with -g <name>, it goes through each file in that group and either executes it one-by-one (batch) or combines them all to create a boxset.
pq.cjs -g darkCorners -t batch will produce a docx for every file in the group, whereas,
pq.cjs -g darkCorners -t boxset will produce a single docx that combines every file in the group.
Make sure to follow the writing convention correctly. groups: followed by indented group name: and then intented - file name. The intendation represents the hierarchy of group section -> 1 or more groups -> 1 or more files.
The advanced guide covers some fine-grained control over boxsets and gives you some tips on how to create effective sets.
buildControls: gives the script additional instructions as it produces the output.
resourcePath: the doc producer will look here for any images if you’ve provided no path in the Markdown; if you prefer to put all your images in this folder (like covers, maps, illustrations), then it will look here, and you don’t have to specify a path in every single mention (e.g., you can do wordsPerPage: the --stats option will use this variable to calculate the number of ~pages in your book, based on words; if you don’t have this line, the script uses 250 as default.metricsFile: provide a location for a text file and the script will output basic metrics about your book into this file (book stats like title, words, pages, chapters, povs, chapter names and lengths).replacers: let you replace a label: with the value anywhere in any of your manuscripts, so long as the label is typed with {{label}}. You can add as many as you want! There may be some circumstances where it may not work if there are odd combinations of special characters, but for 99% of the cases it works great. They are fantastic to abstract some very common text into simple labels and apply them to your entire library, how awesome is that! The advanced guide goes into some nice tips and ideas on how to use replacers.
There is a premium feature to include external markdown or text anywhere within your manuscripts. This is a huge time saver (think of how to have common intros, thank-you, backlist entries - all maintained centrally and updated once and you can regenerate your entire backlist in seconds!).
The structure of any manuscript follows these basic rules:
header frontmatter
---
================
chapter frontmatter
---
content
The file opens with a header frontmatter (which we will cover in a bit). The frontmatter is separated from actual chapter content by using --- on a new line.
And then, each chapter is separated from the other by ====== (at least 5 double-dashes, though having 20-30 so that the separation is clear is recommended).
That’s it.
Here’s how a manuscript with two chapters would look. We will walk through what the different parts mean. Once done, open the sample.md from the download folder and go through it. The sample represents a real extract from one of my books.
exclude:
type: header
name: heading section
bookInfo:
title: Regent
version: 1.0
series: The Last Pharaoh
author: Jay Penner
pubDate: 15-Aug-2020
coverImage: ./regent.cover.jpg
replacers:
d1 : "> "
buildControls:
outputName: Sample
includeCoverImage: true
wordTemplate: ./templates/novel.docx
ePubStyleSheet: ./templates/novel.css
formats:
- docx
---
synopsis: header section
============================================================
name: intro
pov: Cleopatra
---
The cool basalt floor hid the cauldron of emotions.
============================================================
name: young-royals
pov: Pothinus
---
# {{#n}}
### 22 years ago
Pothinus took the royals on a trip.
This is the opening section of any manuscript and provides instructions to the script on how to process the file. In the descriptions below, a * implies it is required in the header, and if omitted, in some cases, the value is picked up from the global.md (don’t actually put a star in the real file!)
*exclude - don’t include the content of this section in your output
*type: header - needed for internal purposes
name - a name for the section, optional
*bookInfo: - section with info about the book
-*title, *series, *author - basic info on the book
-*version - add a version, this is used if you want to emit versions in your book (useful)
-coverImage - path to the cover, used in conjunction with includeCoverImage build (see below)
replacers - optional list of key, value replacements (covered in the global section above)
*buildControls - controls the production of outputs
-*outputName: - name of produced doc, e.g., Regent (don’t put extensions like .docx)
-outputFolder: - where to place the output (if different from global)
-includeVersionNumber: - appends the version number to the produced doc (e.g.regent_3.1.2.docx)
-includeCoverImage: - adds the cover image to the first page of the book
-*wordTemplate: - the template to use for the MS word production; this is an important option with lot of power and you can learn more on how to use it in the book along with access to a few nice additional templates. The sample comes with a default
-*ePubStyleSheet: - the CSS stylesheet to control the ePub production. The sample comes with a default
-*formats: - controls the formats to produce the output; you can list one or more, and the script will produce those formats. docx and epub are currently supported.
A premium feature to include external content is covered in the advanced guide.
A chapter can optionally include frontmatter, and having it helps in stats generation. Regardless, a chapter must have an empty frontmatter delimiter ---.
-name: a name for the chapter, just a way to distinguish it
-pov: a “point-of-view” if your chapters have a POV structure. This is then used by the stats engine to produce pov metrics (i.e., which charater used what % of the book); use can reuse this label for any other purpose too.
-synopsis: a brief description of the chapter, used in future versions of pq to show chapter summaries
-exclude: excludes this chapter from all processing; great if you want to have draft chapters, or wish to exclude for whatever reason
Make sure to look at the
sample.mdthat came with the download and spend some time playing with it by modifying.
There’s another little label that will exclude a chapter ONLY if you are running the script to generate a boxset; this is great to exclude chapters from boxsets that may be repeating in other books in the set.This is covered in the premium access..