Hierarchical numbering for cross-references


I’m using Scrivener 2.6 and would like to have hierarchical numbering for cross-references (tables and figures). While I know from the help file explaining placeholder tags that I can use the <$n:figure:someText> tag, the explanations have the general syntax as <$[auto-number-type]:[name]:[keyword]>, suggesting that something like <$hn:figure:someText> should also be possible.

But when using this, the compiled output does not expand the tag at all, it seems only to work with <$n:…> but not with <$hn:…>. Is this correct or do I miss something? Is hierarchical numbering of figure and tables not possible (following the headings numbers)?


The <$hn> counter is different from the rest in that it is not actually a sequential counter, it doesn’t increment when you use it, but rather is more like a document meta-data placeholder, such as <$position>, which prints the numeric order of the item within its folder context. No matter how many times you use either of these, one after the other, they will always print the same number until you move them to another location in the outline.

So, unless your section is broken up into multiple pieces, so long as the figure or table caption resides within that same text document, you can use it for further references to the number. It will print “1.18.4” for each usage within that section.

Thanks for the answer, but that is not what I am after. I know the <$hn> tag is resetting in every „folder context“, this is what I want to have, i.e. „Figure 1.1“, „Figure 1.2“ and so on in chapter 1 and then „Figure 2.1“, „Figure 2.2“ in chapter 2.

This is the point. It actually does not print any number at all. In my text I have the tag <$hn:figure:myFigure>. When I compile this, the output still says <$hn:figure:myFigure> and not „1“ or „1.1“ or similar. The tag is not recognized as a tag, it seems. When I instead use <$n:figure:myFigure>, the tag IS recognized and sequential numbers appear in the output.

So, either I am doing something fundamentally wrong, or tags of the type <$[auto-number-type]:[name]:[keyword]> are not supported with auto-number-type „hn“. Bug or feature?


Yes, to expand on what I was saying since I wasn’t explicit, since the $hn token merely reports the physical position of an item in the hierarchy, there is no use for named streams or counter instances since you can only ever have one value for the position for a particular item, and besides the full sequence (1.2.18) would rarely be useful outside of the title itself.

So as to what you are trying to do, specifically, there isn’t a way to do that. The $hn tag produces a whole sequence wherever it is used, and there is no way to extract just a piece of that sequence for use in captions or whatnot. The $parentposition code may be of some limited use, so long as the caption is a direct child of the chapter item and you don’t keep any excluded documents in the Draft ($parentposition is absolute, and disregards compile selections, so it will get out of sync with $hn if used as a substitute in a tree that as excluded items).

However, what you are wanting to do, in isolation, is possible but not with the $hn tag. You can for example number chapters with <$n:chapter:someChapterTitle>, which then makes a “hook” for your figure numbers to use (same as the figure number itself). One possible way of combining the two ideas together would be to generate named chapter numbers on the side, thus continuing to use $hn for the main visible numbers, but also generating a chapter numbering sequence for your captions.

The trick to this method is that if you use a second token to track the numbering of your chapters, that number has to be physically printed somewhere in the output in order for it to be registered. Fortunately, with Scrivener we can generate that number for purposes of cross-referencing, and then later in the compile process, wipe out the generator number in the Replacements compile tab (it is safe to remove it at that point because all of the counters have been evaluated to text).

So the basic idea is you have a tree like this:

Chapter Section Section Chapter Section

You compile, which adds $hn to all of these as a prefix:

1 Chapter 1.1 Section 1.2 Section 2 Chapter 2.1 Section

Okay, that’s all straight forward, we’re going to add the chapter numbering token as a title suffix in the Formatting pane, to the Formatting pane rows that generate chapter titles:


Okay, this is a compound placeholder: the <$custom:[meta-data key]> token will print the value of the like-named custom meta-data field for that item, which then becomes the “identifier” for this named counter instance. Thus, we can give our chapters a convenient shorthand for use in figures, right in the Inspector or Outliner (adding the “sectionName” column). This will then get used when you compile to generate the number. For example if we call our two example chapters Red and Black, we’d get the following prior to counter evaluation:

<$hn> Chapter%%<$n:chapter:Red>%% <$hn> Section <$hn> Section <$hn> Chapter%%<$n:chapter:Black>%% <$hn> Section

After counter evaluation:

1 Chapter%%1%% 1.1 Section 1.2 Section 2 Chapter%%2%% 2.1 Section

Okay, so now from anywhere in the book you can refer to the second chapter as <$n#chapter:Black> and it will evaluate to “2”, whether used in a figure caption in that chapter, or a cross-reference to that figure from another chapter entirely. We just need to strip out these temporary numbers from the chapter titles with a Replacement, and we’ll need to use Regular Expressions to be very specific about what we are removing. Copy and paste the following into the Replace field:


Leave the With field empty, and check off “RegEx”. This search pattern will look for only cases where digits are surrounded by double-percentage marks and remove the whole thing. Since the search pattern requires numerals in the middle, it will never replace the token itself (which consists of punctuation marks and letters). This is a concern because Replacements run more than once, and they make a sweep before tokens are evaluated so that you can use Replacements to modify placeholders or generate them. Thus we do not want it to find just anything between percentage marks, or it will remove the placeholder token before it gets a chance to generate the number. It generates the numbers, and then the next Replacement sweep finds it and removes it. Hopefully that all makes sense—we’re using a few esoteric loops in the compile process to sneak an ad hoc invisible counter in, and then making use of it in the source material.

The percentage markers themselves were an arbitrary choice, they are useful when working with RegEx since the percentage mark isn’t a dedicated search symbol (like “+” is). You can use whatever you want, but if you find the pattern stops working, try escaping the punctuation, like ++\d+++ which is messy and why I chose something simpler to read and error-check. :slight_smile:

Sorry for the huge info-dump, if any that requires more explanation, let me know. Here are some resources:

  • 24.18 Replacements, pg. 399.
  • 10.1.6 Custom Meta-Data, pg. 120.

Wow! Thank you so much for this very exhaustive answer! This again shows how flexible Srivener is and how powerful the Compile function is.

With these explanations and examples I was able to achieve what I need. So, in order for other people with similar questions to also benefit from this (and for my own documentation), I add here a short description of what I ended up with, including the last bits not described in your post:

What I wanted was hierarchical figure and table captions like this:

1 Chapter One
   1.1 First subsection in first chapter
         Text here and a table 1.1
         More text here and a table 1.2
   1.2 Second subsection in first chapter
         Also text here and a table 1.3
2 Chapter Two
   2.1 First subsection in chapter two
         Subsection text here with another table 2.1

Every time a table (or figure) occurs I need a number to reference it in the text, starting with the chapter number, followed by a dot, followed by a consecutive number starting from 1 in every chapter. This is a typical situation in scientific writing (for which I need this).

The tables will be numbered and identified using the custom counter <$n:tab:someID> and the figures will use the custom counter <$n:fig:someID> as explained in the Scrivener manual and Help menu.

Here is how:

  1. Tag the chapter/subsection headings with the <$hn> tag as a prefix in the compile settings (Formatting pane) for all levels for which this is wanted. Note: this is not mandatory for the caption numbering to work.

  2. Tag the chapter (and only those, not the subsections) headings with a custom <$n> tag as suffix in the compile settings (Formatting pane), adding some extra characters to later recognize these easily, like so: %%<$n:chapter:<$custom:sectionName>>%%

The keyword ‚chapter’ is the custom one, starting a custom auto-increment-number and you may choose another keyword here. The tag <$custom:sectionName> refers to a custom metadata entry for your documents. You can also use something else here (than ‚sectionName‘).

Also add the tag here to reset the custom counters for tables and figures when a new chapter starts, so the complete suffix line will look like this:

  1. Enter a unique ‚sectionName‘ metadata entry for every document/folder that represents a chapter.

  2. Add an entry to the Replacements in the Compile settings (Replacements pane), adding %%\d+%% in the Replace field, leaving the With field empty, and checking off the RegEx field. This will strip our chapter counter from the output so that it is not visible.

  3. Now, every time you insert a table in a document you will use something like this for the caption:

Table <$n#chapter:ONE>.<$n:tab:myTableWithData> Bla bla legend

and refer to this table in the text like this

for an explanation, see Table <$n#chapter:ONE>.<$n:tab:myTableWithData>.

The same goes for figures with the fig keyword. In this example, I entered ONE as the sectionName for the whole chapter, and used myTableWithData as the unique id for this particular table.

  1. Compile your document and enjoy. And big thanks to AmberV!


Thanks for posting your solution!

Hi, I followed the instruction above, but when compiling, the numbering for the second level and above does not reset. This is the result after compiling:

  1. Chapter One
    1.2. First level subsection
    1.3. First level subsection
    1.3.1. Second level subsection
  2. Chapter Two
    2.4. First level subsection
    2.5. First level subsection
    2.5.2. Second level subsection

How to make the subsection numbering to reset? Kindly help

Hi! Manage to get it worked! I added the <$hn> tag in the chapter prefix.

%%<$n:chapter:<$custom:sectionName>>%%<$rst_tab><$rst_fig>Chapter <$hn>


This is great and exactly what I need! I was wondering if you could provide a more explicit example. I’m getting a bit stuck. Does each chapter need both a UNIQUE chapter tag and ,section name’ tag? or just ,section name’?

For example, we’ll give chapter one the section name ‘dog’ and chapter two the section name ‘cat’. Would the code to tag that just be:


Or does the chapter part of that also need to be unique for each actual chapter?

Additionally, where do we add the ,section name’ meta data?

tberg & AmberV this is really awesome! Any additional examples, help you can provide will be so appreciated!

Hi this has been really helpful for me but I’m not quite there. I’m writing a technical handbook in a highly structured house style with sections, subsections, etc. I’ve got these instructions working fine for the numbering of figures and tables (Fig 2.3 for the third figure in chapter 2 etc) but also need to be able to cross reference to other parts of the text. What I have in mind is to be able write something like

“Refer to C<$n:chapter:ChapterTitleNoSpaces>.S<$n:section:SectionTitleNoSpaces>.<$n:subsection:SubsectionTitleNoSpaces> for further info”

(where chapter, section and subsection are custom placeholders) and have this compile to

“Refer to C3.4.1 for further info”

I’m struggling a bit with counters that are incrementing when they shouldn’t, but more fundamentally how to handle the subsections level (which may not always be present). If I try to create custom prefixes in the Compile dialog panel for level 2 documents, it seems to group documents by whether they have “children” rather than the actual level (i.e. a level 1 document without a child is given the same formatting as a level 2 document)

Any help gratefully received!


I have found a good way to provide numbering and cross referencing:

((((( In following, use text between -----> and <------)))))

For starters, set the formatting prefix to -----> %%<$n:sectNameAbbrev: <------
and suffix to -----> >%%<$rst_tab><$rst_fig>!3~<$hn>~~. <------

Note that in the title you should place an abbreviation for the section name. If you want to use a title instead, put the following into the prefix (leaving suffix blank).
-----> %%<$n:sectNameAbbrev:<$custom:sectionName>>%%<$rst_tab><$rst_fig>!3~<$hn>~~. <------

A little explanation. The ‘sectNameAbbrev’ is a ‘type’ of header so that the one marked with the ID given by the info after the ‘:’. In the first prefix format, that info comes from the title field. In the second it comes from the custom variable for the entry, the custom variable being named sectionName.
Further, there is a “!3~” in the second part of the string. Also, there is a “~~” at the end. Those, as well as the “%%”, all are used to mark find strings for ‘replacement’. Specifically, the “!3~” is used to indicate that the 3rd part of the hierarchical number is to be used for numbering the section. To accomplish this, I put a series of strings in for find and replace:
FIND REPLACE WITH (be sure to check RegEx)

“%%\d+%%” —><---- (nothing used)
!1~(\d+).(\d).(\d)(.(\d))~~ $1
(\d*).(\d).(\d).(\d).(\d).(\d).(\d).(\d)..~~ $2
!3~(\d+).(\d+).(\d+)(.(\d))..?~~ $3
(\d*).(\d).(\d).(\d).(\d)..~~ $4
!5~(\d+).(\d+).(\d+).(\d+).(\d+).(\d).(\d).(\d).(\d)..~~ $5

and so on. Note that the above shows irregularity to provide a couple of alternative structures. The main point is that you want to be sure to have actual digits where you want them, or the strategy breaks.

You can also wrap the find and replacement with some further replacement, so that you can get a string set like I. A. 1. a) i) .

Wow, thanks! I need to spend some time looking into that. The book in question is now submitted and in the end we left all this cross linking to the copy-editor but this looks useful for the next edition. Thanks again


I need to accomplish the exact same thing as the OP, but the solution shown in AmberV’s and tberg’s posts above does not seem to work in Scrivener 3. Is there a different way to do this now that there is no Formatting pane in the Compile dialog? When I enter the custom tags in the body of the text, Replace does not strip the %%\d+%% tag (yes, I checked RegEx), so that :

<$hn>Chapter %%<$n:chapter:<$custom:ONE>>%%<$rst_tab><$rst_fig>

evaluates to:

Chapter %%1%%

and a subsequent Table caption :

Table <$n#chapter:ONE>.<$n:tab:myTableWithData> Bla bla legend

evaluates as is, with all the code.

Thanks for any help.

Upon initial testing, it looks like unfortunately that part of the above technique may no longer work. Replacements had to be modified a bit to reduce instances whereby they would cycle repeatedly and duplicate themselves. We were using its repeating nature to our advantage in the v2 recipe, but now in v3, by the time the tokens are evaluated fully, all replacements are done.

There would be one last stop-gap, a tool that plain-text users could take advantage of with the Processing pane, where you can UNIX scripts against the compiled output (and thus do further replacements). But that’s not going to work for anything like native PDF or Word.

That aside, the basic idea still functions fine. It generates a sequence of hardcoded numbers you can refer to throughout the book. You’ll just have to find some other way to strip out the temporary codes from chapter titles after you compile—unless someone thinks of something I’m missing.

I did, by the way, also try using the technique of applying a compile format style to the temporary placeholder, with the intention of then setting that style to delete the text from it in its compile settings—but that also unfortunately happens before placeholders are evaluated. Rightly so, I would say. You typically wouldn’t want numbers incremented from text that is outright deleted. But it was worth a shot and would have made for a cleaner approach than regex.

Well that second part should be working fine, and does for me—though it perhaps deserves mention that <$custom:ONE>, as used for the chapter number itself, would then be referring to the custom metadata field named ONE. Given your usage of ONE as a value in the second example that doesn’t appear to be your intention. You would use the field name with the intention of extracting the value (ONE). Basically what happens there is that if you type ONE into a field named ChapterNumber, and then use <$n:chapter:<$custom:ChapterNumber>>, then internally that turns into <$n:chapter:ONE>, which is course basically what you use elsewhere to refer to that handle.

As to there being no Formatting pane—yeah, but all of what the Formatting pane did has been moved into the Section Layouts pane. A Layout is just like a row in the Formatting pane, only now it has a proper name and you can tell folders to use it by name, rather than having to hard code this stuff by type/level in the compile settings.

Might be worth going over the compile migration tutorial if you haven’t already.

Thanks Amber, got it to work now.

I wanted each equation in a given chapter (e.g. Chapter 1) to have this form: (1.1), (1.2), (1.3). I believe this was the OP’s goal too.

I achieved it by auto-numbering and then naming each chapter, and then doing the same for each equation within a chapter. Then when I wanted to refer to an equation with hierarchical notation, I did this:

Chapter <$n:chapter:$@Introduction>
[equation 1]	(<$n:chapter:$@Introduction>.<$n:equation:$@Euler1>) 

[equation 2]	(<$n:chapter:$@Introduction>.<$n:equation:$@Euler2>) 

And here is a hierarchical reference to Euler equation 1 from chapter 1, i.e. equation (<$n:chapter:$@Introduction>.<$n:equation:$@Euler1>) 

This method has the virtue that if I end up placing a preface before Chapter 1, all the equation numbers and references to them change as well, since all of these are auto-numbered and responsive to the auto-number placeholders that had come before.

I think this should suit my needs, and unless I’m missing something, I hope this might help others as well.