Placeholder Tags (Variables)

There may be times in Scrivener when you want to enter information that isn’t yet known, which can’t be known until the draft is compiled, or which may change. For instance, you may want to include the page number in the header or footer, the word count and current date on your title page, or numbers after your chapter titles. Until you compile your draft, Scrivener doesn’t know what pages will be present in the final manuscript or which text documents will be included, so it would be difficult for Scrivener to maintain a live representation of such information in your text, but it’s not ideal to have to re-type these things every time they change. The solution is to use placeholder tags - these are tags that you can type anywhere in Scrivener (in the main text, the titles, in the title prefix and suffix fields of the Formatting pane in the Compile sheet, and so on), which will be replaced with specific information in the compiled document. For instance, if you enter the tag <$surname>, when you compile the text, this tag will be replaced with the surname of the current user. There is also a set of tags to help you create project templates that need to include specific information about the user creating the project from your template, such as his or her name and address on the title page.

Generally, you won’t want to litter your text with placeholder tags. Rather, they are intended to be useful for setting up title pages, creating template projects, and setting up the Compile options (for instance, the auto-number tags can be added in the title options of the Formatting pane of the Compile sheet to generate automatic chapter titles and numbers - take a look at some of the project templates that come with Scrivener for examples). You don’t have to use placeholder tags at all, of course, and they are a rather advanced feature, but as there are times when you may find them useful, provided below is a complete list of the placeholder tags you can use in Scrivener.


Template Tags

You can use template tags when putting together a project you intend to turn into a template using File > Save as Template. When a Scrivener project is created from a template (via the New Project templates chooser), all of the following tags will be replaced with the relevant data from the user’s Address Book or elsewhere before the project appears on screen. You can thus use these tags to create templates that include user-specific information such as name and address, which can be useful for setting up title pages and suchlike.

Tip: To create a new project without having these tags automatically replaced, hold down the Option key while clicking on “Choose…” in the New Project template chooser panel. (This is useful for updating templates or creating your own templates based on existing ones.)


<$template_firstName>

User’s forename of first name as set in Address Book.

<$template_lastName>

User’s surname or last name as set in Address Book.

<$template_fullName>

User’s full name, from Address Book or account settings.

<$template_initial>

First letter of user’s forename, as set in Address Book.

<$template_street>

User’s street name, taken from Address Book.

<$template_city>

User’s city or town, taken from Address Book.

<$template_state>

User’s state or county, taken from Address Book.

<$template_ZIP>

User’s ZIP or postcode, taken from Address Book.

<$template_country>

User’s country, taken from Address Book.

<$template_phoneNumber>

User’s phone number, taken from Address Book.

<$template_email>

User’s e-mail address, taken from Address Book.

<$template_projectName>

The project title, derived from the project file name.



Compile Tags

The following tags can be entered anywhere in your project and will be replaced with specific information in your compiled document.

Escaping Compile tags: In very rare circumstances (for instance, if you were writing a book about Scrivener), you may find that you want to write about a tag and so have it appear in the final text without being replaced. For this, Compile tags can be “escaped” using the backslash character. Thus, “\<$date>” will appear in the compiled document as “<$date>”, without being replaced with the current date.


Page Numbers

<$p>

When used in the header or footer, gets replaced with the current page number.

When used in the main text and it has an internal document link associated with it, the <$p> tag will be replaced with the page number on which the linked document appears if possible.

<$p-r>

<$P-R>

When used in the header or footer, gets replaced with the current page number as Roman numerals (use <$p-r> for lowercase Roman numerals and <$P-R> for uppercase Roman numerals). Unlike <$p>, which can show negative numbers for front pages, Roman numerals always start at “i”.

Mainly intended for use on front matter pages. (Note that these tags may not be supported by all formats.)

<$pagecount>

When used in the header or footer, gets replaced with the page count (note that this tag only works in headers and footers). Note that for formats other than standard Print and PDF, this will count all pages, even front matter pages that do not have page numbers (for Print and PDF, front matter without page numbers is not included in the count).





Headers and Footers

Not all tags are supported in headers and footers. In addition to the special header and footer tags specified below (which can only be used in headers and footers), only the tags listed under the sections Page Numbers, Current Date and Time, and User and Project Information are supported in headers and footers.

<$sectiontitle>

Gets replaced with the title of the document that first comes after the page break most recently preceding the header or footer in which it occurs. In practice, this is useful for placing chapter titles in headers or footers. For instance, if you have a chapter in a single text document starting on a new page, then that document’s title will replace “<$sectiontitle>”; if your chapters are broken down into smaller sections placed inside folders, and the folders mark the start of each new chapter, then the folder’s title will replace “<$sectiontitle>” throughout the chapter headers and footers.

Note that if the section title cannot be calculated for any reason (for instance, because there is no text in the section associated with any documents), <$sectiontitle> may fall back on using the abbrevated project title (working the same as “<$abbr_projecttitle>” - see User and Project Information for details on where the abbreviated project title is drawn from).





Comments, Footnotes and Layout

<$--ENDNOTES-->

Tells the compiler where to place the endnotes. If this tag is not present, the endnotes will get placed at the end - this tag just provides a way to customise the placement of the endnotes. (Note that this tag cannot be used with script, MultiMarkdown or e-book formats, and can only be used with RTF if “Flatten footnotes…” is selected in the Layout compile options.)

<$--COMMENTS-->

Tells the compiler where to place linked comments. If this tag is not present, linked comments will be placed at the end of the text before any endnotes. Note that this tag can only be used with the HTML format.

<$BLANK_PAGE>

Tells the compiler to leave this page blank. At the end of compiling the text, Scrivener goes through looking for potentially blank pages and removes them, but if it finds this tag on an otherwise blank page, it just removes the tag and leaves the page blank.





Document  Variables

Document variable tags can be placed anywhere inside the text of a document (note that they cannot be used in the Compile panel’s header and footer fields).

<$title>

Gets replaced with the document title during the Compile process (that is, the title of the document in the binder in which this tag occurs). If associated with an internal document link, gets replaced with the title of the linked document.

<$parenttitle>

Gets replaced with the title of the parent of the document (e.g. the folder in which the document is contained). If associated with an internal document link, gets replaced with the title of the parent of the linked document.

<$title_no_spaces>

The same as <$title>, but strips all spaces from the title. Potentially useful for compound tags. (If associated with an internal document link, gets replaced with the title of the linked document.)

<$parenttitle_no_spaces>

The same as <$parenttitle>, but strips all spaces from the parent title. Potentially useful for compound tags. (If associated with an internal document link, gets replaced with the title of the parent of the linked document.)

<$position>

Gets replaced with the position number of the document within its parent folder or container. Potentially useful for compound tags.

<$parentposition>

The same as <$position>, except uses the position of the parent within its parent folder or container. Potentially useful for compound tags.

<$label>

Gets replaced with the name of the document label during the Compile process. If associated with an internal document link, gets replaced with the name of the document label of the linked document.

<$status>

Gets replaced with the name of the document status during the Compile process. If associated with an internal document link, gets replaced with the name of the document status of the linked document.

<$keywords>

Gets replaced with a list of keywords associated with the document during the Compile process. If associated with an internal document link, gets replaced with the keywords of the linked document.

<$synopsis>

Gets replaced with the document synopsis during the Compile process. If associated with an internal document link, gets replaced with the synopsis of the linked document.

<$linecount>

Gets replaced with the line count of the document during the Compile process. If associated with an internal document link, the line count will show the number of lines in the linked document.

<$revision>

Gets replaced with the revision number of the document. (The revision number is the number of snapshots associated with the document plus one.)

<$createdDate>

<$shortCreatedDate>

<$mediumCreatedDate>

<$longCreatedDate>

<$fullCreatedDate>

Gets replaced with the created date of the document, using one of the formatting styles specified in the System Preferences. (Note that <$createdDate> is the same as <$shortCreatedDate>).

<$createdTime>

<$shortCreatedTime>

<$mediumCreatedTime>

<$longCreatedTime>

<$fullCreatedTime>

Gets replaced with the created time of the document, using one of the formatting styles specified in the System Preferences. (Note that <$createdTime> is the same as <$shortCreatedTime>).

<$modifiedDate>

<$shortModifiedDate>

<$mediumModifiedDate>

<$longModifiedDate>

<$fullModifiedDate>

Gets replaced with the modified date of the document, using one of the formatting styles specified in the System Preferences. (Note that <$modifiedDate> is the same as <$shortModifiedDate>).

<$modifiedTime>

<$shortModifiedTime>

<$mediumModifiedTime>

<$longModifiedTime>

<$fullModifiedTime>

Gets replaced with the modified time of the document, using one of the formatting styles specified in the System Preferences. (Note that <$modifiedTime> is the same as <$shortModifiedTime>).

<$custom:…>

Can be used to insert custom meta-data in the draft. For instance, if you have added a custom meta-data field entitled “Locations” to your project, “<$custom:Locations>” will get replaced with the information in the Locations field for the document during the Compile process. (If associated with an internal document link, gets replaced with the custom meta-data of the linked document.)





Current Date and Time


<$date>, <$shortdate>

Gets replaced with the current date during the Compile process, using the short date format defined in the user’s System Preferences.

<$mediumdate>

Gets replaced with the current date during the Compile process, using the medium date format defined in the user’s System Preferences.

<$longdate>

Gets replaced with the current date during the Compile process, using the long date format defined in the user’s System Preferences.

<$fulldate>

Gets replaced with the current date during the Compile process, using the full date format defined in the user’s System Preferences.

<$time>, <$shorttime>

Gets replaced with the current time during the Compile process, using the short time format defined in the user’s System Preferences.

<$mediumtime>

Gets replaced with the current time during the Compile process, using the medium time format defined in the user’s System Preferences.

<$longtime>

Gets replaced with the current time during the Compile process, using the long time format defined in the user’s System Preferences.

<$fulltime>

Gets replaced with the current time during the Compile process, using the full time format defined in the user’s System Preferences.

<$year>

Gets replaced with the current year during the Compile process.

<$shortnumericalmonth>

Gets replaced with the current month during the Compile process, using single or double digits (i.e. “3” for March and “11” for November).

<$numericalmonth>

Gets replaced with the current month during the Comple process, using double digits (i.e. “03” for March” and “11” for November).

<$shortmonth>

Gets replaced with the current month during the Compile process, using the abbreviated month name (e.g. “Mar” for March).

<$month>, <$longmonth>

Gets replaced with the current month during the Compile process, using the full month name.

<$day>, <$shortday>

Gets replaced with the current day of the month during the Compile process, using single or double digits.

<$longday>

Gets replaced with the current day of the month during the Compile process, using double digits only.

<$shortweekday>

Gets replaced with the current day of the week during the Compile process, using the abbreviated weekday name (e.g. “Tues”).

<$weekday>, <$longweekday>

Gets replaced with the current day of the week during the Comple process, using the full weekday name.





User and Project Information


<$surname>, <$lastname>

Gets replaced with the user’s surname or last name during the Compile process. The information is taken from the “Project Properties” in the Project > Meta-Data Settings panel or, if that is blank, from the user’s Address Book. If the tag appears in uppercase, the surname will be uppercased too.

<$forename>, <$firstname>

Gets replaced with the user’s forename or firstname name during the Compile process. The information is taken from the “Project Properties” in the Project > Meta-Data Settings panel or, if that is blank, from the user’s Address Book. If the tag appears in uppercase, the forename will be uppercased too.

<$initial>

Gets replaced with the first letter of the user’s forename during the Compile process.

<$author>, <$name>, <$fullname>, <$username>

Gets replaced with the user’s full name during the Compile process. The information is taken from the “Project Properties” in the Project > Meta-Data Settings panel or, if that is blank, from the user’s Address Book. If the tag appears in uppercase, the user’s name will be uppercased too.

<$compilegroup>

Gets replaced with the name of the group currently being compiled (as selected in the “Contents” pane of the Compile sheet). If the tag appears in uppercase, the name will be uppercased too.

<$draftname>

Gets replaced with the title of the Draft folder during the Compile process. If the tag appears in uppercase, the title will be uppercased too.

<$projecttitle>, <$projectname>

Gets replaced with the project name during the Compile process. The project name is taken from the “Project Properties” in the Project > Meta-Data Settings panel or, if that is blank, from the file name of the Scrivener project. If the tag appears in uppercase, the project name will be uppercased too.

<$abbr_projecttitle>, <$abbr_projectname>, <$abbr_title>

Gets replaced with the abbreviated project name during the Compile process. The abbreviated project name is taken from the “Project Properties” in the Project > Meta-Data Settings panel or, if that is blank, from the file name of the Scrivener project. If the tag appears in uppercase, the abbreviated project name will be uppercased too.





Statistics


<$wc>

Gets replaced during the Compile process with the total word count of the text currently being compiled.

<$wc50>

Gets replaced during the Compile process with the total word count of the text currently being compiled, rounded to the nearest 50 words.

<$wc100>

Gets replaced during the Compile process with the total word count of the text currently being compiled, rounded to the nearest 100 words.

<$wc500>

Gets replaced during the Compile process with the total word count of the text currently being compiled, rounded to the nearest 500 words.

<$wc1000>

Gets replaced during the Compile process with the total word count of the text currently being compiled, rounded to the nearest 1000 words.

<$cc>

Gets replaced during the Compile process with the total character count of the text currently being compiled.

<$cc50>

Gets replaced during the Compile process with the total character count of the text currently being compiled, rounded to the nearest 50 characters.

<$cc100>

Gets replaced during the Compile process with the total character count of the text currently being compiled, rounded to the nearest 100 characters.

<$cc500>

Gets replaced during the Compile process with the total character count of the text currently being compiled, rounded to the nearest 500 characters.

<$cc1000>

Gets replaced during the Compile process with the total character count of the text currently being compiled, rounded to the nearest 1000 characters.





Auto-Numbering


<$n>

Gets replaced with Arabic numerals during the Compile process. The number is incremented each time a <$n> tag is encountered in the text, so “<$n>, <$n>, <$n>” would become “1, 2, 3” in the compiled text.

<$sn>

The same as <$n> but intended to be used for sub-numbering. The count restarts each time an <$n> tag is encountered. Thus, “<$n> (<$sn>, <$sn>), <$n> (<$sn>, <$sn>)” would become “1 (1, 2), 2 (1, 2)” in the compiled text.

<$r>

Gets replaced with lowercase Roman numerals during the Compile process. The number is incremented each time a <$r> tag is encountered in the text, so “<$r>, <$r>, <$r>” would become “i, ii, iii” in the compiled text.

<$R>

Gets replaced with uppercase Roman numerals during the Compile process. The number is incremented each time a <$R> tag is encountered in the text, so “<$R>, <$R>, <$R>” would become “I, II, III” in the compiled text.

<$l>

Gets replaced with lowercase outline (alphabetical) numbering during the Compile process. The number is incremented each time an <$l> tag is encountered in the text, so “<$l>, <$l>, <$l>” would become “a, b, c” in the compiled text.

<$L>

Gets replaced with uppercase outline (alphabetical) numbering during the Compile process. The number is incremented each time an <$L> tag is encountered in the text, so “<$L>, <$L>, <$L>” would become “A, B, C” in the compiled text.

<$w>

Gets replaced with numbers as lowercase words (using the current language settings) during the Compile process. The number is incremented each time a <$w> tag is encountered in the text, so “<$w>, <$w>, <$w>” would become “one, two, three” in the compiled text.

<$t>

Gets replaced with numbers as title-case words (using the current language settings) during the Compile process. The number is incremented each time a <$t> tag is encountered in the text, so “<$t>, <$t>, <$t>” would become “One, Two, Three” in the compiled text.

<$W>

Gets replaced with numbers as uppercase words (using the current language settings) during the Compile process. The number is incremented each time a <$W> tag is encountered in the text, so “<$W>, <$W>, <$W>” would become “ONE, TWO, THREE” in the compiled text.

<$hn>

Gets replaced during the Compile process with hierarchical numbering based on the level of the document in which the tag occurs relative to the Draft folder or compile group (depending on the current compile settings). So occurrences of the <$hn> tag in the second document in the Draft folder may get replaced with the number “2”; occurrences of the tag in the third subdocument of the eighth document in the Draft folder may be replaced with “8.3”.

You can assign internal document links to the <$hn> tag to refer to other sections - if the <$hn> tag has a document link associated with it, it will be replaced with the hierarchical numbering of the linked document. Note, however, that this only works if the linked document contains an <$hn> tag itself (for instance, in its title).

Restarting auto-numbering streams:

<$rst>, <$rst_…>

Place <$rst> immediately before any of the auto-numbering tags to restart the numbering. So, for instance, “<$w>, <$w>, <$w>, <$rst><$w>, <$w>” would become “one, two, three, one, two” in the compiled text. Alternatively, you can place <$rst_X> anywhere in the text, replacing the “X” with the letter used in the auto-numbering tag you wish to restart. E.g. <$rst_R> would restart the uppercase Roman numeral auto-numbering from that point onwards.

Using named auto-numbering streams:

<$n:…>, <$w:…>

You can assign names to any of the auto-numbering variables to create unique streams by inserting a colon and any name of your choosing between the auto-numbering letter and the final bracket. For instance, you could use “<$t:part>” (where “part” is the name you have chosen) as the auto-numbering tags for the titles of parts in a book, and “<$t:chapter>” for the chapters.  In this example, the text “Part <$t:part>, Chapter <$t:chapter>, Chapter <$t:chapter>, Chapter <$t:chapter>, Part <$t:part>, Chapter <$t:chapter>,  Chapter <$t:chapter>” would result in “Part One, Chapter One, Chapter Two, Part Two, Chapter Three, Chapter Four” in the compiled text. Please note that names cannot contain any whitespace (such as spaces).

Figure and table numbering:

<$n:table:myTableName>

<$n:figure:myFigureName>

You can create special auto-numbering tags that include a name and a keyword to enable you to refer back to auto-numbers, for instance for referring to tables and figures. The format of such auto-numbering tags is this:


<$[auto-number-type]:[name]:[keyword]>


Subsequent instances of tags that use the same auto-number type, name and keyword will be replaced with the same number as was generated for the first instance of that combination; only tags that have a different keyword will cause the number to be incremented. This is best explained with an example:


[An image]

Figure <$n:figure:myImage>


[Another image]

Figure <$n:figure:nextImage>


[A table]

Table <$t:table:myTable>


See Figure <$n:figure:myImage>, Figure <$n:figure:nextImage> and Table <$t:table:myTable>.


When compiled, this will result in the following:


[An image]

Figure 1


[Another image]

Figure 2


[A table]

Table One


See Figure 1, Figure 2 and Table One.


Note how the tag “<$n:figure:myImage>” occurring later in the text was replaced with the same number (“1”) generated for the first instance of that tag.


If you want to create a forward reference, for the reference use the format:


<$[auto-number-type]#[name]:[keyword]>

(i.e. Use a hash instead of the first colon.)


E.g:


<$n:eg:foo> Example sentence.


See example <$n#eg:foo> and compare it with <$n#eg:bar> below.


<$n:eg:inbetweener> Another sentence.

<$n:eg:bar> The final sentence.


When compiled, this will result in the following:


1 Example sentence.


See example 1 and compare it with 3 below.


2 Another sentence.

3 The final sentence.


Using names and keywords in auto-numbering tags can thus allow you to refer to table and figure numbers. (Note that names and keywords cannot contain any whitespace characters such as spaces.)


Restarting tagged auto-numbering streams:

<$rst_KEYWORD>

You can restart one of the tagged auto-numbering streams by using the <$rst_KEYWORD> tag anywhere before an occurrence of one of the tags. For instance, <$rst_imageNumber> would restart tags such as <$n:imageNumber> or <$n:imageNumber:myImage>.

Compound tags

You can create compound tags by using other tags inside the tagged auto-numbering or figure and table numbering. For instance, it is possible to use “<$n:figure:<$parentposition>>” as a valid figure auto-numbering tag, because the document variables such as <$parentposition> will get replaced before the auto-numbering variables.

Making tags more readable

You can use the Compile sheet’s “Replacements” pane to make compound and other tags more readable while you are writing your text. For instance, in the Stageplay UK project template, act and scene numbers appear in the text as “ACT [N] SCENE [R]”. This phrase is then replaced in the Compile sheet’s replacement pane with “ACT <$R:ACT:<$PARENTPOSITION>> SCENE <$N:<$PARENTPOSITION>>”. This allows each scene to reference its act number, because a folder is used to hold the scenes of each act, so “<$PARENTPOSITION>” can be used to give each act a unique tag. The result is this: “ACT I SCENE 1”, “ACT I SCENE 2”, ACT I SCENE 3”, “ACT II SCENE 1”, “ACT II SCENE 2”, and so on.





Images


<$img:imgName>

<$img:imgPath>

<$img:imgNameOrPath;w=x;h=y>

You can use the <$img…> tag to have images inserted into your text during Compile. This can be useful if you want to insert an image into a title prefix or suffix, if you want to keep images out of the text while writing, or if you want to include certain images only conditionally (you could use the “Replacements” pane of Compile to remove image tags for images you don’t want to appear in a particular Compile format, for instance).

Image tags support image documents that have been imported into the project - in which case you should use the name of the document on its own - or file paths to images on disk. For instance:

<$img:My Image Document>

<$img:~/Pictures/My Image File.png>

(If the image file is stored in the same directory as, or a subdirectory of, the .scriv project, a relative path can be used.)

You can also define the width and height of the image thus:

<$img:My Image Document;w=400;h=200>

As in HTML, specifying only one of either the width or height will cause the other dimension to be scaled proportionally:

<$img:~/Pictures/My Image File.png;w=400>

Remember that the image will use the same formatting as the tag, so if you want the image to be centred with no line spacing, you must format the tag accordingly.

Tip: If you have more than one image in the project with the same name, you can specify the exact image by using an internal document link.





Miscellaneous


<$toc>

Used when compiling e-book formats only. If the <$toc> tag appears in an otherwise blank document when compiling to an e-book format, and if that document’s title matches the title assigned to the table of contents (in the “Layouts” pane of Compile), then this document will be replaced with an automatically-generated table of contents. This allows the user to determine where the automatically-generated table of contents should be placed in cases where it is not wanted at the very start of the e-book. (Tip: Tick “Page Break Before” and “Compile As-Is” for the document in which you place this tag.)

<$ebook_start>

Used when compiling to Kindle .mobi format only. If this is present in a document and “Book begins after front matter” is not ticked in the compile Layout options, the exported Kindle file will be set to open at the section that contains this tag. Note that it may not work as expected if you place it in a table of contents page, because some Kindle devices do not seem to like this.