Include Tag Processing

The sample project attached has two text files in the draft folder.

Both of these files have <$include:filename> tags that reference three texts stored in the research folder.

The first text file in the draft folder has no additional text after the include tags. When compiled (to PDF, RTF, etc), only the first include tag is processed.

The second text file in the draft folder has some additional text after the include tags. When compiled (to PDF, RTF, etc), all three include tags are processed.

The very strange thing here is that if the additional text is shortened, only one or two – depending on the length of the additional text – of the include tags are processed.

Is this a bug?

Include.pdf (23.4 KB) (53.4 KB)

Yeah it does look like there is something odd thereabouts. I also tried using the document link format instead of referring to section types by name in the placeholder, and still got the same result. I suppose I’ve never come across this one because I either use it as the sole content of the file (acting more like a proxy for the original item) or embedded within a much longer document as a short phrase.

I’ll make sure Keith gets these results, thanks!

Thanks, Ioa.

Just as an FYI, the issue started here: … =2&t=52823

Which led to here:


I replicated the issue (having previously only used include tags as you describe) and then posted this thread.

Be good if it could be made to work for the other poster or for anyone else in the future.


Thank you @Jo for raising this as a bug. I appreciate it. Hope this gets fixed in the next update.


Fixed for 3.0.4. (There’s a bug in the code whereby the search range isn’t being updated to account for the fact that there is now more text after the replacement, so it stops searching.)


Thank you for fixing it in 3.04 version. When do you plan to release that version?

Also, is it possible to expand these $include and variables in general before compile time? I want to display this information in composition mode. Is it possible? It would be very helpful, if I can see expanded document before compilation.

Thank you!


I’m afraid I cannot say exactly when 3.0.4 will be released as there are a number of things that still need doing in that version before it is ready.

It is not possible to expand these tags before Compile time, no - these tags are specific to Compile. It would be impossible to have the text from other documents, or even from external files, appearing inside documents for live editing.

All the best,

This is in large part why I prefer using the document link format for these. If I need to look up the original text I can simply click on the linked <$include> tag. I’ll also sometimes “comment” the link by putting a short inline annotation after it, describing what will be included. Another side benefit for linking is that you by default get a backlink, meaning all included items will have a list of those documents that use their content, in the Document Bookmarks inspector tab.


That would work. Only one issue though. In composition mode when I am in document 1 and click on a link inside it to document 2. How do I go back to document 1? Previous/next document shortcut (option+cmd+up or down arrow would not work because the included document is in another folder. Is there a shortcut for editor back button? Can I add such a keyboard shortcut like other shortcuts I have? I don’t see it in the menu item.


Definitely! The shortcuts are the same as in many Web browsers: ⌘[ and ⌘] for Back and Forward, respectively. The commands are in the Navigate ▸ Editor ▸ submenu; while there also note there are shortcuts for triggering history navigation in the other split, which may be of use if you prefer link settings that load the linked item in the other editor (not applicable to Composition mode of course).

Composition Mode uses its own history queue (much like each editor split has its own queue), which is built up while you use a session, and abandoned once you leave it.

Brilliant. thank you!

I just ran into this issue this morning! Yesterday was my first time learning about the <$include> tag, and I was so excited to use it for my grant-writing because different grants call for different elements of the same copy that I have split across several documents. Being able to plug-and-play would be so helpful. When can I expect this patch?

I’d really appreciate some help as I have some include tags driving me crazy.

In my document (link below) there are six include tags that link to documents within the Scrivener file.

  1. <$include:Unproofed>
  2. <$include:Typed feedback>
  3. <$include:Fleur Lewis>
  4. <$include:Steven Lewis>
  5. <$include:Kathyn Hellewell>
  6. <$include:Laura Ferguson>

I believe I set them all up the same way but only one that works during compile is (2).

I write my documents in markdown so I compile from Markdown to Word. This creates fantastic Word documents. (I’m grateful every day for Scrivener and Markdown.)

I won’t bore you with why include tags are so important to our documents because I’m sure lots of us are in the same boat. Suffice it to say, this document is from a template we use daily, so it would be wonderful if it worked.

Anyone who could show me what I’m doing wrong would be a godsend.

The document:…zip?dl=1

Flummoxed me. Think you need Keith or Ioa to read and respond to this thread, or to contact tech support.

Be very interested to know the final solution…

Slàinte mhòr.

This is a subtle problem. When you’re using the approach of supplying a binder title name to include, it will start scanning from the very top of the binder and stop when it hits the first document that matches the name between the “:” and closing “>” character. In your case, that means including the document that is doing the including, since it has the same name. The reason “Typed feedback” includes correctly is because it is the first document in the binder with that name (the other is “Typed feedback only”).

So in fact, I’m pretty sure it is working just fine! :slight_smile: The results however make it look as though it isn’t working, because it is including the text of first “Unproofed” document, which of course contains a placeholder for including the text of the first “Unproofed” document, which of course contains a placehol…. That would go on forever naturally, causing compile to hang, so you’ve probably triggered the safety feature that breaks circular includes like this.

A good solution to this would be to rename the bio files, particularly if they are only ever used to insert data into what you are compiling. Naming conventions can make search results clearer, as well as the token itself. Once the items have been renamed, you can select all of these links from the include placehoders, right-click and use the “Update Links to use Target Titles” command.

Got to try that when I am back at a Mac. Thanks, Ioa.

Slàinte mhòr.


Slàinte mhòr. (197 KB)

There was never any serious doubt in my mind that it was me, not the second love of my life, Scrivener! :smiley:

A perfect solution, thank you so much, AmberV.