BETA
TOC

Tag Reference Guide

Tags give superpowers to your manuscript

Pre-Requisite: Please make sure to read getting started before you continue.

Tags augment your manuscript with useful metadata (for those familiar with Markdown, perhaps think of this as Author Markdown) that PublishQuickly uses to provide features. Not only do tags help with your own writing discipline, but they help you cut down time on various activities that ultimately helps you get to publishing faster and with better quality.

While all tags are optional, you will truly harness the power of this platform if you use tags. They're very simple to understand!

There's really two basic rules for tags:

  1. Every tag begins on a new line with @ and ends at the end of a line.

  2. Tags are case sensitive (@nostats will work but @NOSTATS may not)

Before we jump into it, another quick intro to how a chapter is organized.


header area

[[body]] 

content area

x--------------------------------------x ====> chapter separator

Tags Overview

There are three types of tags. All tags are optional.

BOOK TAG: Applied once per manuscript—Each of these tags is processed exactly once per manuscript (like @title--there's only one title for the book). You can mention them multiple times, in which case only the last one is picked. Book tags must appear in the header area of any chapter.

CHAPTER TAG: Applied on a chapter basis—These tags are processed for every chapter, like @synopsis--every chapter has a synopsis. Chapter tags must appear in the header area of a chapter.

CONTENT TAG: Applied in body of chapter—These tags are special in that they are processed within your chapter content. (like @insert to place your backmatter)

Before the explanations, here’s how a really simple “book” with just one chapter might look. One without any tags, and one with tags.

First: a chapter with no tags.

[[body]]

John went to the forest.

x----------------------x

Next, let’s add a couple of header tags.

@title John and the Lion

@synopsis John finds the lion.

@out beta

[[body]]

John went to the forest.

x----------------------x

Now that you got a sense of the tags, let’s look at all the tags supported and what they do. We also cover some tips and examples.

top


Book level tags

ASIN

book

@ASIN [code]

Enter your Amazon ASIN code to automatically get a list with links to 10 prominent Amazon stores.

Example:

@ASIN B07PWNYR3Z

will result in:

For e.g., https://www.amazon.com/dp/B07PWNYR3Z

series

book

Specify a series for your book (if it belongs to a series)

@series The X312 chroncles

author

book

Specify author of the work

@author Jane Doe

title

book

@title John and the Lion

Give your book a title. Used for internal references, and for history building.

A title is required along with @tid for building your manuscript history.

tid

book

@tid JatL1

Give your title a unique identifier. This is required along with the title if you wish to avail of the history builder feature.

When a book has @tid specified, we will record the book's count and chapters in a history entry automatically every time you generate, giving you the chance to see your book's progress. Having a @tid gives you the freedom to change your book's title at any point without losing its development history.

This is great for those who wish to track their word progress over time, and to look back at how they did. (Feature WIP)

tid must be at least 3 characters long, must be unique (among your books), and can be any letter or number without space in between. For e.g., aXn, 12AB, MtKlc, xYzA

top


version

book

@version [label]

Specify a version for the manuscript. This can be very handy, here's how:

Here’s how:

Specify version once - e.g., @version 1.2.1

Now, anywhere in your chapters, let’s say in the copyright chapter, use the phrase {{version}}

For e.g.,

[[body]]

This book (c) John Doe 2020. All events are fictional.

v_{{version}}

Will become

[[body]]

This book (c) John Doe 2020. All events are fictional.

v_1.2.1

And appear in the output Word or ePub documents that you generate.

The benefit is that when you upload the book to, say, KDP, you can always check what’s online vs. your current version (if you made local updates) and track back for any reason.

You can make it even more useful with the use of {{now}} which is replaced with a date and time at which the doc was generated. For e.g.,

v_{{version}} {{now}} will result in v_1.2.1 2021.04.14.09.45.23

top


wpp

book

specify a directional words-per-page

@wpp [number]

Example usage:

@wpp 250

This is for directional calculation of pages. Put a number that you think is sensible for your book – 250 is a good benchmark value, to indicate that the page size is 250 words, and the PublishQuickly can report out pages per chapter using this as a basis.

It is important to understand that while this is directional, it is still very useful to get a sense of your book size and chapter lengths.

Note: The value after the tag has to be a positive number >= 50. Anything lesser is treated as 50, and anything greater than 1000 is treated as 1000

top


Chapter level tags

exclude

chapter

exclude chapter's body from being considered

@exclude

Use this when you want to use the chapter purely as a reference or a scratch pad. All body in the chapter is ignored, but relevant book level tags in the header are processed.

Tip: Make your first chapter a @exclude chapter and add all the book level tags.

Here’s an example of an @excluded chapter.

@exclude

@title Water Lilies are Silly

@author Wasser. S. Silli

@series Silly Chronicles

@synopsis This is just a book header chapter

[[body]]

All this is excluded - it won't show up in the output

x-------------------------------x

The app also ignores the exclude chapter from any chapter, page, or book counts.

top


glossary

chapter

@glossary word1 word2 word3 … wordn

You can specify one or more words of glossary in any chapter. For e.g., you may have a few glossary words in one chapter

@glossary TCP AWS Cloud

and in another chapter you have

@glossary AI ML RPA

PublishQuickly will then consolidate all of them, sort them Alphabetically, and create a glossary markdown file in output that you can paste wherever you want. Makes it really convenient!

The Markdown file will look like this:

# GLOSSARY

## A

AI
AWS

## C

Cloud

## M

ML

## R

RPA

## T

TCP

Note: Glossary terms have to start with an alphabet. Terms starting with a number or special character will be ignored. For example oneRange is fine, but 1Range is not.

top


inverse

chapter

@inverse

handy tag!

exclude this specific chapter in an output of type inverse

When you use the @inverse tag in some of your chapters and generate, you get two Word documents:

Doc 1 - your full manuscript

Doc 2 - your full manuscript EXCLUDING the chapters that had the inverse tag

This is particularly helpful for proofread or beta--for example maybe you want to exclude the copyright, title, dedication, end thank-you's etc.--then @inverse is perfect for that.

In other words, instead of saying “I want these chapters in this variant,” you may want to say “I want to exclude these chapters and create a variant”

Here’s an example of an @inverse chapter.

@inverse 

@synopis how inverse works

[[body]]  

This chapter appears in your core, but won't be there in a variant called inverse.  

x-------------------------------x

What if you wanted a variant that only includes a couple of chapters from the book? For example for a sample release, to send to a prospective agent?

For that, you use the @out tag--so keep reading.

top


name

chapter

give a name to the chapter

@name [a word]

For example:

@name ch_25

[[body]]

John wondered what was in the forest.

x-------------------------------x

Tip:

Give names like ch00, chmid, chend to make it easy to go to your first chapter, middle of the book, end.

If you use the skeletal generator, you can get your chapter name autonumbered.

top


noboxset

chapter

exclude chapter from a boxset or series collection

@noboxset

When you create a boxset, sometimes you don't need certain chapters from your individual books because it becomes repetitive content (e.g., thank you’s / your other works pages) or any other reason. Using a @noboxset tag will let you exclude those chapters from the produced boxset.

Just add @noboxset to the chapter header. That’s all.

top


nostats

chapter

Exclude chapter's word count from final book word count

@nostats

Excludes the words in the body of a chapter from all word counting, useful when the chapter is for copyright statements, cover page, dedication, back-matter and so on and you don’t want to count them as part of your book’s word and page count (though technically they all count)

top


pov

chapter

Define a point-of-view for a chapter

@pov [name]

Indicates the point-of-view of this chapter. You can have one POV per chapter. We report pov metrics–like how much of your book is taken by the character John and how many chapters John appears in.

What if your entire book has just one POV? Or your book is non-fiction and has no POV?

Well, the POV tag can be creatively reused for other purposes.

Remember, it’s just a tag, and statistics on it are reported. You can reuse it, for example, to classify your chapters by type of content, like action, backstory, fights, romance or say geography US, India, Brazil, Canada or sentiment dark, happy, sappy and so on, it doesn’t matter. It’s whatever classification that helps you better understand your manuscript.


@pov John

[[body]]

John went to the forest.

x--------------------------------------x

top


out

chapter

produce a specific subset of your book

@out label

Let’s say your book has 20 chapters, but you want to only send three specific chapters to someone.

Just tag those chapters as, say, sample and you will get an output with chapters that only have the sample tag.

For example:

@out sample or @out agent

each with only those chapters that had that tag.

When you use the @out tag, you get two documents:

Doc 1 your full manuscript

Doc 2 only the @out tagged chapters

Important note: Consider using the @inverse tag if all you want to do is exclude specific chapters from the core and create a separate output. For most people, this may be sufficient! out is the opposite of inverse.

top


replacer

chapter

replace a phrase with another in the body

@replacer [word,replacement | word2:replacement2,....]

This is a powerful tag. What this let’s you do is use specific patterns in the body of your chapters, and allow the app to replace that pattern with something else during output generation.

This can be a huge timesaver in many cases, and we’ll explain more below.

  1. You can specify @replacer once in your manuscript, with as many pairs until a new line.

  2. The replacement can be any Markdown compliant text.

Here are some examples:

@replacer {{wf}}:Wisit D. Forest, {{mk}}:![](map.png)

@replacer {{iod}}:Illiad and Odyssey, {{hm}}:His Majesty

Each time {{wf}} appears in the body, it is replaced by Wisit D. Forrest, and each time it encounters {{mk}} it is replaced with a Markdown phrase that points to an image file. When the tool produces the output documents, you will see the replaced values.

This can be a terrific time saver, here's how:

Let's say you wanted to use a pretty ornamental picture below chapter headings. All you have to do is give it a text phrase (mk above) and the equivalent image reference. No more fiddling with images. We generate the output with the image wherever the phrase appears.

Not only that, if you wanted to change the image to something else in your entire book, just change the image reference and regenerate--takes seconds! Imagine doing that in Word!

Another good example is using it to replace complicated names. Instead of typing Megadoloarcheopterix fifty times, you could use {{ax}} as the replacer.

Replacer rules:

  1. You can define it once per manuscript

  2. You can define as many as you want, so long as it’s a single line that ends with a newline

  3. The replacement content should be a markdown sentence or word

  4. Just be aware to define unique replacer phrases that don’t occur in your general body!

Out-of-the-box Replacers

The app comes with several out-of-the-box replacers, i.e. if you use the specified phrase, the app replaces them with some standard values. The following are supported by default. They are further described below.


{{now}}

{{version}}

{{asin}}

{{#n}} 

{{#r}} 

top


Versioning Your Book

{{version}} anywhere in your text is replaced by the @version you specified.

{{now}} is replaced by the current server date and time: good for versioning document production versions at the exact time of production.

For example:

[[body]]

This book (c) John Doe 2020. All events are fictional.

Version {{version}} Produced on {{now}}

Becomes

This book (c) John Doe 2020. All events are fictional. 

Version 1.2.1 Produced on 2020.08.20.11.45.20 

Automatic Chapter Numbering

{{#n}} is replaced by a sequentially increasing chapter number, +1 from the previous--this is fantastic for novels and saves a ton of time fiddling with numbering, removing them selectively and so on.

You can specify only those chapters that need to have a chapter number (e.g., a novel with many parts with chapters in-between in a running sequence).

For example:

[[body]]

# CHAPTER {{#n}}.

## NEW YORK, 2048

becomes

CHAPTER 10. 

New York, 2048

You can reset your numbering from any chapter and go back to 1 by using {{#r}}

ASIN Linking for your Inserts

{{asin}} replaces it with the value specified in @ASIN tag. This is useful if you have inserts where you want to build multiple links to various Amazon stores. All you need to do is type https://www.amazon.de/dp/{{asin}}

For example, this can be used in the back-matter pages.

top


synopsis

chapter

Give the chapter a summary

@synopsis [paragraph]

Give the chapter a summary. Having synopses creates a certain discipline, and helps you understand the flow. The Results page shows each chapter with synopsis.

@synopsis the Lion stalks John and he is unaware

[[body]]

John was full of himself. The lion was stupid, he was sure.

x-----------------x

top


Body level tags

insert

body

insert reusable content into body

@insert file.txt or .md

Another incredibly powerful feature. Insert will replace the tag line with the contents of the file specified.

Note: A file with the exact name must be in your vault.

This is very helpful when you want to reuse content across books – for example, a listing of your other books or a common thank you note.

Note: @insert comes with the following limitations:

  1. It only replaces .md or .txt, and does not process tags inside it.

  2. It is a blind insertion. And a chapter can have only ONE insert in the body.

Remember: the @insert tag is inside the body. It is not a header tag.


@synopsis list author's other books

[[body]]

@insert myotherbooks.md

x--------------------------------------x

Tip: Isolate your book back-matter or generic “visit my author site” or other content to a separate markdown file.

This will make it really easy to update your reused content as you write new books or links change for your website and so on, and recreating your books with the new content literally takes seconds! No more cut-copy-paste-format and all that time-sucking nonsense.

Reminder: Out-of-the-box replacers also work in the replaced body

Note: You cannot add reference paths to the file. Only add the file name.

for e.g. @insert ../mybooks.md is not NOT allowed, but @insert mybooks.md is allowed--assuming you have access to the vault and you have uploaded a file called mybooks.md

top


Summary

Hopefully this gave you a good sense of what tags are and what they can do for you. Start using some of them or play with the sample provided in the generator.

Come on and get productive!

top