I have created a new project in Scrivener 3 using the blank template.
It contains one file in Draft, called Scene, and another file in Research, called Boilerplate.
Scene contains some markdown and an include tag that references Boilerplate:
Boilerplate also includes some markdown:
When I compile using MultiMarkdown > Web Page, both the Scene text and the Boilerplate text are converted properly: italics, bold, and hyperlinks.
When I compile using PDF, RTF, ePUB, or any other format, the Scene text is converted properly, but the included Boilerplate text is left as raw markdown.
I have tried moving the boilerplate text into the draft folder, but the issue remains the same. Compiled to HTML, the markdown pulled from the <$include> tag converts properly, but remains as raw markdown when compiled to any other format.
Hmm . . . I’m afraid I can’t help you then. I never use include tags so I don’t know how they behave exactly. But I’m interested in hearing the full answer! I’m sure a more knowledgeable other person will be able to help you soon.
Hmm, yes it looks like inclusion happens toward the end of the compile process, after documents themselves have been processed to RTF. So if a document never was processed, then the raw text is what you get.
It might be an oversight, I’ll check. There are as you can imagine some labyrinthian conditions where it comes to these placeholders.
As for using the MMD compile formats themselves however—it doesn’t matter what order any of this is done in since Scrivener doesn’t actually do any conversion in this case. All of your Markdown text is pass through the MMD engine and converted no mater when or where it gets included.
Thanks, again. And the <$include> does work for compiled HTML even if the referenced file is in the research folder, but not for other formats.
This <$include> behaviour is new to S3. It promises to be very useful for repeated text, such as bios or advisories that need to appear in multiple documents. Saves copying and pasting and keeping in sync if only one master file is ever needed.
Thanks, Ioa. Yes, logic suggests it is something to do with the compile sequence. Clearly works in HTML, so hopefully it will be possible for other compile formats as well. Be interesting to hear Keith’s insight.
Do you mean when compiled to MMD->HTML? Because if so then that method doesn’t rely upon Scrivener to convert the MultiMarkdown to RTF internally—that would in fact mess it up. It does that for its own formats, like ePub and the HTML option up next to ePub, etc. For all of those options below the “MultiMarkdown” entry, Scrivener just assembles the text together as plain text and passes that result to MultiMarkdown, which then produces HTML or whatever.
It can be quite useful indeed! I just did a quick search and I used it over a hundred times in the user manual. Sometimes the way a menu command is described would be inserted into a bullet list elsewhere, where a group of menu commands are documented together. Sometimes a group of closely related preference panes would have a common “See Also” list they all share, that sort of stuff.
I have fixed this for the next update, but the <$include> tag will always have certain limitations. For instance, Scrivener won’t be able to convert Markdown for text files that are stored externally and included - it can only do this for text files stored in the project itself.
Yes, MMD > HTML works. The separate compile to Web Page serves the <$include> text as raw markdown. Apologies for not being clear about this originally. I am mainly hoping to get the <$include> to work for output to ePub and Kindle, when the included file has markdown in it. Your explanation helps to explain the compile sequence. Wonder if it can/will be tweaked to work as I hope.
I think it is a significant S3 feature. Makes managing repeated text so much easier. One master file for boilerplate copyright info, another for a biography, etc.
Hadn’t even thought about linking to an external file. Will have to experiment, especially to see what formatting an external <$include> file does take on.
If you need formatting, then use RTF. TextEdit would work for that, but so would even Scrivener and then exporting the file from the binder. Pages isn’t much use as a format to anything but Pages. Apple never released the specs.
TXT if you don’t need formatting and want to ensure the injected text takes on whatever local formatting is around the injection point. Also if you’re using Markdown for that then TXT would work best.
The details of how all of this works—with regards to how styles are treated, formatting, compiling stage format overrides, and so on—are in §10.1.5, starting on pg. 208.
Given the flexibility, there aren’t a few simple rules. If you insert a plain-text snippet into an inspector footnote for example, something different is going to happen than if you import a ten page RTF file from somewhere.
Keith, above, says “Scrivener won’t be able to convert Markdown for text files that are stored externally”, but are you saying markdown is okay?
I have added an <$include> tag, selected it, and then chosen Edit > Add Link to link to a test RTF file on my desktop. I can’t get that to compile. I also tried <$include:/Users/username/Desktop/RTF.rtf>, but that doesn’t compile either.
<$img:/Users/username/Desktop/sample.jpg> does work for an image, so I assumed a file would work in the same away.
To clarify, I am thinking in terms of that MMD->HTML compile format. Again with that, it doesn’t matter how the text ends up as Markdown syntax with those formats. Scrivener passes along the whole compiled .txt file to the MultiMarkdown engine intact, and then it is responsible for making HTML out of it. So it doesn’t matter if your text comes from a .txt file, or from inside of a synopsis card, or a a custom meta-data field—it’s all valid formatted text because all you need to make valid formatted Markdown text is punctuation marks. No conversion necessary.
The linked method only works for binder items.
On the example you tried, I’m not sure why that isn’t working for you. I’ve tested both relative and absolute paths to files and both include fine. The only thing that doesn’t work is the UNIX ~ shorthand.
