Help with linking placeholders


Many years later that this thread was started, I am having the same problem. Can anyone explain how to auto-number images with Chapter + Number?

In other words, I want to write “Fig. 1.1”, “Fig. 1.2”, etc., under my images in the first chapter of my book; “Fig. 2.1”, “Fig. 2.2”, etc., under my images in the second chapter in my book, and so on. How can this be accomplished?

Hi I’m not getting anywhere with this. Is there a way to use placeholders to link an in-text reference to a figure so they always have the same reference?

Picture attached which illustrate what I mean.

Cheers :smiley:

Hi Morgan,

I’ve been wondering what had happened to you, how you had got on. I’ve never had to do this, but I’m willing to spend time working it out. Mind you, there are others here who are much better placed to advise.

I suppose there are a couple of questions that need answers:

  • How do you want your graphics numbered? A simple number or hierarchically numbered based on chapter number?
  • Do you want the number to start again at 1 for each chapter, or to run consecutively throughout the thesis?



Not at a Mac right now to check, but I am pretty certain that under Help > List of all Placeholders, there is a guide that explains how to do this. Probably under figures and tables.

Slàinte mhòr.

EDIT: This?

Hi Mark,

Good to hear from you. I was swamped with my research. Managed to submit (phew!) so now trying to improve with Scrivener.

A simple number hierarchy sounds right. It could be chapter based (starting at x.1 for each chapter) or even just be non chapter based, being consecutively numbered from start to finish . The latter might be easier for now.

I’ve just read Jo’s message… It could have the solution there? I’ll give it a try and report back :slight_smile:

Glad you got it in and are continuing to work on it. JoRo’s answer gives you the key to creating a consecutive numbering system. Getting it to start at 1 for each chapter will require more tweaking.

I’ll take the opportunity to play around with it.



Yes - thanks JoRo - I managed to make it work. Really helpful.

Haha - thanks Mark. Let me know how the tweaking goes :slight_smile: :slight_smile:

Easier Numbering

If you started with one of our non-fiction templates, you may have some “macros” built into the compile settings that can help you out with this. To check:

  1. Open File ▸ Compile...
  2. Double-click on the selected compile Format in the left sidebar to edit it.
  3. Click on the “Replacements” pane. If you’re set up for them, you’ll see a few cryptic looking lines in here. These make it so you don’t have to worry about the numbering placeholder syntax directly, and can instead more clearly type in just the identifier you want to use for the figure.

How to use them is described in the help file provided at the top of the template’s binder, but it’s quite simple: #fig(name of counter) creates a reference pointing to the spot where !fig(name of counter) is set. Both of these codes will print the figure number associated with that image.

If you don’t have these replacement links, copy the following code and paste it into your Replacements table:


This is flexible of course. The “!fig(stuff)” part could be changed to something even simpler, like “{” and “}”, so all you type into the editor is “{stuff}”, and then elsewhere type in “[stuff]” to refer to that number in cross-references—like so:


Restarting Numbering

A simple number hierarchy sounds right. It could be chapter based (starting at x.1 for each chapter) or even just be non chapter based, being consecutively numbered from start to finish . The latter might be easier for now.

To restart a numbering stream, insert the proper reset code into a place where the compiler will insert it as needed. A common tactic for doing that is into either the title prefix or suffix fields, in the Section Layout that generates the chapter break:

This code will reset the "figure" numbering stream.

But if you do that, then cross-references become more complex in that you need to refer not only to the figure number but the chapter it came from, like 21.3, which would be the third figure in chapter 21. That’s possible to do with Scrivener, but indeed it is a lot easier to just number them sequentially. Let’s return to that topic after looking into the replacement a bit further.

Keeping Output Agile

This method highlights one advantage to using an intermediate syntax instead of the numbering codes directly in the editor: if you change your mind about the implementation, then all you need to change is the one Replacement that governs how the hundreds of individual “!fig(stuff)” codes work in your text, all at once. (187.4 KB)

Here’s a simple example (see attached project for starting point). Let’s say you get tired of typing in "Fig. !fig(stuff): " in front of every single caption. Indeed, if you are doing that, it’s a strong argument for not typing this in manually over and over, and instead having the Replacement generate the static text around the number:

  1. First compile the project to see how the codes I’ve added into the two sample chapters work normally. They print a number where you use the code, meaning we need to add any embellishing text ourselves at the moment.

  2. Open the compiler and edit the “Example Numbering” compile format, and go into the Replacements pane. The With field is what the simple codes will be converted into. The “$@” symbol means first: select everything in between the text around the symbol and save it; and secondly, print the saved text into this spot. So we capture the “name_of_figure” text from “!fig(name_of_figure)”, and then insert it into “<$n:figure:name_of_figure>”, which prints “2” or whatever.

  3. So if we want the Replacement to print “Fig. 2:” so that we only need to type in the simple code and then the caption, change the With field to:

    Fig. <$n:figure:$@>:
  4. Click the Test... button and examine the two captions in the output PDF.

  5. Now that we know how to do that, we can also change the cross-references as well:

    Figure <$n#figure:$@>

The “Example Numbering - Custom” compile format in that sample project demonstrates the above two changes.

Chapter Numbering with Reset

To proceed with the demonstration, first implement a chapter break numbering reset as described above:

  1. Edit the compile format again, and this time go into the Section Layouts pane. Select “Heading & Text”, and then click on the “Title Options” tab.

  2. Type the following into the suffix field:


    As you might suspect, this can be done for any named number stream. We’ve been using one called <$n:figure:your_token>, so we put “figure” into the reset code.

    Give that a test compile. You should now get “1” for both example figures since they are each in their own chapter. Of course now we have an ambiguous result since two figures are “1”. We need “1.1” and “2.1” for these cross-references to make sense across chapters.

  3. Well firstly we need to number our chapters. :slight_smile: Click over into the Prefix field, and add the following:


    So this one is a little special. There are two codes, the inner one will be evaluated by the compiler first, printing the name of the chapter into this spot, making a code like this: “<$n:chapter:Firstexample>”, which then gets turned into a number.

  4. We could at this point paste that same placeholder into the Replacement designed to print captions. With this simple project structure, where each file is one chapter, from the “perspective” of both the heading and the captions, the title of this document is a suitable common identifier. But there is a problem with that assumption, let’s test it out. First go ahead and add the chapter numbering code to the !fig Replacement:

    Fig. <$n#chapter:<$title_no_spaces>>.<$n:figure:$@>:

    Save the compile Format and run a test compile to examine the result. The captions should be working well! You now have Figure 1.1 and Figure 2.1. Of course the cross-references won’t work yet, but one thing at a time.

This approach isn’t very flexible however. To demonstrate, open the Research folder in the example project binder and drag the “Third example” file on top of the “Second example” file, nesting it beneath. Our “chapter” now has subsections. We won’t worry about numbering and formatting that for now, we just want to make sure we get a “Fig. 2.2” because it is the second illustration in the chapter. So compile and see how it goes.

We get a broken token on the third illustration because we are requesting a chapter number that doesn’t exist, the “Thirdexample” number—it is pulling the title from the document the placeholder is found within, naturally. We need to somehow get the chapter number no matter how deeply nested the figure caption may be.

This is where the <$levelN_title_no_spaces> placeholder comes in handy. From no matter where within the chapter we use that placeholder, it will extract the title from that level of the outline, rather than using the current document (“Third example”). So try this in your replacements field:

Fig. <$n#chapter:<$level1_title_no_spaces>>.<$n:figure:$@>:

Much better!

Debugging Placeholders

This is a useful spot to make mention of a good trick for figuring out why things aren’t working the way you want. With our prior example, the failure was obvious as there was no chapter number identified as “Thirdexample” and the placeholder just broke. Sometimes the fail result will be a number—for example if we had used the less safe “<$n:chapter:etc>” instead of “<$n#chapter:etc>”, then our compiled result would have been “Fig. 3.2”, as it would have see “Thirdexample” hadn’t been used yet, and would have incremented the chapter number counter to 3.

If you didn’t know all of the above yet, it might be entirely mysterious as to why you get “3” instead of “2”. A way of probing into what a compound placeholder is doing is with a backslash in front of the placeholder. Here’s an example compiled result from putting a backslash in front of the chapter number placeholder in the Replacement pane:

Fig. \<$n#chapter:Thirdexample>.1

Since we didn’t backslash the interior placeholder, we can see what it evaluates to (“Thirdexample”) and know from that we have the wrong target, as the current chapter should be “Secondexample”. The “.1” on the end is the figure numbering placeholder, we didn’t escape that one either.


So long as we have a stable outline level to consider a chapter, we pretty much have the caption problem solved. Now we need to somehow get that full chapterNum.figureNum sequence printed in other documents.

The best way to do this will be to combine two different techniques together:

  1. First, go back into the compile format and change the cross-reference figure Replacement (the #fig variant) to the following and give that a test compile:

    Figure <$n#chapter:<$level1_title_no_spaces>>.<$n#figure:$@>

    We’re using something pretty much the same as the caption number itself. You’ll note that references pointing to a figure in the same chapter will work as expected. It’s the second reference in the “Second example” document that fails, printing “Figure 2.1” instead of “Figure 1.1”. That’s because <$level1_title_no_spaces> evaluates to “Secondexample” in both cases. We need to somehow get the cross-reference to have “Firstexample” in it. Feel free to use the backslash technique here to keep an eye on what happens underneath the surface, if you wish.

  2. To answer this problem we’ll need to step out of the compiler, so save your settings and return to “Second example” in the project window. Locate the “#fig(test)” example and select the placeholder text completely.

  3. Drag the “First example” chapter, from which this figure comes, and drop it onto the selected text in the editor, forming a link from the placeholder to the target.

  4. Run a quick test compile. And now the cross-chapter reference prints correctly, as “1.1”.

If you used the backslash trick on the chapter placeholder, you’ll see the difference in these two #fig(…) placeholders:

Refer to Figure \<$n#chapter:Secondexample>.1.


Refer to Figure \<$n#chapter:Firstexample>.1.

So the hyperlink directs all placeholders that are document-specific to use the link target’s data instead of the document the placeholder is found within. This approach is ignored by placeholders that produce static numbers, so the link has no detrimental effect on them. It is something to be aware of however, if you use other placeholders that are document specific and wrap the whole thing into a Replacement macro with a hyperlink on it, then you’ll end up pulling all metadata within that replacement from the target.

And, since we’re using the levelN approach for our target, the target figure’s binder item can be as many levels deep as it needs to be. The hyperlink points the placeholder to this subsubsection and then from that context the level1 title is whatever chapter file is at the top, for it, not the original.

The “Numbering - Chapter Restarts” compile Format has all of the above modifications made to it, for your reference (sans the hyperlink of course).


So one important thing to reiterate at this point is that, with the exception of the link, all of the above adjustment and even radical alterations, were done without a single adjustment to the source material in your editor. We maintain a very simple numbering/referencing macro in the editor, and precisely how that ends up working is down up to the compile format.

Hopefully the above tutorial provides enough background into what is being done, to make suitable alterations to it, but if I didn’t explain something well enough, let me know!

1 Like


I have a problem with the auto-numbering of figures in Scrivener. I can’t figure out what is going on, I would very much appreciate if anyone can help.

I am using the following replacements during compiling:
!fig($@) --> replace with: <$n:figure:$@>
!ch($@) --> replace with: <$n:chapter:$@>

And I have this list of figures in the body of the text to be compiled:
Figure !ch(ch3).!fig(fig1). Title
Figure !ch(ch3).!fig(fig2). Title
Figure !ch(ch3).!fig(fig3). Title
Figure !ch(ch3).!fig(fig4). Title
Figure !ch(ch3).!fig(fig5). Title
Figure !ch(ch3).!fig(fig6). Title
Figure !ch(ch3).!fig(fig7). Title
Figure !ch(ch3).!fig(fig8). Title
Figure !ch(ch3).!fig(fig9). Title
Figure !ch(ch3).!fig(fig10). Title
Figure !ch(ch3).!fig(fig11). Title

When I compile for Microsoft Word or for PDF, for example, no matter what I do, even if the text above is the only section of text I compile, the result is the following, with a jumbled arrangement of figure numbers.
Figure 3.1. Title
Figure 3.2. Title
Figure 3.3. Title
Figure 3.4. Title
Figure 3.6. Title
Figure 3.7. Title
Figure 3.8. Title
Figure 3.5. Title
Figure 3.1. Title
Figure 3.2. Title
Figure 3.3. Title

The result skips figure 5, introduces it later, and then restarts from figure 1. What am I doing wrong?


This section is for passing on tips rather than asking for technical support, so you might be better off starting a new thread in the appropriate section of the forum. I note that the previous question did not receive a reply, perhaps because it was in the wrong place.

I’ve merged your question with a thread that explains how to accomplish what you’re looking to do. Scroll up to the long post above yours, where you will find an example project and detailed explanations for how it all works.

@AmberV, I like your workflow very much. However, I am having problems implementing the backslash command

From this replacement command in compile>edit format>replacements


the compilation process leaves me with this:

(help me out in another matter. whats the difference between colon and # in such kind of commands. Superficially they seem to do the same ?) >> edit: Answer is that the colon is for define a label and # for referencing that label, even in a place in a text ’ before’ it is defined. correct so far?

Thanks for pointing out that error, I have edited the post to remove the backslashes from the code sample.

In Scrivener you can put a backslash in front of any placeholder to print that placeholder literally, instead of having the placeholder evaluated. In this way one could effectively write about using Scrivener’s placeholders without having their examples turn into numbers or whatever. :slight_smile: If you really need a blackslash in front of the value, then use two of them, to “escape the escape character”.

AmberV, I think - because of my bad reading - we missunderstood each other. I was looking to implement the solution to referencing a figure - say the first figure in chapter 3, so figure 3.1 - in another chapter (e.g. chapter five) thereby trying to prevent it from changing towards 5.1.

You say I need to drag the document (the on in chapter 3) from the binder into that document that will be part of chapter 5? I am so unsure how to this since I am planning to have replacements like this

!fig($@) for <$n:chapter:<$level1_title_no_spaces>>.<$n:fig:$@>
!fig-($@) for <$n#chapter:<$level1_title_no_spaces>>.<$n#fig:$@>

How I am to do this? Thank you very much for your help.

If you’re asking about how to create and work with links in general, then refer to §10.1.1, Creating Internal Links. There are a variety of different methods you can use, drag and drop is merely one of them.

The important thing to know is that:

  • Linked placeholders pull information from the link target rather than the document they are found within.
  • Replacements modify the text of the link so that it becomes a placeholder, meaning you can link to friendly text than the full placeholder to get this effect.

The rest is entirely up to you. Use drag and drop, use right-click and drill down to the chapter three item via the Document Link submenu, use ⌘L and the “Link to Existing Document” tab—whatever works best for you.

Hej there, I was about to write back that I dont understand you (which I partly still dont) when I found one answer in the manual section you pointed me to.

If take a placeholder like <n:chapter…> that gives me the chapter number, it will always show the chapter it is actually in. So If i want to refer to my figure 1.1 in chapter 3 - using your code suggestion - I actually have to link that one to that other chapter. allright.

(I wonder why there is not an actual link created, but this must be because I compile with scrivomatic?)

It’s better not to think of them as links in a cross-referencing sense, but a feature that you are using in combination with another feature (placeholders) to produce an effect that has nothing to do with links. Therefore the link is removed, just like the placeholder itself is removed. Both are removed, and become “23.2” or whatever you need.

I’ve spent a lot of time learning about Scrivener and this is the best thread regarding automated numbering of Tables and Figures , The Best
and yet - a Project template containing all these settings is lacking , it is sorely needed - the other stuff on the web is megre
thanks Amber

There is no project template for a Thesis because there are simply too many variations. All Scrivener templates are is a blank project, built up a bit with some starter files and ideas that you can discard or amplify at will, and in some cases, compile settings. They are intended as a quick way of getting some preliminary content and settings defined in a new project.

However, the Non-Fiction category contains some templates that may be suitable as a starting point for a thesis. I would suggest creating a test project from each of the templates there, then seeing which is the closest match to your needs, then customizing it further according to your specific requirements.

Hi Kazz ~ thanks for responding

I hold a different view. While there are templates in the non-fiction category, mentally and practically, having a template labelled “Thesis” would be like a life ring to a person who thinks they are going to drown.
Pre-loaded with Section Types of Chapter/ Chapter Subsection / Figure / Table (that auto number when compiled) would be a salve to someone who is already hearing from all those around them that “they used Word” ,
Scrivener is just so much better than all the rest - however I have spent countless hours (likely hundreds) learning how to use it because I got ‘glitched’ whenever I saw “scene” , (and being obsessive, I’d change that , and that would lead me down a series of ramifications that altered things somewhere , you get the picture)
The template could be super simple , all (most all) theses have the structure above and the less the novice has to tinker with and ‘upset’ how well Scrivener can work - more folk would be on board
All the best, Justin